Versione: 1.0.0

Invio di scansioni

L'API Scan accetta richieste di scansione attraverso un singolo endpoint unificato. Specificate l'obiettivo, il motore di scansione e la configurazione opzionale — la piattaforma gestisce la coda, l'esecuzione, la raccolta dei risultati e le notifiche.

Architettura

Le scansioni vengono elaborate in modo asincrono tramite Kafka:

POST /scans → Kafka → Motore di scansione → Risultati → Webhook/Polling

Creare una scansione

Endpoint

POST /api/v1/scans

Scope richiesto: scans:create

Richiesta

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": "Audit di rete settimanale",
    "targetType": "domain",
    "priority": "normal",
    "options": {
      "ports": "1-1024",
      "timing": "T3"
    },
    "tags": ["produzione", "settimanale"],
    "timeout": 3600
  }'

Parametri della richiesta

Campo	Tipo	Obbligatorio	Descrizione
`target`	string	Sì	Obiettivo della scansione (URL, host, dominio, IP o CIDR)
`scanType`	string	Sì	Motore di scansione da usare (vedi riferimento sotto)
`name`	string	No	Nome leggibile della scansione
`targetType`	string	No	Classificazione dell'obiettivo: `host`, `url`, `domain`, `ip`, `network`
`priority`	string	No	Priorità di esecuzione: `critical`, `high`, `normal`, `low` (predefinito: `normal`)
`options`	object	No	Opzioni specifiche del motore
`config`	object	No	Sovrascritture di configurazione del motore
`tags`	string[]	No	Tag personalizzati per organizzazione e filtraggio
`timeout`	integer	No	Durata massima della scansione in secondi
`assetId`	string	No	Collegare la scansione a un asset registrato nella Gestione Asset
`callbackUrl`	string	No	URL HTTPS per un callback una tantum al completamento

Risposta (201 Created)

{
  "success": true,
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "scanType": "nmap",
    "name": "Audit di rete settimanale",
    "target": "example.com",
    "status": "queued",
    "priority": "normal",
    "progress": 0,
    "tags": ["produzione", "settimanale"],
    "createdAt": "2026-03-06T10:00:00Z"
  }
}

Riferimento dei motori di scansione

Nmap — Scoperta di rete

Tipo: nmap · Categoria: Rete · Obiettivi: host, ip, network, domain

{
  "target": "192.168.1.0/24",
  "scanType": "nmap",
  "options": {
    "ports": "1-65535",
    "timing": "T4",
    "serviceDetection": true,
    "osDetection": true,
    "scriptScan": true,
    "scripts": ["vuln", "safe"]
  }
}

Opzione	Tipo	Predefinito	Descrizione
`ports`	string	`1-1024`	Intervallo porte (es.: `22,80,443`, `1-1024`, `1-65535`)
`timing`	string	`T3`	Template temporizzazione: `T0` (paranoico) a `T5` (folle)
`serviceDetection`	boolean	`true`	Attivare rilevamento servizio/versione (`-sV`)
`osDetection`	boolean	`false`	Attivare identificazione OS (`-O`)
`scriptScan`	boolean	`false`	Attivare scansione script NSE
`scripts`	string[]	`[]`	Categorie di script NSE da eseguire
`udpScan`	boolean	`false`	Includere scansione UDP (`-sU`)
`topPorts`	integer	—	Scansionare solo le N porte più comuni

ZAP — Sicurezza applicazioni web

Tipo: zap · Categoria: App web · Obiettivi: url

{
  "target": "https://app.example.com",
  "scanType": "zap",
  "options": {
    "scanPolicy": "full",
    "spiderMaxDepth": 5,
    "ajaxSpider": true,
    "activeScan": true,
    "contextInclude": ["https://app.example.com/.*"],
    "contextExclude": ["https://app.example.com/logout"]
  }
}

Opzione	Tipo	Predefinito	Descrizione
`scanPolicy`	string	`standard`	Intensità: `light`, `standard`, `full`
`spiderMaxDepth`	integer	`3`	Profondità massima di esplorazione
`ajaxSpider`	boolean	`false`	Attivare esplorazione AJAX/JavaScript
`activeScan`	boolean	`true`	Eseguire test attivi di vulnerabilità
`contextInclude`	string[]	`[]`	Pattern regex URL da includere
`contextExclude`	string[]	`[]`	Pattern regex URL da escludere

Trivy — Analisi vulnerabilità container

Tipo: trivy · Categoria: Container/Infrastruttura · Obiettivi: url, host

{
  "target": "registry.example.com/miaapp:latest",
  "scanType": "trivy",
  "options": {
    "scanners": ["vuln", "misconfig", "secret"],
    "severity": ["CRITICAL", "HIGH"],
    "ignoreUnfixed": true
  }
}

Nuclei — Rilevamento basato su template

Tipo: nuclei · Categoria: Rilevamento vulnerabilità · Obiettivi: url, host, domain

{
  "target": "https://api.example.com",
  "scanType": "nuclei",
  "options": {
    "templates": ["cves", "vulnerabilities", "misconfigurations"],
    "severity": ["critical", "high", "medium"],
    "concurrency": 25,
    "rateLimit": 150
  }
}

Nikto — Scansione server web

Tipo: nikto · Categoria: Server web · Obiettivi: url

{
  "target": "https://www.example.com",
  "scanType": "nikto",
  "options": { "tuning": "1234", "maxTime": "600s", "ssl": true }
}

SQLMap — Rilevamento SQL injection

Tipo: sqlmap · Categoria: App web · Obiettivi: url

{
  "target": "https://app.example.com/search?q=test",
  "scanType": "sqlmap",
  "options": { "level": 3, "risk": 2, "technique": "BEUSTQ", "dbs": true, "batch": true }
}

Sicurezza in produzione

SQLMap può essere aggressivo. Usate sempre level ≤ 3 e risk ≤ 2 su sistemi di produzione.

Wapiti — Scansione applicazioni web

Tipo: wapiti · Categoria: App web · Obiettivi: url

{
  "target": "https://app.example.com",
  "scanType": "wapiti",
  "options": { "modules": ["xss", "sql", "exec", "file", "crlf"], "scope": "domain", "maxDepth": 5 }
}

theHarvester — Ricognizione OSINT

Tipo: harvester · Categoria: OSINT · Obiettivi: domain

{
  "target": "example.com",
  "scanType": "harvester",
  "options": { "sources": ["google", "bing", "linkedin", "shodan", "crtsh"], "limit": 500, "dnsLookup": true }
}

Sublist3r — Enumerazione sottodomini

Tipo: sublist3r · Categoria: OSINT · Obiettivi: domain

{
  "target": "example.com",
  "scanType": "sublist3r",
  "options": { "engines": ["google", "bing", "yahoo", "virustotal"], "bruteforce": true, "ports": "80,443,8080", "threads": 30 }
}

Sentinel — Orchestrazione multi-motore

Tipo: sentinel · Categoria: Unificato/Completo · Obiettivi: url, host, domain, ip

Analisi orchestrata multi-motore proprietaria di Cert-IX. Seleziona e esegue automaticamente la combinazione di scanner più appropriata in base al tipo di obiettivo, poi correla e deduplica i rilevamenti.

{
  "target": "example.com",
  "scanType": "sentinel",
  "priority": "high",
  "options": { "depth": "standard", "engines": ["nmap", "nuclei", "harvester", "sublist3r"], "correlate": true, "riskScore": true }
}

Profondità	Motori utilizzati	Tempo stimato
`quick`	Nmap + Nuclei	5–15 minuti
`standard`	Nmap + Nuclei + Harvester + ZAP/Nikto	15–45 minuti
`deep`	Tutti i motori applicabili	1–3 ore

Livelli di priorità

Priorità	Comportamento	Caso d'uso
`critical`	In testa alla coda, elaborazione immediata	Risposta a incidenti attiva
`high`	Prima delle scansioni normali	Verifiche pre-deploy
`normal`	Ordine FIFO standard	Valutazioni di routine (predefinito)
`low`	Elaborazione quando c'è capacità disponibile	Scansioni in background/batch

Annullare una scansione

POST /api/v1/scans/:scanId/cancel

Scope richiesto: scans:cancel

Elencare le scansioni

GET /api/v1/scans

Scope richiesto: scans:list

Prossimi passi:

Architettura​

Creare una scansione​

Endpoint​

Richiesta​

Parametri della richiesta​

Risposta (201 Created)​

Riferimento dei motori di scansione​

Nmap — Scoperta di rete​

ZAP — Sicurezza applicazioni web​

Trivy — Analisi vulnerabilità container​

Nuclei — Rilevamento basato su template​

Nikto — Scansione server web​

SQLMap — Rilevamento SQL injection​

Wapiti — Scansione applicazioni web​

theHarvester — Ricognizione OSINT​

Sublist3r — Enumerazione sottodomini​

Sentinel — Orchestrazione multi-motore​

Livelli di priorità​

Annullare una scansione​

Elencare le scansioni​