🛡️ Sentinel — Spiegatore CLI per CVE

"Questa CVE mi riguarda?" — risposta in secondi, non ore.

Sentinel prende un ID CVE, recupera dati da NVD, OSV.dev e MITRE, poi usa Claude per produrre un briefing chiaro e attuabile in 5 sezioni sulla vulnerabilità.

Installazione

cd sentinel/
pip install -e .

Configurazione

# Richiesto: chiave API Anthropic
sentinel config set api-key sk-ant-...

# Opzionale: chiave API NVD (limiti più alti di frequenza)
sentinel config set nvd-key xxxxxxxx-xxxx-...

# Oppure usa le variabili d'ambiente
export ANTHROPIC_API_KEY=sk-ant-...
export NVD_API_KEY=xxxxxxxx-xxxx-...

Utilizzo

# Spiega una CVE (report in 5 sezioni con output colorato nel terminale)
sentinel cve CVE-2024-3094

# Scegli la persona di output (vedi Persone più sotto)
sentinel cve CVE-2024-3094 --format exec       # Riepilogo Esecutivo / CISO
sentinel cve CVE-2024-3094 -f engineer          # Approfondimento tecnico dettagliato
sentinel cve CVE-2024-3094 -f devops            # Focalizzato sull'infrastruttura
sentinel cve CVE-2024-3094 -f security          # Report predefinito in 5 sezioni

# Funziona anche con scan
sentinel scan . --cve CVE-2024-3094 --format exec

# Output JSON
sentinel cve CVE-2024-3094 --json

# Output Markdown
sentinel cve CVE-2024-3094 --markdown

# Riepilogo breve di un paragrafo
sentinel cve CVE-2024-3094 --brief

# Salta cache, recupera dati freschi
sentinel cve CVE-2024-3094 --no-cache

# Modalità verbosa (mostra tempi e dettagli fonte)
sentinel cve CVE-2024-3094 -v

Persone di Output (--format / -f)

security (predefinito) — Analista di Sicurezza

Il classico briefing di vulnerabilità in 5 sezioni:

Sezione	Cosa risponde
🔍 Cos'è	Spiegazione in linguaggio semplice
💥 Come sfruttarla	Vettore d'attacco, riepilogo PoC, difficoltà
🚨 Chi deve preoccuparsi	Software interessato, versioni, ecosistemi
🛡️ Come applicare la patch in sicurezza	Passi di rimedio, link alla patch
✅ Cosa testare	Passi di verifica dopo la patch

exec — Dirigente / CISO

Una lettura di 10 secondi per dirigenti impegnati. Severità a semaforo, impatto aziendale, un'azione da intraprendere. Nessun gergo.

🔴 CRITICA — CVE-2024-3094 (Backdoor XZ)

Una backdoor è stata inserita in una libreria di compressione Linux core utilizzata sulla maggior parte dei server.
Gli aggressori possono intercettare e modificare i dati su qualsiasi sistema che esegue xz 5.6.0-5.6.1.
È richiesto un downgrade immediato — stima 15-30 min per server, nessun downtime previsto.

Rischio: Compromissione della supply chain — alta severità, sfruttamento attivo
Impatto: Tutta l'infrastruttura Linux che esegue versioni interessate
Azione necessaria: Downgrade di xz alla 5.4.6. Verifica con `xz --version`.

engineer — Ingegnere del Software

Approfondimento tecnico dettagliato con versioni esatte, comandi di upgrade, pattern grep e passi di test:

Sezione	Focus
📦 Librerie e Versioni Interessate	Intervalli di versione esatti, catene di dipendenze
🔧 Rimedio a Livello di Codice	Comandi di upgrade specifici, modifiche di configurazione
🔍 Cosa Cercare con Grep	Pattern da cercare nel tuo codebase
🧪 Come Testare la Correzione	Comandi di verifica, test di regressione
⚠️ Modifiche Rottura	Deprecazioni, differenze comportamentali

devops — DevOps / SRE

Focalizzato sull'infrastruttura con container, K8s, CI/CD e monitoraggio:

Sezione	Focus
🏗️ Infrastruttura Interessata	Immagini di base, container, servizi cloud
🚀 Impatto sul Deploy	Strategia di aggiornamento rolling, valutazione downtime
🔄 Piano di Rollback	Come tornare indietro se la patch causa problemi
📊 Monitoraggio e Rilevamento	Log, alert, rilevamento dello sfruttamento
🚨 Passi di Risposta agli Incidenti	Passo dopo passo se sfruttato attivamente

Scansione SDK Mobile

Sentinel rileva dipendenze nelle configurazioni di build delle app mobili che gli scanner standard non trovano:

Ecosistema	File Analizzati	File Lock (preferito)
Android (Gradle)	build.gradle, build.gradle.kts, gradle/libs.versions.toml	—
iOS (CocoaPods)	Podfile	Podfile.lock
iOS (Swift PM)	Package.swift	Package.resolved
Flutter (Dart)	pubspec.yaml	pubspec.lock

# Scansiona un progetto Android
sentinel scan ./my-android-app --cve CVE-2024-XXXX

# Scansiona un progetto iOS
sentinel scan ./my-ios-app --cve CVE-2024-XXXX

# Scansiona un progetto Flutter
sentinel scan ./my-flutter-app

Caratteristiche:

• Risolve i riferimenti a variabili Gradle ($firebaseBomVersion) da gradle.properties e blocchi ext {}
• Analizza i cataloghi di versione Gradle (libs.versions.toml)
• Gestisce le subspec CocoaPods (Firebase/Analytics)
• Preferisce i file lock rispetto ai manifest per versioni risolte accurate
• Supporta file Gradle sia in DSL Groovy che Kotlin

Scanner BOM Runtime K8s

Scansiona il tuo cluster Kubernetes per immagini container vulnerabili:

# Scansiona tutti i namespace
sentinel scan --k8s

# Scansiona namespace specifico
sentinel scan --k8s --namespace production

# Controlla una CVE specifica nel cluster
sentinel scan --k8s --cve CVE-2024-3094

# Genera SBOM per tutte le immagini in esecuzione
sentinel scan --k8s --sbom

# Scansiona un'immagine specifica (nessuna connessione al cluster necessaria)
sentinel scan --k8s --image nginx:1.25

Configurazione RBAC K8s

Sentinel necessita di accesso in sola lettura. Applica il manifest RBAC minimale:

kubectl apply -f config/k8s-rbac.yaml

Questo crea un ServiceAccount sentinel-readonly con solo permessi get e list su pod, namespace, deployment, replicaset, daemonset e statefulset. Nessun accesso in scrittura.

Analisi del Percorso di Esecuzione

Determina se una CVE colpisce effettivamente il tuo codice tracciando se le funzioni vulnerabili sono raggiungibili dai punti di ingresso:

# Analisi completa con interpretazione Claude
sentinel scan . --cve CVE-2024-22195 --execution-path

# Solo locale (nessun dato inviato esternamente)
sentinel scan . --cve CVE-2024-22195 --execution-path --local-only

Verdetti:

• 🔴 RAGGIUNGIBILE — punto di ingresso → ... → chiamata a funzione vulnerabile trovata
• ✅ NON_RAGGIUNGIBILE — pacchetto vulnerabile importato ma funzione vulnerabile mai chiamata
• 🟡 SOLO_IMPORTATO — il pacchetto è una dipendenza ma mai importato direttamente nel codice
• 🟠 INCONCLUSIVO — dispatch dinamico, reflection o pattern complessi rilevati

Sicurezza: Quali dati lasciano il tuo ambiente?

Modalità	Dati inviati esternamente
--local-only	Nessun dato — analisi AST puramente locale
Default	Solo metadati sanitizzati: nomi di funzioni, nomi di import, archi del grafo delle chiamate (lista nodi/archi), descrizione CVE. Mai codice sorgente.

Tutti i dati inviati a Claude sono registrati in ~/.sentinel/audit.log per revisione.

Gestione Cache

sentinel cache clear    # Cancella tutti i dati nella cache

Configurazione

La configurazione è memorizzata in ~/.sentinel/config.json. Cache in ~/.sentinel/cache.db.

sentinel config set api-key <key>
sentinel config set nvd-key <key>
sentinel config set model <model-name>
sentinel config get api-key

🌐 Server Webhook e Integrazioni

Sentinel include un server FastAPI che accetta comandi da Slack, Microsoft Teams, Telegram e una API REST generica.

Avvia il Server

sentinel server start                    # Porta predefinita 8080
sentinel server start --port 9090        # Porta personalizzata
sentinel server start --workers 4        # Più worker
sentinel server status                   # Controlla se in esecuzione

API REST