dobybaxter127/nimbus-vestigeUn motore di ricostruzione forense per la risposta agli incidenti nel cloud e nell'identità.
Un motore di ricostruzione forense per la risposta agli incidenti cloud e di identità.
Data la telemetria frammentata di cloud, SaaS e identità — log del control plane, eventi di accesso, attività di token e consenso — NV ricostruisce come un'intrusione si è molto probabilmente spostata tra account e servizi, elenca gli altri percorsi più probabili che avrebbe potuto prendere e riporta ogni passaggio con una confidenza calibrata e spiegabile. Rifiuta di affermare ciò che le evidenze non possono sostenere.
Il rilevamento ti dice che qualcosa è successo. Nimbus Vestige ti dice come — e cos'altro.
Le intrusioni moderne non "irrompono". Accedono. L'identità è ora il principale vettore d'attacco, coinvolta nella grande maggioranza delle indagini di incident response cloud, e la maggior parte delle intrusioni attraversa più superfici — identità più cloud più SaaS più endpoint. La telemetria che le registra è frammentata e incoerente, il che già costringe i responder a ricostruire la storia manualmente da dati incompleti.
Quella ricostruzione manuale è lenta e fallisce in modo prevedibile: il responder si ancora alla prima narrazione plausibile e perde quella reale. NV automatizza la ricostruzione e attacca direttamente questa modalità di fallimento presentando sempre lo spazio classificato dei percorsi plausibili, non una singola storia.
Fondamentalmente, NV fa questo con l'onestà come prodotto. Il nemico dichiarato del mercato è la confidenza a scatola chiusa — uno strumento che afferma una conclusione senza mostrare il proprio lavoro. Ogni numero prodotto da NV è riconducibile alla specifica evidenza che lo ha generato, e qualsiasi cosa non possa sostenere viene trattenuta piuttosto che ipotizzata.
NV non è un rilevatore, uno scanner, un revisore o un esecutore di attacchi. Questi strumenti ti dicono che qualcosa è successo e lo misurano. NV lavora all'indietro — ricostruzione abduttiva del meccanismo dai pattern, attraverso un patrimonio di identità frammentato.
Il blue team si rigenera; il red team si commoditizza. Gli strumenti offensivi trovano un insieme finito e correggibile di vulnerabilità e vengono integrati in pipeline di sicurezza CI/CD automatizzate. Ricostruire come è avvenuta un'intrusione non si risolve mai — gli attaccanti continuano a inventare, quindi il bisogno è permanente e si auto-rinnova.
Il motore è indipendente dal substrato. La logica centrale — ricostruire il meccanismo dai pattern, con confidenza calibrata e un binario di arresto — è impegnata prima su cloud/identità, ma in seguito sarà portata su rete, endpoint e OT. L'obiettivo può cambiare senza riscrivere la tesi.
La ricostruzione abilita l'hardening. Una volta che sai come sono entrati — e quali altre porte erano aperte — costruisci le difese. I percorsi non intrapresi ma plausibili sono un backlog di hardening, spesso di valore superiore alla ricostruzione stessa, perché la maggior parte delle violazioni sfrutta esposizioni prevenibili, non tecniche innovative.
Degrada con eleganza sull'intrusione nuova — proprio l'incidente che conta di più. Un motore a firme/regole diventa cieco su una zero-day; il nucleo abduttivo di NV produce comunque un percorso più probabile, onestamente segnalato come a confidenza inferiore.
L'onestà è un fossato. Una confidenza calibrata e basata su casi con alternative classificate è esattamente ciò che il mercato dice di volere e ciò che i concorrenti a scatola chiusa strutturalmente non possono offrire senza una riprogettazione.
Log grezzi del provider → grafo normalizzato eventi/entità → motore di ricostruzione → JSON → GUI.``` O365 / Entra audit logs nv_extract_identity_events.py AWS CloudTrail (IAM/STS/S3) nv_extract_cloudtrail_events.py (ingest + normalize) ▼ normalized identity events (JSONL) ← one event model, any substrate │ nv/graph.py (typed per-actor timelines) ▼ reconstruction engine ├─ nv/patterns.py known layer: ATT&CK identity pattern library ├─ nv/providers.py provider packs: per-substrate op→ATT&CK vocab (Entra + AWS) ├─ nv/validation.py Phase 3: provenance + integrity gate on every pattern ├─ nv/feeds.py live ATT&CK STIX / TAXII / Sigma clients + scheduler ├─ nv/confidence.py evidence-corroboration scorer (calibratable weights) ├─ nv/calibration.py fit + measure confidence against labeled ground truth ├─ nv/reconstruct.py most-likely chain + ranked competing paths + trust floor └─ nv/scope.py authorized-scope gate (refuses unauthorized tenants/accounts) │ run_nv.py ▼ reconstruction.json ──► nv_gui.html (embedding canvas + two-column view + trust slider)
L'interfaccia grafica è un **puro livello di visualizzazione** — renderizza l'output del motore e consente all'analista di spostare
la soglia di fiducia. Non contiene alcuna logica di ricostruzione propria.
---
## Il modello di fiducia (la credibilità dell'intero prodotto)
Ogni passaggio porta una confidenza in [0, 1], costruita tramite **corroborazione delle prove**:```
confidence = per-technique base rate
+ bonus for each independent corroborating signal
(source IP, device, successful outcome, temporal adjacency, broad-consent flags)
− penalty for missing signals (e.g. no source IP to corroborate origin)
I punteggi dei percorsi combinano i loro collegamenti tramite la media geometrica, quindi un collegamento debole trascina onestamente il percorso verso il basso invece di essere diluito dalla media.
Ogni peso di cui sopra — i tassi di base per tecnica, i bonus per segnale, le penalità per assenza — risiede in un'unica tabella PARAMS in nv/confidence.py. Questi sono i priori v1 di NV e sono calibrabili: nv/calibration.py può ricalibrarli rispetto a ground truth etichettato e il motore caricherà il risultato, ricadendo sui priori v1 quando non viene fornita alcuna calibrazione (vedi sotto).
La regola di withhold, incorporata nel contratto di output del motore — non solo nell'interfaccia. Sotto la soglia, un passo viene trattenuto. Trascinare la soglia è il compromesso onestà-versus-copertura reso concreto: verso l'alto per una fiducia rigorosa/elevata, verso il basso per una copertura permissiva/elevata. La soglia predefinita è una decisione editoriale su dove NV si colloca prima che l'analista la tocchi.
I pesi v1 sono difendibili, ma sono priori. nv/calibration.py li ottimizza rispetto a ground truth etichettato — eventi in cui sappiamo quali facevano parte dell'intrusione e quali erano benigni — e, cosa cruciale, misura se l'ottimizzazione ha effettivamente aiutato, quindi una calibrazione viene adottata solo se riduce l'errore di calibrazione piuttosto che limitarsi a spostare numeri.
Confidenza calibrata significa una cosa: la confidenza di NV per un passo dovrebbe essere uguale alla probabilità che il passo fosse realmente sul percorso dell'attacco. Quindi la confidenza di ogni evento etichettato viene trattata come una probabilità prevista e l'harness adatta:
Le soglie verified/withheld sono policy, non calibrazione, e restano invariate.
Riporta Brier score, log-loss, ECE, AUC, una tabella di affidabilità e una scansione della soglia di fiducia (recall dei veri passi vs tasso di falsi positivi benigni a ogni soglia), prima e dopo — così il compromesso onestà-versus-copertura è leggibile piuttosto che un singolo numero.```bash
python3 calibrate.py --labeled run_labeled.jsonl --origin live
--run-label "badzure-2026-07 tenant-x" --out calibration.json
python3 calibrate.py --out calibration.json
python3 run_nv.py events.jsonl out.json --authorize t.onmicrosoft.com
--calibration calibration.json
**Fonte di ground truth.** L'input onesto è la telemetria di un'esecuzione BadZure / MAAD-AF in un
tenant reale, etichettata unendo il log di audit unificato con il record di attività dello stesso
strumento di attacco (ogni evento causato dallo strumento è on-chain; tutto il resto è benigno —
vedi `LABELED_SCHEMA` in `nv/calibration.py`). Finché non lo punti verso un'esecuzione reale,
`eval/calibration_cases.py` fornisce un corpus **proxy** dalla forma documentata, e ogni artefatto
calibrato su di esso viene marcato `source="proxy"` nella sua provenienza, così un fit proxy non
potrà mai essere scambiato per uno live. `calibration.proxy.json` è l'artefatto proxy incluso.
Sul corpus proxy incluso il fit è un netto miglioramento — Brier 0.398 → 0.045, ECE
0.576 → 0.081, AUC 0.81 → 0.91, e il tasso di falsi positivi benigni alla soglia 0.60
crolla da 0.69 a 0.00 (le prior v1 erano gravemente troppo fiduciose sull'attività benigna).
Il proxy è deliberatamente conservativo; solo un'esecuzione su tenant live produce i pesi che
dovresti effettivamente distribuire.
## Integrità della fiducia (Fase 3)
Due controlli di prim'ordine proteggono la ricostruzione da input errati:
- **Gate dell'ambito autorizzato** (`nv/scope.py`) — NV rifiuta di eseguire su qualsiasi
patrimonio non presente nella lista autorizzata. Eseguire con `--authorize <tenant-domain>`
per ogni patrimonio su cui sei autorizzato a indagare.
- **Validazione della sorgente dei pattern** (`nv/validation.py`) — nessun pattern entra nella
libreria senza superare: (1) allowlist della sorgente attendibile, (2) checksum del contenuto /
controllo di manomissione, (3) correttezza strutturale dello schema, (4) id di tecnica valido
in stile ATT&CK. Ogni pattern ammesso conserva un record di audit; i rifiuti vengono registrati
con una motivazione. Un feed avvelenato o malformato viene fermato a monte prima che possa
produrre una falsa ricostruzione. È lo stesso scetticismo che il motore applica alle evidenze,
esteso ai pattern stessi.
---
## Mantenere aggiornata la conoscenza (restare al passo con l'evoluzione degli attaccanti)
Un motore di ricostruzione è aggiornato tanto quanto la sua libreria di pattern e la sua capacità
di gestire ciò che la libreria non ha mai visto. NV affronta l'obsolescenza su **due fronti
indipendenti**, per scelta progettuale:
### 1. Il livello noto rimane aggiornato grazie a una pipeline di aggiornamento validata
La libreria non è hardcoded — `nv/patterns.py` carica ogni pattern (incluso il set
integrato) tramite `nv/validation.py`, quindi i feed esterni entrano dallo stesso percorso
attendibile. I client di rete live che scaricano questi feed secondo una pianificazione sono
implementati in `nv/feeds.py` e guidati da `update_feeds.py`. Sorgenti, per livelli di fiducia:
- **MITRE ATT&CK (STIX)** — la tassonomia autorevole delle tecniche. Il connettore legge
l'indice STIX di ATT&CK, scarica l'ultima release enterprise e aggiorna nome e tattica
autorevoli della tecnica per ogni operazione su cui NV ragiona —
scartando qualsiasi operazione la cui tecnica ATT&CK abbia nel frattempo revocato o
deprecato. NV mantiene la proprietà del legame operazione→tecnica e del prior del tasso
di base; ATT&CK possiede la tassonomia.
- **CTI verificata via TAXII 2.1** — un client completo discovery → api-root → collection →
objects. Scarica gli oggetti STIX attack-pattern da una collection CTI verificata e
aggiorna le tecniche tracciate da NV. Pesata al di sotto di ATT&CK.
- **Ruleset comunitario Sigma** — scaricato come archivio git; ogni regola cloud/identity che
nomina un'operazione O365/Entra e porta un tag `attack.tXXXX` diventa un
candidato operazione→tecnica, con un tasso di base derivato dal `level` di severità della
regola e poi ridotto dal peso della sorgente comunitaria. Le regole che non mappano vengono
saltate con una motivazione, mai indovinate.
In caso di collisione su un'operazione, l'unione viene ordinata per fiducia ascendente prima del
commit, quindi un legame ATT&CK autorevole vince sempre su uno comunitario; i contenuti di livello
inferiore vengono comunque ammessi e registrati nell'audit come corroborazione.
`update_library(candidates)` re-inserisce l'intero set attraverso la validazione e ricostruisce
la libreria atomicamente, così un feed avvelenato non potrà mai lasciare la libreria parzialmente
aggiornata.
**Due allowlist, non una.** La validazione filtra già tramite il tag della sorgente; i connettori
aggiungono un'allowlist *host* a livello di rete, quindi un connettore può scaricare solo da un
host attendibile su TLS — l'equivalente a livello di trasporto dell'allowlist delle sorgenti e
una protezione contro un URL di feed dirottato o scritto male. Ogni fetch registra lo sha256 del
payload grezzo, l'URL e l'orario come provenienza, così un successivo re-pull può rilevare
mutazioni a monte.
**Perché il livello di validazione conta di più man mano che i feed crescono:** più automatizzi
gli aggiornamenti, più una pipeline di auto-aggiornamento diventa un rischio di fiducia
travestito — un feed sbagliato o avvelenato inietta pattern falsi e produce false
ricostruzioni. NV tratta l'ingestione come avversaria: allowlist, checksum, schema e audit trail
su ogni pattern, a ogni aggiornamento.
### 2. Il livello abduttivo copre ciò che nessun feed ha ancora nominato
I feed sono sempre in ritardo rispetto al tradecraft più recente. Il nucleo abduttivo è la
salvaguardia: quando un'operazione osservata non corrisponde a **nessun** pattern della libreria,
NV non la scarta — ricostruisce il percorso più probabile dai primi principi e lo contrassegna con
`no known match` a confidenza ridotta. Questo è validato nella suite di eval
(`eval/ground_truth_cases.py`), dove un passo di furto di token di managed identity
deliberatamente sconosciuto viene rilevato, sequenziato correttamente e onestamente ridotto di
peso al di sotto della soglia di fiducia.
Insieme, questi elementi significano che NV non diventa mai del tutto obsoleto: il livello noto
traccia la frontiera pubblicata attraverso una pipeline resistente all'avvelenamento, e il livello
abduttivo impedisce allo strumento di diventare cieco di fronte all'intrusione che la frontiera
non ha ancora raggiunto.
### Cadenza di aggiornamento suggerita
`nv/feeds.py` porta una cadenza per-feed e `update_feeds.py` scarica solo ciò che è dovuto,
quindi può essere inserito direttamente in cron o in un timer systemd:
- ATT&CK STIX — 90 giorni (poche release ufficiali all'anno).
- CTI/TAXII — 7 giorni (man mano che il feed pubblica), sempre tramite validazione.
- Sigma — 30 giorni.```bash
# run whatever is due, keeping state under ./.nv_feeds (cron-friendly)
python3 update_feeds.py
# force all feeds now but only report what would change
python3 update_feeds.py --force --dry-run
# run fully offline against captured fixtures (no network)
python3 update_feeds.py --offline eval/fixtures --force
Dopo qualsiasi modifica alla libreria, ri-esegui eval/run_eval.py per confermare che le forme di attacco note
vengano ancora ricostruite, eval/validation_cases.py per confermare che il gate rifiuti ancora input non validi, e
eval/feeds_offline_test.py per confermare che il percorso dei feed sia integro end-to-end.
La ricostruzione mostrata in nv_gui.html è basata su un set di dati di ricerca pubblico
— il corpus del log di controllo unificato di Office 365 di invictus-ir — non dal tenant live
di nessuna azienda. Esiste così che il motore possa essere dimostrato e provato end-to-end senza
la cooperazione di nessuno. Per usare NV sul serio, un'organizzazione collega i propri dati di audit Entra/M365
come descritto di seguito. Nessun dato proprietario o del cliente è incluso in alcuna parte di
questo progetto.
NV gira ovunque tu lo esegua; i tuoi log non devono mai abbandonare il tuo ambiente. Quattro passaggi:
1 — Esporta i tuoi log di controllo. NV legge il log di controllo unificato di Microsoft 365. Puoi ottenerlo
da Microsoft Purview (Ricerca audit → esporta CSV), dal cmdlet Search-UnifiedAuditLog
di Exchange Online PowerShell, dagli endpoint auditLogs / signIns di Microsoft Graph
oppure da un'esportazione Sentinel/SIEM di OfficeActivity e SigninLogs.
2 — Normalizzalo nel modello di eventi su cui NV ragiona:```bash python3 nv_extract_identity_events.py your_audit_export.csv your_events.jsonl
Questo mantiene gli accessi, le concessioni di consenso, le modifiche a service principal e ai ruoli, e l'accesso
alle cassette postali — incluse le operazioni di identità che NV non ha mai nominato, così raggiungono comunque
il livello abduttivo — e scarta il resto. Legge un CSV con la colonna standard `AuditData`
oppure JSON/JSONL in cui ogni record è un oggetto `AuditData` (la forma in cui
viene distribuito il corpus di ricerca invictus-ir).
**3 — Ricostruzione, con ambito limitato.** Il motore rifiuta di operare su un tenant che non hai
esplicitamente autorizzato:```bash
python3 run_nv.py your_events.jsonl reconstruction.json \
--authorize yourtenant.onmicrosoft.com
4 — Visualizza. Apri nv_gui.html e fai clic su ⤒ carica reconstruction.json per puntarlo al
file che il motore ha appena generato — la stessa schermata mostra quindi l'incidente, le
entità e le bande di confidenza. Ogni punto sulla tela di embedding riesegue la
ricostruzione per quell'entità al clic.
Il motore è indipendente dal substrato — solo il vocabolario delle operazioni è specifico del provider
(nv/providers.py). Il percorso AWS segue gli stessi tre passaggi su CloudTrail:```bash
python3 nv_extract_cloudtrail_events.py cloudtrail.json aws_events.jsonl
python3 run_nv.py aws_events.jsonl reconstruction.json --authorize aws:123456789012
L'ingest mantiene gli eventi IAM/STS/sign-in (incluse le nuove operazioni IAM, così raggiungono lo
strato abduttivo) più le letture di oggetti S3, e limita l'ambito all'**account** AWS piuttosto che a un
dominio tenant. Lo stesso nucleo abduttivo, modello di confidenza e soglia di fiducia restano invariati.
La GUI include anche un **banner dei dati demo** e una guida in-app "Connetti i tuoi dati",
così chiunque la apra capisce che la ricostruzione è composta da dati di esempio pubblici finché
non collega i propri.
## Struttura del progetto```
run_nv.py reconstruction engine entrypoint (scope-gated)
nv_extract_identity_events.py ingest: M365/Entra unified audit log -> event model
nv_extract_cloudtrail_events.py ingest: AWS CloudTrail -> event model [iteration 3]
update_feeds.py pull + validate threat-intel feeds on a cadence [iteration 1]
calibrate.py fit confidence weights from labeled ground truth [iteration 2]
nv/ the engine package
graph.py patterns.py validation.py confidence.py reconstruct.py scope.py
providers.py per-substrate op->ATT&CK vocabulary packs (Entra + AWS) [iteration 3]
feeds.py ATT&CK STIX / TAXII 2.1 / Sigma clients + scheduler [iteration 1]
calibration.py metrics + parameter fit [iteration 2]
eval/ evals + offline fixtures (no network, no tenant)
nv_gui.html pure view layer (loads engine reconstruction.json)
calibration.proxy.json bundled proxy calibration artifact [iteration 2]
Esegui tutto dalla root del progetto in modo che il pacchetto nv sia importabile.
python3 nv_extract_identity_events.py auditrecords.csv nv_identity_events.jsonl
python3 run_nv.py nv_identity_events.jsonl reconstruction.json
--trust-floor 0.6 --authorize your-tenant.onmicrosoft.com
Mantieni aggiornata la libreria di pattern e calibra la confidenza:```bash
python3 update_feeds.py # pull + validate feeds that are due
python3 calibrate.py --labeled run.jsonl --origin live --out calibration.json
python3 eval/run_eval.py # attack shapes reconstruct correctly python3 eval/validation_cases.py # poisoned patterns are rejected python3 eval/feeds_offline_test.py # feed connectors + scheduler (offline) python3 eval/providers_aws_test.py # AWS chain reconstructs through the same engine python3 calibrate.py # calibration harness on the bundled proxy corpus
---
## Stato
**Funziona end-to-end su dati reali** (dataset O365 di invictus-ir), lungo l'intero piano:
| Fase | Elemento | Stato |
|---|---|---|
| 1 | Modello normalizzato evento/entità | fatto |
| 1 | Ingest + normalizzazione (testa di ponte Entra/M365) | fatto |
| 2 | Livello noto (libreria di pattern ATT&CK) | fatto |
| 2 | Modello di confidenza basato sulla corroborazione delle evidenze | fatto |
| 2 | Soglia di fiducia nel contratto di output | fatto |
| 2 | Nucleo abduttivo (livello ignoto) | fatto, provato con valutazione |
| 2 | Ipotesi alternative classificate | fatto |
| 3 | Livello di validazione delle sorgenti di pattern | fatto |
| 3 | Controllo dello scope autorizzato | fatto |
| 3 | Connettori feed live (ATT&CK STIX / TAXII / Sigma) + scheduler | fatto |
| 4 | Schermata a due colonne su output reale del motore | fatto |
| 4 | Canvas embedding / similarità | fatto |
| 4 | Ricostruzione per entità guidata dal canvas (il click riesegue la catena) | fatto |
| 4 | La GUI carica il `reconstruction.json` del motore (puntala al tuo file) | fatto |
| 4 | Substrato multi-provider (AWS CloudTrail, provato con valutazione) | fatto |
| 5 | Estetica / theming | fatto |
| 5 | Harness di calibrazione della confidenza + integrazione col motore | fatto |
### Lacune note e oneste (prossime iterazioni)
- **Numeri di calibrazione su tenant reale.** L'harness di calibrazione è completo e
l'interfaccia è provata, ma il `calibration.proxy.json` distribuito è calibrato su
dati proxy dalla forma documentata. I pesi distribuibili richiedono di eseguire
l'harness su una run reale di BadZure / MAAD-AF — un passo operativo per chi adotta
lo strumento.
- **Crescita del vocabolario guidata dai feed.** I connettori aggiornano il NV di
operazioni su cui il sistema già ragiona; consentire a un feed di *introdurre* una
nuova operazione (e collegarla alla classificazione iniziale/pivot/raccolta) è
lavoro futuro.
- **Profondità del secondo provider.** AWS è incluso come prova di indipendenza dal
substrato (pack + ingest + eval), ma solo IAM/STS/S3. Ampliare il pack AWS,
aggiungere connettori feed specifici per provider e un terzo substrato (GCP, Okta)
sono i prossimi passi.
---
## Licenza
Nimbus Vestige è **source-available** sotto la **PolyForm Noncommercial License
1.0.0** (vedi [LICENSE](https://gitlab.com/dobybaxter127/nimbus-vestige/-/blob/main/LICENSE)). L'intero strumento — motore di ricostruzione,
ingest di entrambi i provider, GUI e harness di valutazione — è libero da ispezionare,
eseguire e usare per qualsiasi scopo **non commerciale**: progetti personali, ricerca,
istruzione, organizzazioni non profit e valutazione. Leggi ogni riga prima di decidere.
**L'uso commerciale richiede una licenza a pagamento** — usarlo in un prodotto o
servizio che vendi o ospiti, all'interno di sistemi di produzione o interni di
un'azienda a scopo di lucro, o in incarichi di incident response o consulenza a
pagamento. Vedi
[COMMERCIAL-LICENSE.md](https://gitlab.com/dobybaxter127/nimbus-vestige/-/blob/main/COMMERCIAL-LICENSE.md).
---
### Autore
Doby Baxter 2026