Risultati e stato delle scansioni

Seguite il progresso delle scansioni, ottenete i rilevamenti e comprendete il ciclo di vita completo dall'invio al completamento.

Ciclo di vita dello stato

Ogni scansione attraversa un insieme di stati ben definiti:

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

Stato	Descrizione	Risultati disponibili	Terminale
queued	Richiesta accettata, in attesa di capacità	No	No
running	Lo scanner sta eseguendo attivamente	No (progresso parziale disponibile)	No
completed	Scansione completata con successo	Sì	Sì
failed	Errore fatale riscontrato	Dettagli errore disponibili	Sì
cancelled	Annullata dall'utente	Risultati parziali possibili	Sì

Verificare lo stato

Endpoint

GET /api/v1/scans/:scanId

Scope richiesto: scans:read

Richiesta

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

Risposta — In corso

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

Risposta — Completata

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

Importante — Parametro scanType

Passate sempre il parametro scanType corretto corrispondente al motore usato durante la creazione. Il predefinito è nmap — se la vostra scansione ha usato zap, dovete specificare ?scanType=zap o otterrete un errore 404 SCAN_NOT_FOUND.

Ottenere i risultati

Una volta che lo stato è completed, i risultati completi sono disponibili.

Endpoint

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

Scope richiesto: 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"

Schemi dei risultati per motore

Risultati 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 }
}

Risultati ZAP

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

Risultati Trivy

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

Risultati Nuclei

{
  "findings": [
    {
      "templateId": "CVE-2023-44487",
      "name": "Attacco 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 }
}

Risultati 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 }
}

Risultati Sentinel

{
  "overallRiskScore": 7.2,
  "riskLevel": "high",
  "enginesUsed": ["nmap", "nuclei", "harvester"],
  "correlatedFindings": [
    {
      "title": "Pannello di amministrazione esposto con CVE nota",
      "severity": "critical",
      "engines": ["nmap", "nuclei"],
      "description": "La porta 8080 è aperta (nmap) ed esegue una versione affetta da CVE-2024-1234 (nuclei)",
      "recommendation": "Limitare l'accesso alla porta 8080 e aggiornare l'applicazione"
    }
  ],
  "summary": { "critical": 1, "high": 4, "medium": 8, "low": 15, "total": 50 }
}

Strategia di polling

Fase	Intervallo	Durata
Iniziale (0–2 min)	Ogni 5 secondi	Feedback rapido per scansioni brevi
Attiva (2–10 min)	Ogni 15 secondi	La maggior parte delle scansioni termina qui
Estesa (10–60 min)	Ogni 30 secondi	Scansioni profonde o complete
Lunga durata (60+ min)	Ogni 60 secondi	Grandi reti o Sentinel

Usate i webhook

Per le integrazioni in produzione, usate i webhook al posto del polling. I webhook sono più efficienti e forniscono notifiche istantanee.

Notifiche in tempo reale

Configurate webhook per ricevere notifiche push quando si verificano eventi di scansione:

Evento	Trigger
scan.started	La scansione passa da queued a running
scan.completed	La scansione termina con successo
scan.failed	La scansione incontra un errore fatale
scan.cancelled	La scansione viene annullata

Consultate Webhook per le istruzioni di configurazione.

---

Prossimi passi:

• Template di scansione →
• Webhook →
• Riferimento errori →