Résultats et statut des analyses

Suivez la progression des analyses, récupérez les découvertes et comprenez le cycle de vie complet depuis la soumission jusqu'à la complétion.

Cycle de vie du statut

Chaque analyse passe par un ensemble d'états bien définis :

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

Statut	Description	Résultats disponibles	Terminal
queued	Requête acceptée, en attente de capacité	Non	Non
running	Le scanner exécute activement	Non (progression partielle disponible)	Non
completed	Analyse terminée avec succès	Oui	Oui
failed	Erreur fatale rencontrée	Détails d'erreur disponibles	Oui
cancelled	Annulée par l'utilisateur	Résultats partiels possibles	Oui

Vérifier le statut

Endpoint

GET /api/v1/scans/:scanId

Portée requise : scans:read

Paramètres de requête

Paramètre	Type	Défaut	Description
scanType	string	nmap	Le type de moteur (doit correspondre à l'analyse originale)

Requête

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

Réponse — En cours

{
  "success": true,
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "scanType": "nmap",
    "name": "Audit réseau hebdomadaire",
    "target": "example.com",
    "status": "running",
    "progress": 67,
    "createdAt": "2026-03-06T10:00:00Z",
    "startedAt": "2026-03-06T10:00:02Z"
  }
}

Réponse — Terminée

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

Réponse — Échouée

{
  "success": true,
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "scanType": "nmap",
    "status": "failed",
    "progress": 23,
    "error": "Cible injoignable : délai de connexion dépassé après 120s",
    "durationMs": 120340
  }
}

Important — Paramètre scanType

Passez toujours le bon paramètre scanType correspondant au moteur utilisé lors de la création. Le défaut est nmap, donc si votre analyse utilisait zap, vous devez spécifier ?scanType=zap sinon vous obtiendrez une erreur 404 SCAN_NOT_FOUND.

Récupérer les résultats

Une fois le statut completed, les résultats complets sont disponibles.

Endpoint

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

Portée requise : results:read

Requête

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"

Réponse (200 OK)

{
  "success": true,
  "data": {
    "scanId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "scanType": "nmap",
    "target": "example.com",
    "status": "completed",
    "startedAt": "2026-03-06T10:00:02Z",
    "completedAt": "2026-03-06T10:02:15Z",
    "results": { ... }
  }
}

La structure du champ results varie selon le moteur — voir les schémas ci-dessous.

Schémas de résultats par moteur

Résultats 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",
          "scripts": [{ "id": "http-title", "output": "Example Domain" }]
        }
      ]
    }
  ],
  "stats": {
    "hostsUp": 1,
    "hostsDown": 0,
    "openPorts": 2,
    "closedPorts": 1022,
    "filteredPorts": 0
  }
}

Résultats ZAP

{
  "alerts": [
    {
      "name": "Cross-Site Scripting (Réfléchi)",
      "risk": "High",
      "confidence": "Medium",
      "description": "Le Cross-site Scripting (XSS) est une technique d'attaque...",
      "solution": "Validez toutes les entrées et encodez les sorties...",
      "cweid": 79,
      "wascid": 8,
      "instances": [
        {
          "uri": "https://app.example.com/search",
          "method": "GET",
          "param": "q",
          "attack": "<script>alert(1)</script>",
          "evidence": "<script>alert(1)</script>"
        }
      ]
    }
  ],
  "summary": { "high": 2, "medium": 5, "low": 12, "informational": 8, "total": 27 }
}

Résultats Trivy

{
  "vulnerabilities": [
    {
      "vulnerabilityID": "CVE-2024-1234",
      "pkgName": "openssl",
      "installedVersion": "3.0.11",
      "fixedVersion": "3.0.13",
      "severity": "CRITICAL",
      "title": "OpenSSL : Débordement de tampon dans la vérification de certificat X.509",
      "cvss": {
        "nvd": { "v3Score": 9.8, "v3Vector": "CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:U/C:H/I:H/A:H" }
      }
    }
  ],
  "summary": { "critical": 1, "high": 3, "medium": 7, "low": 2, "total": 13 }
}

Résultats Nuclei

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

Résultats theHarvester

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

Résultats Sentinel

Sentinel agrège les résultats de plusieurs moteurs dans un rapport unifié :

{
  "overallRiskScore": 7.2,
  "riskLevel": "high",
  "enginesUsed": ["nmap", "nuclei", "harvester"],
  "executionTime": "12m 34s",
  "correlatedFindings": [
    {
      "title": "Panneau d'administration exposé avec CVE connu",
      "severity": "critical",
      "engines": ["nmap", "nuclei"],
      "description": "Le port 8080 est ouvert (nmap) exécutant une version affectée par CVE-2024-1234 (nuclei)",
      "recommendation": "Restreindre l'accès au port 8080 et mettre à jour l'application"
    }
  ],
  "summary": { "critical": 1, "high": 4, "medium": 8, "low": 15, "total": 50 }
}

Stratégie de polling

Lors du polling pour la complétion, utilisez une stratégie adaptative pour équilibrer réactivité et efficacité API :

Phase	Intervalle	Durée
Initiale (0–2 min)	Toutes les 5 secondes	Retour rapide pour les analyses courtes
Active (2–10 min)	Toutes les 15 secondes	La plupart des analyses se terminent ici
Étendue (10–60 min)	Toutes les 30 secondes	Analyses profondes ou complètes
Longue durée (60+ min)	Toutes les 60 secondes	Grands réseaux ou Sentinel

Utilisez les webhooks

Pour les intégrations en production, utilisez les webhooks au lieu du polling. Les webhooks sont plus efficaces et fournissent des notifications instantanées.

Notifications en temps réel

Au lieu du polling, configurez des webhooks pour recevoir des notifications push lorsque des événements d'analyse se produisent :

Événement	Déclencheur
scan.started	L'analyse passe de queued à running
scan.completed	L'analyse se termine avec succès
scan.failed	L'analyse rencontre une erreur fatale
scan.cancelled	L'analyse est annulée

Voir Webhooks pour les instructions de configuration.

---

Prochaines étapes :

• Modèles d'analyse →
• Webhooks →
• Référence des erreurs →