Scans API

Cree, gestione y monitoree escaneos de vulnerabilidades de forma programática.

Endpoints

Método	Endpoint	Descripción
GET	/api/v1/scans	Listar todos los escaneos
POST	/api/v1/scans	Crear un nuevo escaneo
GET	/api/v1/scans/{id}	Obtener detalles de escaneo
DELETE	/api/v1/scans/{id}	Cancelar/eliminar escaneo
GET	/api/v1/scans/{id}/findings	Obtener hallazgos de escaneo

Listar Escaneos

Recupere todos los escaneos de su organización.

GET /api/v1/scans

Parámetros de Consulta

Parámetro	Tipo	Descripción
page	integer	Número de página (predeterminado: 1)
per_page	integer	Elementos por página (predeterminado: 20, máx: 100)
status	string	Filtrar por estado: pending, running, completed, failed
target	string	Filtrar por dominio objetivo
from_date	string	Filtrar escaneos después de fecha (ISO 8601)
to_date	string	Filtrar escaneos antes de fecha (ISO 8601)

Respuesta

{
  "items": [
    {
      "id": "scan_abc123",
      "target": "example.com",
      "scan_type": "full",
      "status": "completed",
      "progress": 100,
      "phase": "complete",
      "created_at": "2025-12-21T10:00:00Z",
      "completed_at": "2025-12-21T10:45:00Z",
      "vulnerabilities_found": 12,
      "critical_count": 1,
      "high_count": 3,
      "medium_count": 5,
      "low_count": 3
    }
  ],
  "total": 45,
  "page": 1,
  "per_page": 20,
  "pages": 3
}

Crear Escaneo

Inicie un nuevo escaneo de vulnerabilidades.

POST /api/v1/scans
Content-Type: application/json

Cuerpo de Solicitud

{
  "target": "example.com",
  "scan_type": "full",
  "frameworks": ["soc2", "pci-dss"],
  "ports": "1-1000",
  "authorized": true
}

Parámetros

Campo	Tipo	Requerido	Descripción
target	string	Sí	Dominio, IP o rango CIDR
scan_type	string	No	quick, full, o compliance (predeterminado: full)
frameworks	array	No	Frameworks de cumplimiento a verificar
ports	string	No	Rango de puertos (predeterminado: puertos comunes)
authorized	boolean	Sí	Certificación de autorización de escaneo

Tipos de Escaneo

Tipo	Duración	Cobertura
quick	5-10 min	Principales vulnerabilidades, puertos comunes
full	30-60 min	Las 11 fases, cobertura completa
compliance	15-30 min	Verificaciones específicas de framework

Respuesta

{
  "id": "scan_xyz789",
  "target": "example.com",
  "scan_type": "full",
  "status": "pending",
  "created_at": "2025-12-21T14:00:00Z",
  "estimated_duration": 2700
}

Obtener Detalles de Escaneo

Recupere detalles de un escaneo específico.

GET /api/v1/scans/{scan_id}

Respuesta

{
  "id": "scan_abc123",
  "target": "example.com",
  "scan_type": "full",
  "status": "running",
  "progress": 45,
  "phase": "vulnerability_scanning",
  "current_tool": "nuclei",
  "created_at": "2025-12-21T10:00:00Z",
  "started_at": "2025-12-21T10:01:00Z",
  "phases_completed": [
    "discovery",
    "enumeration"
  ],
  "phases_remaining": [
    "vulnerability_scanning",
    "web_analysis",
    "cloud_analysis",
    "threat_intelligence",
    "correlation",
    "ai_analysis",
    "remediation_planning",
    "reporting"
  ]
}

Cancelar Escaneo

Detenga un escaneo en ejecución.

DELETE /api/v1/scans/{scan_id}

Respuesta

{
  "id": "scan_abc123",
  "status": "cancelled",
  "message": "Scan cancelled successfully"
}

Obtener Hallazgos de Escaneo

Recupere vulnerabilidades encontradas durante un escaneo.

GET /api/v1/scans/{scan_id}/findings

Parámetros de Consulta

Parámetro	Tipo	Descripción
severity	string	Filtrar: critical, high, medium, low, info
status	string	Filtrar: open, in_progress, resolved, false_positive

Respuesta

{
  "items": [
    {
      "id": "finding_123",
      "title": "SQL Injection in Login Form",
      "severity": "critical",
      "cvss_score": 9.8,
      "status": "open",
      "tool": "sqlmap",
      "affected_component": "https://example.com/login",
      "description": "...",
      "remediation": "...",
      "cve_ids": ["CVE-2024-1234"],
      "detected_at": "2025-12-21T10:30:00Z"
    }
  ],
  "total": 12
}

Cuota de Escaneos

Verifique la cuota de escaneos restante.

GET /api/v1/scans/quota

Respuesta

{
  "plan": "professional",
  "monthly_limit": 150,
  "used_this_month": 45,
  "remaining": 105,
  "resets_at": "2026-01-01T00:00:00Z"
}

Escaneos Programados

Professional y Enterprise

Los escaneos programados están disponibles en los planes Professional y Enterprise.

Crear Programación

POST /api/v1/scans/schedules
Content-Type: application/json

{
  "target": "example.com",
  "scan_type": "full",
  "frequency": "weekly",
  "day_of_week": 1,
  "hour": 2,
  "timezone": "UTC"
}

Listar Programaciones

GET /api/v1/scans/schedules

Eliminar Programación

DELETE /api/v1/scans/schedules/{schedule_id}

Webhooks para Escaneos

Regístrese para recibir notificaciones de eventos de escaneo:

POST /api/v1/webhooks
Content-Type: application/json

{
  "url": "https://your-server.com/webhook",
  "events": [
    "scan.started",
    "scan.completed",
    "scan.failed",
    "vulnerability.critical"
  ]
}

Límites de Tasa

Plan	Escaneos Concurrentes	Escaneos/Mes
Startup	1	25
Professional	3	150
Enterprise	Ilimitado	Ilimitado