Scan-Ergebnisse und -Status

Verfolgen Sie den Scan-Fortschritt, rufen Sie die Befunde ab und verstehen Sie den vollständigen Lebenszyklus von der Einreichung bis zum Abschluss.

Status-Lebenszyklus

Jeder Scan durchläuft eine Reihe klar definierter Zustände:

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

Status	Beschreibung	Ergebnisse verfügbar	Terminal
queued	Anfrage akzeptiert, wartet auf Kapazität	Nein	Nein
running	Scanner führt aktiv aus	Nein (Teilfortschritt verfügbar)	Nein
completed	Scan erfolgreich abgeschlossen	Ja	Ja
failed	Schwerwiegender Fehler aufgetreten	Fehlerdetails verfügbar	Ja
cancelled	Vom Benutzer abgebrochen	Teilergebnisse möglich	Ja

Status prüfen

Endpunkt

GET /api/v1/scans/:scanId

Erforderlicher Bereich: scans:read

Anfrage

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

Antwort — In Bearbeitung

{
  "success": true,
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "scanType": "nmap",
    "status": "running",
    "progress": 67,
    "createdAt": "2026-03-06T10:00:00Z",
    "startedAt": "2026-03-06T10:00:02Z"
  }
}

Antwort — Abgeschlossen

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

Wichtig — Parameter scanType

Übergeben Sie immer den korrekten scanType-Parameter, der der bei der Erstellung verwendeten Engine entspricht. Der Standard ist nmap — wenn Ihr Scan zap verwendet hat, müssen Sie ?scanType=zap angeben, sonst erhalten Sie einen 404 SCAN_NOT_FOUND-Fehler.

Ergebnisse abrufen

Sobald der Status completed ist, sind die vollständigen Ergebnisse verfügbar.

Endpunkt

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

Erforderlicher Bereich: results:read

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"

Ergebnis-Schemata nach Engine

Nmap-Ergebnisse

{
  "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 }
}

ZAP-Ergebnisse

{
  "alerts": [
    {
      "name": "Cross-Site Scripting (Reflektiert)",
      "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 }
}

Trivy-Ergebnisse

{
  "vulnerabilities": [
    {
      "vulnerabilityID": "CVE-2024-1234",
      "pkgName": "openssl",
      "installedVersion": "3.0.11",
      "fixedVersion": "3.0.13",
      "severity": "CRITICAL",
      "title": "OpenSSL: Pufferüberlauf bei X.509-Zertifikatsverifizierung",
      "cvss": { "nvd": { "v3Score": 9.8 } }
    }
  ],
  "summary": { "critical": 1, "high": 3, "medium": 7, "low": 2, "total": 13 }
}

Nuclei-Ergebnisse

{
  "findings": [
    {
      "templateId": "CVE-2023-44487",
      "name": "HTTP/2 Rapid Reset Angriff",
      "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 }
}

theHarvester-Ergebnisse

{
  "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 }
}

Sentinel-Ergebnisse

{
  "overallRiskScore": 7.2,
  "riskLevel": "high",
  "enginesUsed": ["nmap", "nuclei", "harvester"],
  "correlatedFindings": [
    {
      "title": "Exponiertes Admin-Panel mit bekannter CVE",
      "severity": "critical",
      "engines": ["nmap", "nuclei"],
      "description": "Port 8080 ist offen (nmap) und führt eine Version aus, die von CVE-2024-1234 betroffen ist (nuclei)",
      "recommendation": "Zugriff auf Port 8080 einschränken und die Anwendung aktualisieren"
    }
  ],
  "summary": { "critical": 1, "high": 4, "medium": 8, "low": 15, "total": 50 }
}

Polling-Strategie

Phase	Intervall	Dauer
Initial (0–2 Min.)	Alle 5 Sekunden	Schnelles Feedback für kurze Scans
Aktiv (2–10 Min.)	Alle 15 Sekunden	Die meisten Scans enden hier
Erweitert (10–60 Min.)	Alle 30 Sekunden	Tiefe oder umfassende Scans
Langläufer (60+ Min.)	Alle 60 Sekunden	Große Netzwerke oder Sentinel

Verwenden Sie Webhooks

Für Produktionsintegrationen verwenden Sie Webhooks statt Polling. Webhooks sind effizienter und liefern sofortige Benachrichtigungen.

Echtzeit-Benachrichtigungen

Konfigurieren Sie Webhooks, um Push-Benachrichtigungen zu erhalten, wenn Scan-Ereignisse eintreten:

Ereignis	Auslöser
scan.started	Der Scan wechselt von queued zu running
scan.completed	Der Scan wird erfolgreich abgeschlossen
scan.failed	Der Scan stößt auf einen schwerwiegenden Fehler
scan.cancelled	Der Scan wird abgebrochen

Siehe Webhooks für Einrichtungsanweisungen.

---

Nächste Schritte:

• Scan-Vorlagen →
• Webhooks →
• Fehlerreferenz →