Resultados y estado de análisis

Siga el progreso de los análisis, obtenga los hallazgos y comprenda el ciclo de vida completo desde el envío hasta la finalización.

Ciclo de vida del estado

Cada análisis pasa por un conjunto de estados bien definidos:

                    ┌──────────┐
    POST /scans ──→ │  queued  │
                    └────┬─────┘
                         │
                    ┌────▼─────┐
                    │ running  │──── POST /:id/cancel ──→ cancelled
                    └────┬─────┘
                         │
              ┌──────────┼──────────┐
              │                     │
        ┌─────▼──────┐      ┌──────▼─────┐
        │ completed  │      │   failed   │
        └────────────┘      └────────────┘

Estado	Descripción	Resultados disponibles	Terminal
queued	Solicitud aceptada, esperando capacidad	No	No
running	El escáner está ejecutando activamente	No (progreso parcial disponible)	No
completed	Análisis terminado exitosamente	Sí	Sí
failed	Error fatal encontrado	Detalles del error disponibles	Sí
cancelled	Cancelado por el usuario	Resultados parciales posibles	Sí

Verificar el estado

Endpoint

GET /api/v1/scans/:scanId

Alcance requerido: scans:read

Parámetros de consulta

Parámetro	Tipo	Predeterminado	Descripción
scanType	string	nmap	El tipo de motor (debe coincidir con el análisis original)

Solicitud

curl -X GET "https://api.cert-ix.com/scan-api/api/v1/scans/$SCAN_ID?scanType=nmap" \
  -H "X-API-Key: $CERTIX_API_KEY"

Respuesta — En progreso

{
  "success": true,
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "scanType": "nmap",
    "name": "Auditoría de red semanal",
    "target": "example.com",
    "status": "running",
    "progress": 67,
    "createdAt": "2026-03-06T10:00:00Z",
    "startedAt": "2026-03-06T10:00:02Z"
  }
}

Respuesta — Completado

{
  "success": true,
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "scanType": "nmap",
    "status": "completed",
    "progress": 100,
    "resultCount": 12,
    "durationMs": 135000,
    "createdAt": "2026-03-06T10:00:00Z",
    "startedAt": "2026-03-06T10:00:02Z",
    "completedAt": "2026-03-06T10:02:15Z"
  }
}

Importante — Parámetro scanType

Siempre pase el parámetro scanType correcto correspondiente al motor usado durante la creación. El predeterminado es nmap, por lo que si su análisis usó zap, debe especificar ?scanType=zap o obtendrá un error 404 SCAN_NOT_FOUND.

Obtener resultados

Una vez que el estado sea completed, los resultados completos están disponibles.

Endpoint

GET /api/v1/scans/:scanId/results

Alcance requerido: results:read

Solicitud

curl -X GET "https://api.cert-ix.com/scan-api/api/v1/scans/$SCAN_ID/results?scanType=nmap" \
  -H "X-API-Key: $CERTIX_API_KEY"

Esquemas de resultados por motor

Resultados Nmap

{
  "hosts": [
    {
      "ip": "93.184.216.34",
      "hostname": "example.com",
      "state": "up",
      "os": { "name": "Linux", "version": "5.x", "accuracy": 95 },
      "ports": [
        {
          "port": 80, "protocol": "tcp", "state": "open",
          "service": "http", "version": "nginx 1.25.4"
        }
      ]
    }
  ],
  "stats": { "hostsUp": 1, "openPorts": 2, "closedPorts": 1022 }
}

Resultados ZAP

{
  "alerts": [
    {
      "name": "Cross-Site Scripting (Reflejado)",
      "risk": "High",
      "confidence": "Medium",
      "cweid": 79,
      "instances": [
        { "uri": "https://app.example.com/search", "method": "GET", "param": "q" }
      ]
    }
  ],
  "summary": { "high": 2, "medium": 5, "low": 12, "informational": 8, "total": 27 }
}

Resultados Trivy

{
  "vulnerabilities": [
    {
      "vulnerabilityID": "CVE-2024-1234",
      "pkgName": "openssl",
      "installedVersion": "3.0.11",
      "fixedVersion": "3.0.13",
      "severity": "CRITICAL",
      "title": "OpenSSL: Desbordamiento de búfer en verificación de certificado X.509",
      "cvss": { "nvd": { "v3Score": 9.8 } }
    }
  ],
  "summary": { "critical": 1, "high": 3, "medium": 7, "low": 2, "total": 13 }
}

Resultados Nuclei

{
  "findings": [
    {
      "templateId": "CVE-2023-44487",
      "name": "Ataque HTTP/2 Rapid Reset",
      "severity": "high",
      "host": "https://api.example.com",
      "tags": ["cve", "cve2023", "dos", "http2"]
    }
  ],
  "summary": { "critical": 0, "high": 1, "medium": 3, "low": 5, "info": 12, "total": 21 }
}

Resultados theHarvester

{
  "emails": ["[email protected]", "[email protected]"],
  "subdomains": ["www.example.com", "mail.example.com", "api.example.com"],
  "ips": ["93.184.216.34"],
  "summary": { "emailsFound": 2, "subdomainsFound": 3, "ipsFound": 1 }
}

Resultados Sentinel

{
  "overallRiskScore": 7.2,
  "riskLevel": "high",
  "enginesUsed": ["nmap", "nuclei", "harvester"],
  "correlatedFindings": [
    {
      "title": "Panel de administración expuesto con CVE conocido",
      "severity": "critical",
      "engines": ["nmap", "nuclei"],
      "description": "El puerto 8080 está abierto (nmap) ejecutando una versión afectada por CVE-2024-1234 (nuclei)",
      "recommendation": "Restringir acceso al puerto 8080 y actualizar la aplicación"
    }
  ],
  "summary": { "critical": 1, "high": 4, "medium": 8, "low": 15, "total": 50 }
}

Estrategia de polling

Fase	Intervalo	Duración
Inicial (0–2 min)	Cada 5 segundos	Retorno rápido para análisis cortos
Activa (2–10 min)	Cada 15 segundos	La mayoría de los análisis terminan aquí
Extendida (10–60 min)	Cada 30 segundos	Análisis profundos o completos
Larga duración (60+ min)	Cada 60 segundos	Grandes redes o Sentinel

Use webhooks

Para integraciones en producción, use webhooks en lugar de polling. Los webhooks son más eficientes y proporcionan notificaciones instantáneas.

Notificaciones en tiempo real

Configure webhooks para recibir notificaciones push cuando ocurran eventos de análisis:

Evento	Disparador
scan.started	El análisis pasa de queued a running
scan.completed	El análisis termina exitosamente
scan.failed	El análisis encuentra un error fatal
scan.cancelled	El análisis es cancelado

Consulte Webhooks para instrucciones de configuración.

---

Próximos pasos:

• Plantillas de análisis →
• Webhooks →
• Referencia de errores →