Aller au contenu principal
Version: 1.0.0

Prise en main

Soumettez votre première analyse de vulnérabilités en moins de 5 minutes. Ce guide vous accompagne pour obtenir une clé API, soumettre une analyse, vérifier son statut et récupérer les résultats.

Prérequis​

Avant de commencer, assurez-vous de disposer de :

  • ✅ Un compte Cert-IX actif avec accès à l'API Scan
  • ✅ Accès au tableau de bord Cert-IX pour la gestion des clés API
  • ✅ cURL ou tout client HTTP (Python requests, Postman, etc.)

Étape 1 : Obtenir votre clé API​

  1. Connectez-vous au tableau de bord Cert-IX
  2. Naviguez vers Paramètres → Clés API
  3. Cliquez sur Créer une clé API
  4. Configurez la clé :
    • Nom : Donnez un nom descriptif (ex. : « Ma première clé de scan »)
    • Portées : Sélectionnez au minimum scans:create, scans:read, results:read
    • Expiration : Définissez une expiration appropriée (ex. : 90 jours)
  5. Cliquez sur Créer et copiez la clé immédiatement
Important

La clé API brute est affichée une seule fois lors de la création. Stockez-la en sécurité dans un gestionnaire de mots de passe ou un coffre-fort de secrets. Cert-IX ne peut pas la récupérer ultérieurement.

Définissez la clé comme variable d'environnement pour plus de commodité :

export CERTIX_API_KEY="cix_sk_votre_cle_api_ici"

Étape 2 : Soumettre votre première analyse​

Lançons une analyse réseau Nmap basique sur une cible :

curl -X POST https://api.cert-ix.com/scan-api/api/v1/scans \
  -H "X-API-Key: $CERTIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "target": "example.com",
    "scanType": "nmap",
    "name": "Ma première analyse",
    "options": {
      "ports": "1-1024",
      "timing": "T3",
      "serviceDetection": true
    }
  }'

Réponse :

{
  "success": true,
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "scanType": "nmap",
    "name": "Ma première analyse",
    "target": "example.com",
    "status": "queued",
    "priority": "normal",
    "progress": 0,
    "createdAt": "2026-03-06T10:00:00Z"
  }
}
Sauvegardez l'ID de l'analyse

Copiez l'id de la réponse — vous en aurez besoin pour vérifier le statut et récupérer les résultats.

export SCAN_ID="a1b2c3d4-e5f6-7890-abcd-ef1234567890"

Étape 3 : Vérifier le statut de l'analyse​

Les analyses s'exécutent de manière asynchrone. Interrogez le endpoint de statut pour suivre la progression :

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",
    "status": "running",
    "progress": 67
  }
}

Réponse (terminée) :

{
  "success": true,
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "status": "completed",
    "progress": 100,
    "resultCount": 12,
    "durationMs": 135000
  }
}

Valeurs de statut​

StatutSignification
queuedAcceptée, en attente de capacité du scanner
runningLe scanner exécute activement l'analyse
completedTerminée avec succès — résultats disponibles
failedErreur fatale rencontrée
cancelledAnnulée par l'utilisateur

Étape 4 : Récupérer les résultats​

Une fois le statut completed, récupérez les résultats complets :

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 :

{
  "success": true,
  "data": {
    "scanId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "scanType": "nmap",
    "target": "example.com",
    "status": "completed",
    "results": {
      "hosts": [
        {
          "ip": "93.184.216.34",
          "hostname": "example.com",
          "state": "up",
          "ports": [
            {
              "port": 80,
              "protocol": "tcp",
              "state": "open",
              "service": "http",
              "version": "nginx 1.25.4"
            },
            {
              "port": 443,
              "protocol": "tcp",
              "state": "open",
              "service": "https",
              "version": "nginx 1.25.4"
            }
          ]
        }
      ],
      "stats": {
        "hostsUp": 1,
        "openPorts": 2,
        "closedPorts": 1022
      }
    }
  }
}

Script complet​

Voici un script Bash complet qui automatise l'ensemble du workflow :

#!/bin/bash
# API Scan Cert-IX — Workflow complet d'analyse
set -euo pipefail

API_KEY="${CERTIX_API_KEY:?Définissez la variable d'environnement CERTIX_API_KEY}"
BASE_URL="https://api.cert-ix.com/scan-api/api/v1"
TARGET="${1:-example.com}"

echo "🔍 Soumission d'une analyse Nmap pour : $TARGET"

# Étape 1 : Soumettre l'analyse
RESPONSE=$(curl -s -X POST "$BASE_URL/scans" \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"target\": \"$TARGET\",
    \"scanType\": \"nmap\",
    \"name\": \"Analyse rapide - $TARGET\",
    \"options\": {
      \"ports\": \"1-1024\",
      \"timing\": \"T3\",
      \"serviceDetection\": true
    }
  }")

SCAN_ID=$(echo "$RESPONSE" | jq -r '.data.id')
echo "✅ Analyse soumise : $SCAN_ID"

# Étape 2 : Interroger jusqu'à complétion
echo "⏳ En attente de la fin de l'analyse..."
while true; do
  STATUS_RESP=$(curl -s -X GET "$BASE_URL/scans/$SCAN_ID?scanType=nmap" \
    -H "X-API-Key: $API_KEY")
  STATUS=$(echo "$STATUS_RESP" | jq -r '.data.status')
  PROGRESS=$(echo "$STATUS_RESP" | jq -r '.data.progress')

  echo "   Statut : $STATUS ($PROGRESS%)"

  case "$STATUS" in
    completed) break ;;
    failed)    echo "❌ L'analyse a échoué"; exit 1 ;;
    cancelled) echo "⚠️ L'analyse a été annulée"; exit 1 ;;
  esac

  sleep 5
done

# Étape 3 : Récupérer les résultats
echo "📊 Récupération des résultats..."
curl -s -X GET "$BASE_URL/scans/$SCAN_ID/results?scanType=nmap" \
  -H "X-API-Key: $API_KEY" | jq .

echo "✨ Terminé !"

Et ensuite ?​

Maintenant que vous avez terminé votre première analyse, explorez ces sujets :

Conseil pro

Pour les intégrations en production, utilisez les webhooks au lieu du polling. Les webhooks fournissent des notifications instantanées et ne consomment aucun quota API pour les vérifications de statut.