Agente DepAlert

CTWall

Questo strumento fa parte della piattaforma CTWall. Vedi: CTWall

Descrizione

DepAlert è un gate di sicurezza open source per la tua pipeline CI/CD. Analizza gli SBOM rispetto ai dati di intelligence sui malware e ti dice rapidamente se la tua build include pacchetti dannosi noti.

DepAlert risolve problemi fondamentali della supply chain del software che hanno un impatto diretto su velocità, rischio e costi di rilascio:

• Impedisce che il malware raggiunga la produzione trasformando l'analisi SBOM in un gate di rilascio CI/CD automatico.
• Riduce i colli di bottiglia della sicurezza dando ai team un verdetto rapido e deterministico (MALWARE, CLEAN, UNKNOWN) in ogni esecuzione della pipeline.
• Standardizza le decisioni sul rischio tra i team con un modello di policy coerente (fail-on) e un flusso di lavoro per eccezioni verificabile.
• Riduce l'esposizione a incidenti e conformità imponendo controlli a livello di progetto prima della distribuzione, non dopo.
• Migliora la produttività degli sviluppatori sostituendo i passaggi manuali di sicurezza con un unico passo CLI riutilizzabile in qualsiasi pipeline.

Avvio rapido

Vedi 00_quick_start.md per istruzioni dettagliate.

Scopo dello strumento

depalert è un CLI per CI/CD che:

1. Carica un SBOM su CTWall (POST /api/v1/ingest)
2. Attende in modo sincrono il verdetto della revisione (GET /api/v1/tests/{testId}/revisions/{revisionId}/depalert-verdict)
3. Restituisce un risultato e un codice di uscita adatti alla pipeline

Lo strumento è limitato al progetto. Puoi selezionare il progetto target tramite:

• project-id (UUID), oppure
• project-name (risolto tramite API).

Se vengono forniti entrambi, project-id ha la precedenza.

Risultati di Depalert

DepAlert restituisce i risultati di una revisione:

• CLEAN - nessun rilevamento malware - exit 0
• MALWARE - almeno un rilevamento malware nella revisione - exit 1
• UNKNOWN - analisi non ancora completata - exit 2 (oppure exit 0 con fail-on=NONE)

Formato output CLI:

VERDICT: <MALWARE|CLEAN|UNKNOWN> (malware=<n> clean=<n> unknown=<n> total=<n>, elapsed=<t>)

La modalità JSON è disponibile tramite --format json (o CTWALL_OUTPUT=json).

Esempio di output JSON:

{
  "version": "1.1.0",
  "status": "success",
  "exitCode": 0,
  "projectId": "28e241e3-b924-4e1a-abc2-d592e8dd811c",
  "testId": "13271a70-cf47-4f3b-9e33-cb41ed0c793e",
  "revisionId": "c4d1f1a4-c018-488e-9dd0-6cfdbed83bf3",
  "verdict": "CLEAN",
  "malwareComponents": 0,
  "cleanComponents": 12,
  "unknownComponents": 0,
  "totalComponents": 12,
  "elapsedMs": 1842,
  "timedOut": false,
  "failOn": "MALWARE",
  "message": "depalert completed"
}

Risultato atteso

VERDICT: <MALWARE|CLEAN|UNKNOWN> (malware=<n> clean=<n> unknown=<n> total=<n>, elapsed=<t>)

• codice di uscita 0 = pass
• codice di uscita 1 = fallimento policy o errore runtime
• codice di uscita 2 = il verdetto finale è UNKNOWN e fail-on non è NONE

Configurazione CLI e ambiente

Regole di targeting del progetto

• Almeno uno tra project-id o project-name è richiesto.
• project-name viene risolto utilizzando GET /api/v1/projects.
• La corrispondenza del nome è esatta e senza distinzione tra maiuscole e minuscole.
• Se più di un progetto attivo corrisponde allo stesso nome, l'esecuzione fallisce con un errore di ambiguità.
• I valori richiesti possono essere forniti tramite flag o variabili d'ambiente; i flag hanno la precedenza.

Connessione

• https è richiesto per host non locali.
• Per ambienti di test/non produzione puoi usare:
  • --allow-insecure, oppure
  • CTWALL_ALLOW_INSECURE=true.
• Per certificati HTTPS autofirmati (solo test/non produzione) puoi usare:
  • --skip-tls-verify, oppure
  • CTWALL_SKIP_TLS_VERIFY=true.

Sicurezza

Vedi

Licenza

DepAlert è concesso in licenza secondo i termini della licenza BSD 3-Clause