Per iniziare

Inviate la vostra prima scansione di vulnerabilità in meno di 5 minuti. Questa guida vi accompagna nell'ottenere una chiave API, inviare una scansione, verificarne lo stato e ottenere i risultati.

Prerequisiti

Prima di iniziare, assicuratevi di avere:

• ✅ Un account Cert-IX attivo con accesso all'API Scan
• ✅ Accesso al pannello di controllo Cert-IX per la gestione delle chiavi API
• ✅ cURL o qualsiasi client HTTP (Python requests, Postman, ecc.)

Passo 1: Ottenere la chiave API

1. Accedete al pannello di controllo Cert-IX
2. Navigate a Impostazioni → Chiavi API
3. Cliccate su Crea chiave API
4. Configurate la chiave:
   • Nome: Assegnate un nome descrittivo (es.: «La mia prima chiave di scansione»)
   • Scope: Selezionate come minimo scans:create, scans:read, results:read
   • Scadenza: Impostate una scadenza appropriata (es.: 90 giorni)
5. Cliccate su Crea e copiate la chiave immediatamente

Importante

La chiave API in chiaro viene mostrata solo una volta durante la creazione. Conservatela in modo sicuro in un gestore di password o vault di segreti. Cert-IX non può recuperarla successivamente.

Impostate la chiave come variabile d'ambiente:

export CERTIX_API_KEY="cix_sk_la_vostra_chiave_api_qui"

Passo 2: Inviare la prima scansione

Lanciamo una scansione di rete Nmap di base su un obiettivo:

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": "La mia prima scansione",
    "options": {
      "ports": "1-1024",
      "timing": "T3",
      "serviceDetection": true
    }
  }'

Risposta:

{
  "success": true,
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "scanType": "nmap",
    "name": "La mia prima scansione",
    "target": "example.com",
    "status": "queued",
    "priority": "normal",
    "progress": 0,
    "createdAt": "2026-03-06T10:00:00Z"
  }
}

Salvate l'ID della scansione

Copiate l'id dalla risposta — vi servirà per verificare lo stato e ottenere i risultati.

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

Passo 3: Verificare lo stato della scansione

Le scansioni vengono eseguite in modo asincrono. Interrogate l'endpoint di stato per seguire il progresso:

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

Risposta (completata):

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

Valori di stato

Stato	Significato
queued	Accettata, in attesa di capacità dello scanner
running	Lo scanner sta eseguendo attivamente la scansione
completed	Completata con successo — risultati disponibili
failed	Errore fatale riscontrato
cancelled	Annullata dall'utente

Passo 4: Ottenere i risultati

Una volta che lo stato è completed, ottenete i risultati completi:

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"

Risposta:

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

Script Bash completo che automatizza l'intero flusso di lavoro:

#!/bin/bash
# API Scan Cert-IX — Flusso di lavoro completo di scansione
set -euo pipefail

API_KEY="${CERTIX_API_KEY:?Definite la variabile d'ambiente CERTIX_API_KEY}"
BASE_URL="https://api.cert-ix.com/scan-api/api/v1"
TARGET="${1:-example.com}"

echo "🔍 Invio scansione Nmap per: $TARGET"

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\": \"Scansione rapida - $TARGET\",
    \"options\": { \"ports\": \"1-1024\", \"timing\": \"T3\", \"serviceDetection\": true }
  }")

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

echo "⏳ In attesa del completamento..."
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 "   Stato: $STATUS ($PROGRESS%)"
  case "$STATUS" in
    completed) break ;;
    failed)    echo "❌ Scansione fallita"; exit 1 ;;
    cancelled) echo "⚠️ Scansione annullata"; exit 1 ;;
  esac
  sleep 5
done

echo "📊 Recupero risultati..."
curl -s -X GET "$BASE_URL/scans/$SCAN_ID/results?scanType=nmap" -H "X-API-Key: $API_KEY" | jq .
echo "✨ Completato!"

Cosa fare dopo?

• Autenticazione e chiavi API — Scope, rotazione, allowlisting IP
• Invio di scansioni — Tutti i 10 motori con opzioni dettagliate
• Webhook — Notifiche in tempo reale al posto del polling
• Esempi di codice — Client pronti per la produzione in Python, Go e Node.js

Consiglio professionale

Per le integrazioni in produzione, usate i webhook al posto del polling. I webhook forniscono notifiche istantanee e non consumano quota API per le verifiche di stato.