Autenticazione e chiavi API

L'API Scan di Cert-IX utilizza chiavi API per l'accesso programmatico. Le chiavi API offrono scope granulari, restrizioni per tipo di scansione, limiti di velocità per chiave, allowlisting IP, scadenza automatica e rotazione senza interruzioni.

Metodi di autenticazione

Metodo	Caso d'uso	Header
Chiave API	Accesso programmatico (script, CI/CD, integrazioni)	X-API-Key
JWT	Operazioni del pannello di controllo (gestione chiavi API)	Authorization: Bearer <token>

Questa pagina copre l'autenticazione tramite chiave API. L'autenticazione JWT è gestita automaticamente dal pannello di controllo di Cert-IX.

Formato delle chiavi API

Le chiavi API di Cert-IX seguono un formato deterministico per una facile identificazione:

cix_sk_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

Segmento	Descrizione
cix_	Prefisso della piattaforma Cert-IX
sk_	Identificatore di tipo chiave segreta
XXX...	Stringa crittografica casuale di 40 caratteri

Sicurezza

Le chiavi API vengono hashate con SHA-256 prima dell'archiviazione. La chiave in chiaro viene mostrata solo una volta alla creazione. Cert-IX non può recuperare la vostra chiave se persa — dovete effettuare una rotazione.

Trasmettere la chiave API

Includete la vostra chiave API nell'header X-API-Key in ogni richiesta:

curl -X GET https://api.cert-ix.com/scan-api/api/v1/scans \
  -H "X-API-Key: cix_sk_la_vostra_chiave_api_qui"

Non trasmettete mai chiavi API nei parametri URL

Le query string possono essere registrate nei log di accesso del server, nella cronologia del browser e nelle cache dei proxy.

Creare una chiave API

Endpoint

POST /api/v1/api-keys

Corpo della richiesta

{
  "name": "Pipeline CI/CD - Produzione",
  "description": "Utilizzata da GitHub Actions per scansioni di vulnerabilità notturne",
  "scopes": ["scans:create", "scans:read", "scans:list", "results:read", "webhooks:read"],
  "allowedScanTypes": ["nmap", "nuclei", "trivy", "zap"],
  "allowedIpAddresses": ["203.0.113.50", "198.51.100.0/24"],
  "rateLimitPerMinute": 30,
  "rateLimitPerHour": 500,
  "rateLimitPerDay": 5000,
  "expiresInDays": 90
}

Parametri della richiesta

Campo	Tipo	Obbligatorio	Descrizione
name	string	Sì	Nome leggibile della chiave (max. 255 caratteri)
description	string	No	Descrizione d'uso opzionale
scopes	string[]	No	Scope di permessi (predefinito: tutti gli scope)
allowedScanTypes	string[]	No	Motori di scansione permessi (predefinito: tutti)
allowedIpAddresses	string[]	No	Intervalli IP/CIDR sorgente permessi
rateLimitPerMinute	integer	No	Richieste max. al minuto
rateLimitPerHour	integer	No	Richieste max. all'ora
rateLimitPerDay	integer	No	Richieste max. al giorno
expiresInDays	integer	No	Scadenza in giorni (0 o null = nessuna scadenza)

Risposta (201 Created)

{
  "success": true,
  "data": {
    "apiKey": {
      "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "name": "Pipeline CI/CD - Produzione",
      "keyPrefix": "cix_sk_001e3c",
      "scopes": ["scans:create", "scans:read", "scans:list", "results:read", "webhooks:read"],
      "status": "active",
      "expiresAt": "2026-06-04T10:00:00Z",
      "createdAt": "2026-03-06T10:00:00Z"
    },
    "rawKey": "cix_sk_001e3c2d92ffb23344a943df2b6a001fb1028d002"
  }
}

Critico

Il campo rawKey viene restituito solo al momento della creazione. Copiatelo immediatamente e conservatelo in un vault sicuro (es.: HashiCorp Vault, AWS Secrets Manager).

Scope e permessi

Gli scope controllano le azioni che una chiave API è autorizzata a compiere. Applicate il principio del minimo privilegio — concedete solo gli scope necessari per la vostra integrazione.

Scope disponibili

Scope	Descrizione
scans:create	Inviare nuove scansioni
scans:read	Visualizzare dettagli e stato di una scansione
scans:list	Elencare tutte le scansioni del tenant
scans:cancel	Annullare scansioni in corso
results:read	Ottenere risultati e rilevamenti
templates:create	Creare template di scansione
templates:read	Visualizzare template di scansione
templates:update	Modificare template di scansione
templates:delete	Eliminare template di scansione
webhooks:create	Registrare e testare webhook
webhooks:read	Visualizzare configurazioni e log di consegna
webhooks:update	Modificare configurazioni webhook
webhooks:delete	Eliminare webhook
usage:read	Visualizzare analytics di utilizzo e quote

Set di scope consigliati

Pipeline CI/CD (lettura-scrittura scansioni):

["scans:create", "scans:read", "scans:list", "results:read"]

Pannello di monitoraggio (solo lettura):

["scans:read", "scans:list", "results:read", "usage:read"]

Automazione completa (scansioni + webhook + template):

["scans:create", "scans:read", "scans:list", "scans:cancel", "results:read",
 "templates:create", "templates:read", "templates:update",
 "webhooks:create", "webhooks:read"]

Tipi di scansione consentiti

Limitate i motori di scansione che una chiave API può invocare:

Tipi disponibili: nmap, zap, trivy, nuclei, nikto, sqlmap, wapiti, harvester, sublist3r, sentinel

Allowlisting IP

Bloccate una chiave API su indirizzi IP sorgente o intervalli CIDR specifici. Le richieste da altri IP vengono rifiutate con 403 IP_NOT_ALLOWED.

Formati supportati:

• IP singolo: "203.0.113.50"
• Intervallo CIDR: "198.51.100.0/24"
• IPv6: "2001:db8::1"

Limiti di velocità

Finestra	Predefinito	Intervallo configurabile
Per minuto	60	1 – 1.000
Per ora	1.000	1 – 50.000
Per giorno	10.000	1 – 500.000

Header dei limiti di velocità

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 42
X-RateLimit-Reset: 1709654460

Limite di velocità superato

{
  "success": false,
  "error": "Limite di velocità superato. Riprovate tra 23 secondi.",
  "code": "RATE_LIMIT_EXCEEDED"
}

Stato HTTP: 429 Too Many Requests

Rotazione delle chiavi

Effettuate la rotazione delle chiavi API con zero downtime grazie al meccanismo del periodo di grazia.

Endpoint

POST /api/v1/api-keys/:keyId/rotate

Flusso di lavoro di rotazione

1. POST /api-keys/:vecchiaChiaveId/rotate → Nuova chiave creata, vecchia in periodo di grazia
2. Aggiornate il vostro archivio segreti con la nuova chiave
3. Distribuite la nuova chiave nei vostri servizi
4. La vecchia chiave scade automaticamente dopo il periodo di grazia

Buona pratica

Effettuate la rotazione delle chiavi ogni 90 giorni. Automatizzate la rotazione nella vostra infrastruttura o impostate un promemoria nel calendario.

Revoca delle chiavi

Disattivate immediatamente e permanentemente una chiave API. La revoca è istantanea — la chiave smette di funzionare immediatamente.

Endpoint

DELETE /api/v1/api-keys/:keyId

Stati delle chiavi

Stato	Descrizione
active	La chiave è pienamente operativa
revoked	La chiave è stata permanentemente disattivata
expired	La chiave ha superato la sua data expiresAt
suspended	La chiave è stata temporaneamente sospesa da un amministratore

Best practice di sicurezza

Da fare

• ✅ Conservate le chiavi in un gestore di segreti (HashiCorp Vault, AWS Secrets Manager, Azure Key Vault)
• ✅ Usate variabili d'ambiente — non codificate mai le chiavi direttamente
• ✅ Applicate il minimo privilegio — concedete solo gli scope necessari
• ✅ Impostate date di scadenza — rotazione ogni 90 giorni
• ✅ Usate l'allowlisting IP per infrastruttura statica
• ✅ Monitorate l'utilizzo tramite gli endpoint di analytics di utilizzo
• ✅ Revocate immediatamente se una chiave è compromessa

Da non fare

• ❌ Non fate mai commit di chiavi nel controllo versione (Git, SVN)
• ❌ Non trasmettete mai chiavi nei parametri URL
• ❌ Non condividete mai chiavi tra team o ambienti
• ❌ Non registrate mai chiavi API nei log dell'applicazione

---

Prossimi passi:

• Invio di scansioni →
• Template di scansione →
• Riferimento errori →