big-comfy/deadairFindet die Erkennungsregeln in Ihrem SIEM, die ins Leere laufen.
<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 prüft, ob aktivierte SIEM-Detections noch über die benötigte Telemetrie verfügen.</strong><br>
Es meldet fehlende oder veraltete Daten, Ingest-Verzögerungen und Schema-Abweichungen.
</p>
<p align="center">
Läuft lokal · Nur lesend · Kein Agent · Kein Telemetrie-Upload
</p>
<p align="center">
<a href="https://alephnull-sh.github.io/deadair/">Technischen Bericht lesen</a> ·
<a href="https://www.detectionengineering.net/i/208193682/detection-engineering-gem">Vorgestellt in Detection Engineering Weekly</a> ·
<a href="https://tldrsec.com/p/tldr-sec-341">Vorgestellt in tl;dr sec #341</a>
</p>
<p align="center">
<a href="https://alephnull-sh.github.io/deadair/#elastic-demo"><img alt="Ein Elastic-Scan, der fehlende und veraltete Inputs, fehlende Felder und verzögerte Events zeigt" src="https://assets.kitploit.com/production/public/readmes/791/fc36f93c2d5fcaceffd370452b89b908a930eb10e810c0187fb3bba59cb156dd.png" width="860"></a>
</p>
<p align="center">
<sub>Fehlende Felder und verzögerte Events in einem wegwerfbaren Elastic-Lab. Öffne das Bild für die kurze Aufzeichnung mit Wiedergabesteuerung oder reproduziere sie mit <code>make record-scan-lab</code>.</sub>
</p>
## Warum deadair
Eine Regel kann aktiviert, geplant und fehlerfrei sein, nachdem die benötigten Daten verschwunden sind. deadair
liest das Live-Regelinventar, löst die Inputs jeder Regel mithilfe der nativen Semantik des Backends auf und
prüft die konkreten Quellen dahinter.
Es erkennt:
- Regeln, deren Index-, Alias- oder Data-Stream-Selektoren zu nichts auflösen;
- Regeln mit gemischten Selektoren, bei denen ein deklarierter Input verschwunden ist, während ein anderer noch auflöst;
- Regeln, deren passende Quellen alle veraltet oder leer sind;
- bei Elastic Regeln, die mit fehlenden deklarierten Feldern laufen;
- bei Elastic und geeigneten Sentinel Scheduled-Regeln ein Blindfenster durch Ingest-Verzögerung;
- bei Sentinel Regeln, deren bekannte Quellen einen inkompatiblen Basic- oder Auxiliary-Tabellenplan verwenden;
- bei Elastic und OpenSearch gesunde Telemetrie, die von keiner aktivierten Detection gelesen wird.
deadair unterstützt Elastic Security, OpenSearch Security Analytics und Microsoft Sentinel.
## Schnellstart
Lade ein Binary für macOS, Linux oder Windows von
[GitHub Releases](https://github.com/alephnull-sh/deadair/releases) herunter oder installiere es mit Go:
```sh
go install github.com/alephnull-sh/deadair/cmd/deadair@latest
```
Gib das schreibgeschützte Setup für dein SIEM aus:
```sh
deadair setup elastic # Elastic Security
deadair setup opensearch # OpenSearch Security Analytics
deadair setup sentinel # Microsoft Sentinel
```
Führe ein Setup aus und verifiziere dann und scanne:
```sh
deadair check # überprüfen, ob die Anmeldedaten scannen können
deadair scan # Live-Regeln und Telemetrie bewerten
```
Exit-Codes sind stabil: `0` besteht das konfigurierte Gate, `1` bedeutet gegatete Findings und `2` bedeutet, dass der Scan fehlgeschlagen ist.
Um eine Quelle und ihre konsumierenden Detections zu untersuchen:
```sh
deadair scan --json-out report.json --html-out report.html
deadair inspect --source CommonSecurityLog report.json
```
Verwende einen Quellennamen aus deinem Bericht. Der [Untersuchungsleitfaden](https://github.com/big-comfy/deadair/blob/main/docs/investigate.md) behandelt auch
einzelne Sentinel-Feeds, Wartung und Wiederherstellungsverfolgung.
## Wie es funktioniert
| Phase | Was deadair tut |
|---|---|
| Inventar | liest aktivierte Detections und die von ihnen deklarierten Inputs |
| Auflösen | verwendet native Index-Auflösung bei Elastic und OpenSearch; bei Sentinel kombiniert es KQL-Analyse mit Tabellen-, Watchlist-, Saved-Function-, ASIM- und gemappten Cross-Workspace-Nachweisen |
| Messen | prüft Quellenaktualität und -timing sowie Schema und Speicherung, wo das Backend dies unterstützt |
| Berichten | gibt Terminal-, JSON-, HTML-, Fleet-Rollups und Prometheus-Metriken mit den Nachweisen hinter jedem Urteil aus |
Sentinel folgt demselben Regel-zu-Quelle-Modell und ergänzt literale Watchlists, Saved Functions, ASIM-
Parser, gemappte Workspaces und Summary-Table-Lineage. Es zeigt auch, wenn ein gefilterter Ausschnitt einer
gemeinsam genutzten Tabelle verstummt ist oder eine Summary-Pipeline zurückgefallen ist.
Der [Nutzungsleitfaden](https://github.com/big-comfy/deadair/blob/main/docs/usage.md#microsoft-sentinel) beschreibt die Nachweisregeln und der
[Validierungsdatensatz](https://github.com/big-comfy/deadair/blob/main/docs/validation.md#sentinel-live-conformance) dokumentiert die Live-Testabdeckung.
<p align="center">
<a href="https://alephnull-sh.github.io/deadair/#sentinel-demo"><img alt="Ein stiller London-Firewall-Feed und seine abhängige Detection innerhalb von Sentinel CommonSecurityLog" src="https://raw.githubusercontent.com/big-comfy/deadair/main/docs/assets/sentinel-lab.png" width="860"></a>
</p>
<p align="center">
<sub>Zwei Firewall-Feeds teilen sich <code>CommonSecurityLog</code>. Einer stoppt; der andere berichtet weiter. Die Aufzeichnung zeigt die gespeicherten Fehler- und Wiederherstellungs-Scans. Siehe den <a href="https://github.com/big-comfy/deadair/blob/main/docs/validation.md#sentinel-live-conformance">Validierungsdatensatz</a> für die Lab-Bedingungen.</sub>
</p>
deadair prüft, ob die Telemetrie einer Detection vorhanden und gesund ist. Es validiert nicht die Regellogik
und beweist nicht, dass ein simulierter Angriff einen Alarm auslöst. Verwende statische Regelvalidierung und
End-to-End-Detection-Tests für diese Aufgaben.
## Findings
| Finding | Bedeutung | Erste Prüfung |
|---|---|---|
| keine passende Quelle | keiner der Inputs der Regel löst zu einem sichtbaren Index, Data Stream oder einer Sentinel-Tabelle auf | Musteränderungen, fehlende Integrationen und Credential-Scope |
| alle Quellen veraltet oder leer | jede aufgelöste Quelle ist derzeit unbrauchbar | Quellenkadenz und der Ingest-Pfad |
| fehlende Felder | ein von der Elastic-Regel deklariertes Feld fehlt oder ist in einer oder mehreren aufgelösten Quellen nicht durchsuchbar, nachdem jedes Quellen-Mapping gelesen wurde | Parser-, Paket- und Mapping-Änderungen |
| Blindfenster durch Verzögerung | p95-Ingest-Verzögerung bei gepaarten Events überschreitet die Lookback-Marge der Regel | Regelintervall, Lookback, Timestamp-Override und Pipeline-Verzögerung |
| teilweise Input-Abdeckung | der vollständige Ausdruck löst auf, aber ein positiver Selektor darin löst leer auf | Migrationen, Fallback-Selektoren und erwartete Alternativen; informativ, sofern nicht durch Policy gegatet |
| Quellenplan inkompatibel | eine Sentinel-Regel hängt von einer Basic- oder Auxiliary-Tabelle ab, die nicht für den Analytics-Rule-Nachweispfad geeignet ist | Tabellenplan und Regeltyp |
| Quellen-Degradation | eine Quelle ist veraltet, leer, hat geringes Volumen oder Schema-Drift | Quellenhistorie und erwartete Wartung |
| ungenutzte Telemetrie | bei Elastic oder OpenSearch werden Daten gespeichert, aber keine aktivierte lokale Detection löst darauf auf | deaktivierte Regeln und beabsichtigte Erfassung |
| erwarteter Producer still | ein konfigurierter Sentinel-Vendor-, Produkt- oder Device-Feed hat nicht innerhalb seines Schwellenwerts berichtet | Sender und Collector dieses Feeds |
| Summary-Pipeline ungesund | ein relevanter Sentinel-Summary-Job ist fehlgeschlagen oder sein letzter Erfolg ist überfällig | der native Ausführungsdatensatz und die Summary-Abfrage |
Producer- und Summary-Pipeline-Findings beeinflussen den Exit-Status, wenn ihre Klassen in der
Policy ausgewählt sind. Ein stiller Device-Feed wird getrennt von anderen Konsumenten seiner gemeinsam genutzten Tabelle gemeldet.
Jedes Urteil ist auf das beschränkt, was die konfigurierten Anmeldedaten sehen können. JSON-Berichte enthalten die
konfigurierten Ausdrücke, aufgelösten Quellen, Auflösungsmethode, Bewertungsstatus, Backend-Metadaten
und Capability-Nachweise. Siehe den [Nutzungsleitfaden](https://github.com/big-comfy/deadair/blob/main/docs/usage.md) für ausgearbeitete Beispiele und Triage.
## Ein SIEM verbinden
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
```
Bevor deadair den gemappten Remote-Workspace einer Regel bewertet, muss in diesem Workspace Sentinel
bereitgestellt sein. Mappings innerhalb desselben Abonnements können die Quellenverfügbarkeit belegen. Regeln über
Abonnements hinweg benötigen Laufzeitnachweise, die an die exakte Regelidentität gebunden sind. Siehe die
[Sentinel-Nutzungsdetails](https://github.com/big-comfy/deadair/blob/main/docs/usage.md#microsoft-sentinel) für die Nachweisregeln, Workspace- und
Regionsgrenzen sowie Microsofts Performance-Empfehlungen.
Verwende die dokumentierten schreibgeschützten Rollen für
[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) oder
[Microsoft Sentinel](https://github.com/big-comfy/deadair/blob/main/docs/credentials/sentinel.md).
## CI, Flotten und Monitoring
```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` isoliert eine backend-native Kandidatenregel oder einen Detector von unabhängigem Backlog. `diff`
funktioniert mit redigierten Berichten, die mit demselben vom Aufrufer gehaltenen Schlüssel erstellt wurden. Die Fleet-Konfiguration referenziert
Secrets über Umgebungsvariablen, anstatt geheime Werte zu speichern.
Die [offizielle GitHub Action](https://github.com/big-comfy/deadair/blob/main/docs/usage.md#gate-detection-changes) umschließt Kandidaten-Gates für einzelne Instanzen
für Elastic, OpenSearch und Sentinel. Sie schreibt eine Job-Zusammenfassung, lädt einen redigierten JSON-
Bericht hoch und kann eine deadair-Policy anwenden, ohne eine Regel zu installieren. Sentinel-Workflows authentifizieren
den Runner zuerst bei Azure; die Action definiert keine Azure-Credential-Inputs.
Siehe [CI-Gate-Verhalten](https://github.com/big-comfy/deadair/blob/main/docs/usage.md#gate-detection-changes),
[Fleet- und MSSP-Deployment](https://github.com/big-comfy/deadair/blob/main/docs/mssp.md) und die [Prometheus-Beispiele](https://github.com/big-comfy/deadair/blob/main/contrib) für Konfigurationen,
die du in deiner eigenen Umgebung testen kannst.
## Getestete Backends
| Backend | Live-Validierung |
|---|---|
| Elastic Security | vertrauenswürdige CI auf 8.19.19 und 9.4.4 |
| OpenSearch Security Analytics | vertrauenswürdige CI auf 2.19.6 und 3.7.0 |
| Microsoft Sentinel | aufgezeichnete Opt-in-Konformität in wegwerfbaren UK-South-Workspaces; siehe [Validierungsstatus](https://github.com/big-comfy/deadair/blob/main/docs/validation.md#sentinel-live-conformance) |
Der Sentinel-Konformitätslauf ist manuell, keine geplante CI.
## Sicherheitsmodell
- Alle Adapter-Aufrufe sind schreibgeschützt. Vertrauenswürdige Elastic- und OpenSearch-Tests sowie separate Sentinel-Lab-
Sonden verifizieren, dass die dokumentierten Scan-Identitäten keine repräsentativen Schreibvorgänge durchführen können.
- Berichte, HTML, State-Dateien und Fleet-Ausgaben werden auf POSIX-Systemen mit `0600` geschrieben.
- Anmeldedaten können aus Umgebungsvariablen oder Dateien stammen, wodurch Secrets in Prozessargumenten vermieden werden.
- `--redact` ersetzt Tenant-, Regel-, Quellen-, Muster-, Feld-, Abhängigkeits-, Lineage-, Provenienz-,
Workspace-, Watchlist-, Template- und Paket-Identifikatoren durch geschlüsselte HMAC-Pseudonyme. Validierte
Dependency-Probe-Ausdrücke und ihre KQL-Argumente werden niemals serialisiert. Eine
aus zufälligen Bytes generierte `--redact-key-file` aktiviert ebenfalls die Redaktion und hält Namen über
separate Läufe hinweg stabil.
- Der Exporter bindet standardmäßig an Loopback.
- deadair hat kein Phone-Home-Verhalten und keine Nutzungstelemetrie.
Behandle Berichte als sensible SOC-Artefakte: Sie identifizieren blinde Detections, Quellennamen, Schema-Lücken
und ungenutzte Erfassung.
## Dokumentation
- [Nutzungsleitfaden](https://github.com/big-comfy/deadair/blob/main/docs/usage.md) — erste Scans, Berichtsnachweise, Findings, CI-Gates, State und Flotten
- [Eine Telemetrie-Lücke untersuchen](https://github.com/big-comfy/deadair/blob/main/docs/investigate.md) — Quellenkonsumenten, erwartete Feeds und Wiederherstellung
- [Validierungsstatus](https://github.com/big-comfy/deadair/blob/main/docs/validation.md) — getestete Pfade und aktuelle Grenzen
- [Architektur](https://github.com/big-comfy/deadair/blob/main/docs/architecture.md) — Backend-Vertrag, Datenmodell, Sicherheitseigenschaften und Grenzen
- [Best Practices](https://github.com/big-comfy/deadair/blob/main/docs/best-practices.md) — Rollout-Reihenfolge, Alert-Kontext und Routing
- [MSSP-Leitfaden](https://github.com/big-comfy/deadair/blob/main/docs/mssp.md) — Secrets, Redaktion, Scheduling und Tenant-Fehlerbehandlung
- [Detections, die laufen, aber nichts sehen](https://alephnull-sh.github.io/deadair/) — das Problem und eine reproduzierbare Simulation
## Mitwirken
Eröffne ein Issue für Bugs, Vorschläge oder bereinigte Reproduktionen. Maintainer übernehmen Code-Änderungen.
Siehe [CONTRIBUTING.md](https://github.com/big-comfy/deadair/blob/main/CONTRIBUTING.md) für Details.
## Lizenz
Apache-2.0.