big-comfy/deadairTrova le regole di rilevamento nel tuo SIEM che operano alla cieca.
<p align="center">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="docs/assets/banner-dark.svg">
<img alt="deadair - SIEM detection coverage health" src="https://raw.githubusercontent.com/big-comfy/deadair/HEAD/docs/assets/banner-light.svg" width="760">
</picture>
</p>
<p align="center">
<a href="https://github.com/alephnull-sh/deadair/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/alephnull-sh/deadair/actions/workflows/ci.yml/badge.svg"></a>
<a href="https://github.com/alephnull-sh/deadair/releases"><img alt="Release" src="https://img.shields.io/github/v/release/alephnull-sh/deadair"></a>
<img alt="Go 1.26" src="https://img.shields.io/badge/go-1.26-00ADD8">
<a href="https://github.com/big-comfy/deadair/blob/main/LICENSE"><img alt="License: Apache-2.0" src="https://img.shields.io/badge/license-Apache--2.0-blue"></a>
</p>
<p align="center">
<strong>deadair verifica se le detection SIEM abilitate dispongono ancora della telemetria di cui hanno bisogno.</strong><br>
Segnala dati mancanti o obsoleti, ritardi di ingest e discrepanze di schema.
</p>
<p align="center">
Esecuzione locale · Sola lettura · Nessun agente · Nessun caricamento di telemetria
</p>
<p align="center">
<a href="https://alephnull-sh.github.io/deadair/">Leggi l'approfondimento tecnico</a> ·
<a href="https://www.detectionengineering.net/i/208193682/detection-engineering-gem">In evidenza su Detection Engineering Weekly</a> ·
<a href="https://tldrsec.com/p/tldr-sec-341">In evidenza su tl;dr sec #341</a>
</p>
<p align="center">
<a href="https://alephnull-sh.github.io/deadair/#elastic-demo"><img alt="Una scansione Elastic che mostra input mancanti e obsoleti, campi mancanti ed eventi in ritardo" src="https://assets.kitploit.com/production/public/readmes/791/fc36f93c2d5fcaceffd370452b89b908a930eb10e810c0187fb3bba59cb156dd.png" width="860"></a>
</p>
<p align="center">
<sub>Campi mancanti ed eventi in ritardo in un lab Elastic usa e getta. Apri l'immagine per la breve registrazione con controlli di riproduzione, oppure riproducila con <code>make record-scan-lab</code>.</sub>
</p>
## Perché deadair
Una regola può essere abilitata, pianificata e priva di errori dopo che i dati di cui ha bisogno sono scomparsi. deadair
legge l'inventario delle regole attive, risolve gli input di ciascuna regola usando la semantica nativa del backend e
verifica le fonti concrete che vi stanno dietro.
Rileva:
- regole i cui selettori di indice, alias o data-stream non risolvono a nulla;
- regole con selettori misti in cui un input dichiarato è scomparso mentre un altro si risolve ancora;
- regole le cui fonti corrispondenti sono tutte obsolete o vuote;
- su Elastic, regole in esecuzione con campi dichiarati mancanti;
- su Elastic e sulle regole Sentinel Scheduled idonee, una finestra cieca di ingest-lag;
- su Sentinel, regole le cui fonti note usano un piano di tabella Basic o Auxiliary incompatibile;
- su Elastic e OpenSearch, telemetria sana che nessuna detection abilitata legge.
deadair supporta Elastic Security, OpenSearch Security Analytics e Microsoft Sentinel.
## Avvio rapido
Scarica un binario per macOS, Linux o Windows da
[GitHub Releases](https://github.com/alephnull-sh/deadair/releases), oppure installa con Go:
```sh
go install github.com/alephnull-sh/deadair/cmd/deadair@latest
```
Stampa la configurazione di sola lettura per il tuo SIEM:
```sh
deadair setup elastic # Elastic Security
deadair setup opensearch # OpenSearch Security Analytics
deadair setup sentinel # Microsoft Sentinel
```
Esegui una configurazione, poi verifica ed esegui la scansione:
```sh
deadair check # verifica che la credenziale possa eseguire la scansione
deadair scan # valuta regole attive e telemetria
```
I codici di uscita sono stabili: `0` supera il gate configurato, `1` indica finding soggetti a gate e `2` indica che la scansione è fallita.
Per analizzare una fonte e le detection che la consumano:
```sh
deadair scan --json-out report.json --html-out report.html
deadair inspect --source CommonSecurityLog report.json
```
Usa un nome di fonte dal tuo report. La [guida all'analisi](https://github.com/big-comfy/deadair/blob/main/docs/investigate.md) copre anche
i singoli feed Sentinel, la manutenzione e il monitoraggio del ripristino.
## Come funziona
| Fase | Cosa fa deadair |
|---|---|
| Inventario | legge le detection abilitate e gli input che dichiarano |
| Risoluzione | usa la risoluzione nativa degli indici su Elastic e OpenSearch; su Sentinel, combina l'analisi KQL con evidenze da tabelle, watchlist, saved-function, ASIM e cross-workspace mappate |
| Misurazione | verifica freschezza e tempistica delle fonti, oltre a schema e storage dove il backend li supporta |
| Report | emette output su terminale, JSON, HTML, rollup di flotta e metriche Prometheus con le evidenze dietro ogni verdetto |
Sentinel segue lo stesso modello regola-a-fonte e aggiunge watchlist letterali, saved function, parser
ASIM, workspace mappati e lineage delle tabelle di riepilogo. Mostra anche quando una fetta filtrata di una
tabella condivisa è diventata silenziosa o una pipeline di riepilogo è rimasta indietro.
La [guida all'uso](https://github.com/big-comfy/deadair/blob/main/docs/usage.md#microsoft-sentinel) descrive le regole di evidenza, e il
[registro di validazione](https://github.com/big-comfy/deadair/blob/main/docs/validation.md#sentinel-live-conformance) documenta la copertura dei test live.
<p align="center">
<a href="https://alephnull-sh.github.io/deadair/#sentinel-demo"><img alt="Un feed firewall di Londra silenzioso e la sua detection dipendente all'interno di Sentinel CommonSecurityLog" src="https://raw.githubusercontent.com/big-comfy/deadair/main/docs/assets/sentinel-lab.png" width="860"></a>
</p>
<p align="center">
<sub>Due feed firewall condividono <code>CommonSecurityLog</code>. Uno si ferma; l'altro continua a riportare. La registrazione mostra le scansioni di fallimento e ripristino salvate. Vedi il <a href="https://github.com/big-comfy/deadair/blob/main/docs/validation.md#sentinel-live-conformance">registro di validazione</a> per le condizioni del lab.</sub>
</p>
deadair verifica se la telemetria di una detection è presente e sana. Non convalida la logica
della regola né dimostra che un attacco simulato farà scattare un alert. Per questi compiti usa la validazione statica delle regole e i test
end-to-end delle detection.
## Finding
| Finding | Significato | Prima verifica |
|---|---|---|
| nessuna fonte corrispondente | nessuno degli input della regola risolve a un indice, data stream o tabella Sentinel visibile | cambi di pattern, integrazioni mancanti e ambito della credenziale |
| tutte le fonti obsolete o vuote | ogni fonte risolta è inutilizzabile al momento | cadenza della fonte e percorso di ingest |
| campi mancanti | un campo dichiarato da una regola Elastic è assente o non ricercabile in una o più fonti risolte dopo che ogni mapping di fonte è stato letto | cambi di parser, package e mapping |
| finestra cieca di lag | il p95 dell'ingest lag di eventi accoppiati supera il margine di lookback della regola | intervallo della regola, lookback, override del timestamp e ritardo della pipeline |
| copertura parziale degli input | l'espressione completa si risolve, ma un selettore positivo al suo interno si risolve vuoto | migrazioni, selettori di fallback e alternative attese; informativo salvo che la policy lo sottoponga a gate |
| piano di fonte incompatibile | una regola Sentinel dipende da una tabella Basic o Auxiliary non idonea al percorso di evidenza delle regole di analisi | piano della tabella e tipo di regola |
| degrado della fonte | una fonte è obsoleta, vuota, a basso volume o con schema in deriva | storico della fonte e manutenzione prevista |
| telemetria inutilizzata | su Elastic o OpenSearch, i dati vengono archiviati ma nessuna detection locale abilitata vi risolve | regole disabilitate e raccolta intenzionale |
| produttore atteso silenzioso | un feed Sentinel configurato per vendor, prodotto o dispositivo non ha riportato entro la sua soglia | mittente e collector di quel feed |
| pipeline di riepilogo non sana | un job di riepilogo Sentinel rilevante è fallito o il suo ultimo successo è in ritardo | il record di esecuzione nativo e la query di riepilogo |
I finding su produttore e pipeline di riepilogo influenzano lo stato di uscita quando le loro classi sono selezionate nella
policy. Un feed di dispositivo silenzioso viene riportato separatamente dagli altri consumatori della sua tabella condivisa.
Ogni verdetto è limitato a ciò che la credenziale configurata può vedere. I report JSON includono le
espressioni configurate, le fonti risolte, il metodo di risoluzione, lo stato di valutazione, i metadati del backend
e le evidenze sulle capacità. Vedi la [guida all'uso](https://github.com/big-comfy/deadair/blob/main/docs/usage.md) per esempi pratici e triage.
## Connetti un SIEM
Elastic:
```sh
export DEADAIR_ES_URL=https://es.example.internal:9200
export DEADAIR_KIBANA_URL=https://kibana.example.internal:5601
export DEADAIR_API_KEY=<read-only-api-key>
deadair check
deadair scan --json-out report.json --html-out report.html
```
OpenSearch:
```sh
export DEADAIR_BACKEND=opensearch
export DEADAIR_OPENSEARCH_URL=https://opensearch.example.internal:9200
export DEADAIR_OPENSEARCH_USERNAME=deadair
export DEADAIR_OPENSEARCH_PASSWORD=<password>
deadair check
deadair scan
```
Microsoft Sentinel:
```sh
az login --tenant <tenant-id>
export DEADAIR_BACKEND=sentinel
export DEADAIR_AZURE_SUBSCRIPTION_ID=<subscription-id>
export DEADAIR_AZURE_RESOURCE_GROUP=<resource-group>
export DEADAIR_SENTINEL_WORKSPACE=<workspace-resource-name>
# Optional: JSON allowlist for literal workspace() targets.
# export DEADAIR_SENTINEL_REMOTES=/restricted/path/sentinel-remotes.json
deadair check
deadair scan
```
Prima che deadair valuti il workspace remoto mappato di una regola, quel workspace deve avere Sentinel
distribuito. Le mappature nella stessa sottoscrizione possono provare la disponibilità della fonte. Le regole
cross-subscription richiedono evidenze a runtime legate all'esatta identità della regola. Vedi i
[dettagli d'uso di Sentinel](https://github.com/big-comfy/deadair/blob/main/docs/usage.md#microsoft-sentinel) per le regole di evidenza, i limiti di workspace e
regione e le linee guida sulle prestazioni di Microsoft.
Usa i ruoli di sola lettura documentati per
[Elastic](https://github.com/big-comfy/deadair/blob/main/docs/credentials/elastic.md), [OpenSearch](https://github.com/big-comfy/deadair/blob/main/docs/credentials/opensearch.md) o
[Microsoft Sentinel](https://github.com/big-comfy/deadair/blob/main/docs/credentials/sentinel.md).
## CI, flotte e monitoraggio
```sh
# Gate a candidate rule against live source availability.
deadair scan --rule new-rule.json
# Fail only on new regressions between reports.
deadair diff yesterday.json today.json
# Scan multiple SIEM instances from one process.
deadair scan --fleet fleet.json
# Export cached scan results as Prometheus metrics.
deadair serve --interval 5m
```
`scan --rule` isola una regola o detector candidato nativo del backend da un backlog non correlato. `diff`
funziona con report redatti creati con la stessa chiave detenuta dal chiamante. La configurazione della flotta fa riferimento
ai segreti tramite variabili d'ambiente anziché memorizzare i valori dei segreti.
La [GitHub Action ufficiale](https://github.com/big-comfy/deadair/blob/main/docs/usage.md#gate-detection-changes) incapsula i gate per candidati a istanza singola
per Elastic, OpenSearch e Sentinel. Scrive un riepilogo del job, carica un report JSON
redatto e può applicare una policy deadair senza installare una regola. I workflow Sentinel autenticano
prima il runner su Azure; la Action non definisce input di credenziali Azure.
Vedi [comportamento del gate CI](https://github.com/big-comfy/deadair/blob/main/docs/usage.md#gate-detection-changes),
[deployment di flotte e MSSP](https://github.com/big-comfy/deadair/blob/main/docs/mssp.md) e gli [esempi Prometheus](https://github.com/big-comfy/deadair/blob/main/contrib) per configurazioni
da testare nel tuo ambiente.
## Backend testati
| Backend | Validazione live |
|---|---|
| Elastic Security | CI attendibile su 8.19.19 e 9.4.4 |
| OpenSearch Security Analytics | CI attendibile su 2.19.6 e 3.7.0 |
| Microsoft Sentinel | conformità opt-in registrata in workspace UK South usa e getta; vedi [stato di validazione](https://github.com/big-comfy/deadair/blob/main/docs/validation.md#sentinel-live-conformance) |
L'esecuzione di conformità Sentinel è manuale, non CI pianificata.
## Modello di sicurezza
- Tutte le chiamate agli adapter sono di sola lettura. Test attendibili su Elastic e OpenSearch più sonde separate
di lab Sentinel verificano che le identità di scansione documentate non possano eseguire scritture rappresentative.
- Report, HTML, file di stato e output della flotta vengono scritti con permessi `0600` sui sistemi POSIX.
- Le credenziali possono provenire da variabili d'ambiente o file, evitando segreti negli argomenti di processo.
- `--redact` sostituisce identificatori di tenant, regole, fonti, pattern, campi, dipendenze, lineage, provenienza,
workspace, watchlist, template e package con pseudonimi HMAC con chiave. Le espressioni di sonda delle dipendenze validate
e i loro argomenti KQL non vengono mai serializzati. Un
`--redact-key-file` generato da byte casuali abilita anch'esso la redazione e mantiene i nomi stabili
tra esecuzioni separate.
- L'exporter si associa al loopback per impostazione predefinita.
- deadair non ha comportamento di phone-home né telemetria d'uso.
Tratta i report come artefatti SOC sensibili: identificano detection cieche, nomi di fonti, lacune di schema
e raccolta inutilizzata.
## Documentazione
- [Guida all'uso](https://github.com/big-comfy/deadair/blob/main/docs/usage.md) — prime scansioni, evidenze dei report, finding, gate CI, stato e flotte
- [Analizzare una lacuna di telemetria](https://github.com/big-comfy/deadair/blob/main/docs/investigate.md) — consumatori delle fonti, feed attesi e ripristino
- [Stato di validazione](https://github.com/big-comfy/deadair/blob/main/docs/validation.md) — percorsi testati e limiti attuali
- [Architettura](https://github.com/big-comfy/deadair/blob/main/docs/architecture.md) — contratto del backend, modello dati, proprietà di sicurezza e limiti
- [Best practice](https://github.com/big-comfy/deadair/blob/main/docs/best-practices.md) — ordine di rollout, contesto degli alert e routing
- [Guida MSSP](https://github.com/big-comfy/deadair/blob/main/docs/mssp.md) — segreti, redazione, pianificazione e gestione dei guasti dei tenant
- [Detection che girano ma non vedono](https://alephnull-sh.github.io/deadair/) — il problema e una simulazione riproducibile
## Contribuire
Apri una issue per bug, suggerimenti o riproduzioni sanificate. I maintainer gestiscono le modifiche al codice.
Vedi [CONTRIBUTING.md](https://github.com/big-comfy/deadair/blob/main/CONTRIBUTING.md) per i dettagli.
## Licenza
Apache-2.0.