<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 は、有効化された SIEM 検知が必要なテレメトリをまだ持っているかどうかをチェックします。</strong><br>
欠落または古いデータ、取り込み遅延、スキーマの不一致を報告します。
</p>
<p align="center">
ローカルで実行 · 読み取り専用 · エージェント不要 · テレメトリのアップロードなし
</p>
<p align="center">
<a href="https://alephnull-sh.github.io/deadair/">技術解説を読む</a> ·
<a href="https://www.detectionengineering.net/i/208193682/detection-engineering-gem">Detection Engineering Weekly で紹介</a> ·
<a href="https://tldrsec.com/p/tldr-sec-341">tl;dr sec #341 で紹介</a>
</p>
<p align="center">
<a href="https://alephnull-sh.github.io/deadair/#elastic-demo"><img alt="欠落および古い入力、欠落フィールド、遅延イベントを示す Elastic スキャン" src="https://assets.kitploit.com/production/public/readmes/791/fc36f93c2d5fcaceffd370452b89b908a930eb10e810c0187fb3bba59cb156dd.png" width="860"></a>
</p>
<p align="center">
<sub>使い捨ての Elastic ラボにおける欠落フィールドと遅延イベント。画像を開くと再生コントロール付きの短い録画を確認できます。または <code>make record-scan-lab</code> で再現できます。</sub>
</p>
## deadair の理由
ルールは、必要なデータが消えた後でも、有効化され、スケジュールされ、エラーなく動作し続けることがあります。deadair は
稼働中のルールインベントリを読み取り、バックエンド固有のセマンティクスを使って各ルールの入力を解決し、
その背後にある具体的なソースをチェックします。
検出するもの:
- インデックス、エイリアス、データストリームセレクタが何も解決しないルール;
- 宣言された入力の1つが消えたのに別の入力がまだ解決する、混在セレクタのルール;
- 一致するソースがすべて古いか空であるルール;
- Elastic 上で、宣言されたフィールドが欠落したまま実行されているルール;
- Elastic および対象となる Sentinel Scheduled ルールで、取り込みラグによるブラインドウィンドウ;
- Sentinel 上で、既知のソースが互換性のない Basic または Auxiliary テーブルプランを使用しているルール;
- Elastic および OpenSearch 上で、有効な検知がどれも読み取っていない健全なテレメトリ。
deadair は Elastic Security、OpenSearch Security Analytics、Microsoft Sentinel をサポートします。
## クイックスタート
macOS、Linux、Windows 用のバイナリを
[GitHub Releases](https://github.com/alephnull-sh/deadair/releases) からダウンロードするか、Go でインストールします:
```sh
go install github.com/alephnull-sh/deadair/cmd/deadair@latest
```
お使いの SIEM 用の読み取り専用セットアップを表示します:
```sh
deadair setup elastic # Elastic Security
deadair setup opensearch # OpenSearch Security Analytics
deadair setup sentinel # Microsoft Sentinel
```
1つセットアップを実行し、検証してスキャンします:
```sh
deadair check # verify the credential can scan
deadair scan # assess live rules and telemetry
```
終了コードは安定しています: `0` は設定されたゲートを通過、`1` はゲート対象の検出事項あり、`2` はスキャン失敗を意味します。
ソースとそれを消費する検知を調査するには:
```sh
deadair scan --json-out report.json --html-out report.html
deadair inspect --source CommonSecurityLog report.json
```
レポートのソース名を使用してください。[調査ガイド](https://github.com/big-comfy/deadair/blob/main/docs/investigate.md)では、
個別の Sentinel フィード、メンテナンス、復旧の追跡についても説明しています。
## 仕組み
| ステージ | deadair が行うこと |
|---|---|
| インベントリ | 有効な検知と、それらが宣言する入力を読み取る |
| 解決 | Elastic と OpenSearch ではネイティブのインデックス解決を使用; Sentinel では、KQL 分析をテーブル、ウォッチリスト、保存関数、ASIM、マッピングされたクロスワークスペースの証拠と組み合わせる |
| 測定 | ソースの鮮度とタイミング、およびバックエンドが対応している場合はスキーマとストレージをチェックする |
| レポート | 各判定の根拠とともに、ターミナル、JSON、HTML、フリートロールアップ、Prometheus メトリクスを出力する |
Sentinel は同じルール対ソースのモデルに従い、リテラルウォッチリスト、保存関数、ASIM
パーサー、マッピングされたワークスペース、サマリーテーブルの系統を追加します。また、共有テーブルの
フィルタされたスライスが沈黙した場合や、サマリーパイプラインが遅延した場合も示します。
[使用ガイド](https://github.com/big-comfy/deadair/blob/main/docs/usage.md#microsoft-sentinel)では証拠ルールを説明し、
[検証記録](https://github.com/big-comfy/deadair/blob/main/docs/validation.md#sentinel-live-conformance)ではライブテストのカバレッジを記録しています。
<p align="center">
<a href="https://alephnull-sh.github.io/deadair/#sentinel-demo"><img alt="Sentinel CommonSecurityLog 内の沈黙したロンドンのファイアウォールフィードと、それに依存する検知" src="https://raw.githubusercontent.com/big-comfy/deadair/main/docs/assets/sentinel-lab.png" width="860"></a>
</p>
<p align="center">
<sub>2つのファイアウォールフィードが <code>CommonSecurityLog</code> を共有しています。一方が停止し、もう一方は報告を続けます。録画では保存された障害と復旧のスキャンを示しています。ラボの条件については<a href="https://github.com/big-comfy/deadair/blob/main/docs/validation.md#sentinel-live-conformance">検証記録</a>を参照してください。</sub>
</p>
deadair は検知のテレメトリが存在し健全かどうかをチェックします。ルール
ロジックを検証したり、シミュレートされた攻撃がアラートを発火することを証明したりはしません。それらの作業には静的ルール検証とエンドツーエンドの
検知テストを使用してください。
## 検出事項
| 検出事項 | 意味 | 最初の確認 |
|---|---|---|
| 一致するソースなし | ルールの入力のいずれも、可視のインデックス、データストリーム、または Sentinel テーブルに解決しない | パターン変更、欠落した統合、資格情報のスコープ |
| すべてのソースが古いか空 | 解決されたすべてのソースが現時点で使用不可 | ソースのケイデンスと取り込みパス |
| 欠落フィールド | すべてのソースマッピングを読み取った後、Elastic ルールで宣言されたフィールドが1つ以上の解決済みソースに存在しないか検索不可 | パーサー、パッケージ、マッピングの変更 |
| ラグブラインドウィンドウ | ペアイベントの p95 取り込みラグがルールのルックバックマージンを超えている | ルール間隔、ルックバック、タイムスタンプオーバーライド、パイプライン遅延 |
| 部分的な入力カバレッジ | 完全な式は解決するが、その中の1つのポジティブセレクタが空に解決する | 移行、フォールバックセレクタ、想定される代替; ポリシーがゲートしない限り情報提供 |
| ソースプラン非互換 | Sentinel ルールが、分析ルールの証拠パスに適格でない Basic または Auxiliary テーブルに依存している | テーブルプランとルールタイプ |
| ソース劣化 | ソースが古い、空、低ボリューム、またはスキーマドリフトしている | ソース履歴と想定されるメンテナンス |
| 未使用テレメトリ | Elastic または OpenSearch 上で、データが保存されているが、有効なローカル検知がどれもそれを解決しない | 無効化されたルールと意図的な収集 |
| 想定プロデューサの沈黙 | 設定された Sentinel のベンダー、製品、またはデバイスフィードがしきい値内に報告していない | そのフィードの送信元とコレクタ |
| サマリーパイプライン異常 | 関連する Sentinel サマリージョブが失敗したか、最後の成功が期限を過ぎている | ネイティブの実行記録とサマリークエリ |
プロデューサおよびサマリーパイプラインの検出事項は、そのクラスがポリシーで選択されている場合に終了ステータスに影響します。
沈黙したデバイスフィードは、共有テーブルの他のコンシューマとは別に報告されます。
すべての判定は、設定された資格情報が参照できる範囲に限定されます。JSON レポートには、
設定された式、解決されたソース、解決方法、評価ステータス、バックエンドメタデータ、
および機能の証拠が含まれます。実例とトリアージについては[使用ガイド](https://github.com/big-comfy/deadair/blob/main/docs/usage.md)を参照してください。
## 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
```
deadair がルールのマッピングされたリモートワークスペースを評価する前に、そのワークスペースには Sentinel が
デプロイされている必要があります。同一サブスクリプションのマッピングはソースの可用性を証明できます。クロスサブスクリプションのルールには、
正確なルール ID に紐づくランタイム証拠が必要です。証拠ルール、ワークスペースと
リージョンの制限、Microsoft のパフォーマンスガイダンスについては、
[Sentinel の使用詳細](https://github.com/big-comfy/deadair/blob/main/docs/usage.md#microsoft-sentinel)を参照してください。
[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)、または
[Microsoft Sentinel](https://github.com/big-comfy/deadair/blob/main/docs/credentials/sentinel.md) の文書化された読み取り専用ロールを使用してください。
## CI、フリート、モニタリング
```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` は、バックエンドネイティブの候補ルールまたは検知器を無関係なバックログから分離します。`diff`
は、同じ呼び出し元が保持するキーで作成されたマスク済みレポートで動作します。フリート設定は、
シークレット値を保存するのではなく、環境変数を介してシークレットを参照します。
[公式 GitHub Action](https://github.com/big-comfy/deadair/blob/main/docs/usage.md#gate-detection-changes)は、Elastic、OpenSearch、Sentinel 用の単一インスタンス候補
ゲートをラップします。ジョブサマリーを書き込み、マスク済み JSON
レポートをアップロードし、ルールをインストールせずに deadair ポリシーを適用できます。Sentinel ワークフローは
まずランナーを Azure に認証します; Action は Azure 資格情報の入力を定義しません。
[CI ゲートの動作](https://github.com/big-comfy/deadair/blob/main/docs/usage.md#gate-detection-changes)、
[フリートと MSSP のデプロイ](https://github.com/big-comfy/deadair/blob/main/docs/mssp.md)、および[Prometheus の例](https://github.com/big-comfy/deadair/blob/main/contrib)を参照して、ご自身の環境で
テストする設定を確認してください。
## テスト済みバックエンド
| バックエンド | ライブ検証 |
|---|---|
| Elastic Security | 8.19.19 および 9.4.4 での信頼済み CI |
| OpenSearch Security Analytics | 2.19.6 および 3.7.0 での信頼済み CI |
| Microsoft Sentinel | 使い捨ての UK South ワークスペースでの記録されたオプトイン適合性; [検証ステータス](https://github.com/big-comfy/deadair/blob/main/docs/validation.md#sentinel-live-conformance)を参照 |
Sentinel の適合性実行は手動であり、スケジュールされた CI ではありません。
## セキュリティモデル
- すべてのアダプタ呼び出しは読み取り専用です。信頼済みの Elastic および OpenSearch テストに加え、別途の Sentinel ラボ
プローブにより、文書化されたスキャン ID が代表的な書き込みを実行できないことを検証します。
- レポート、HTML、状態ファイル、フリート出力は、POSIX システムでは `0600` で書き込まれます。
- 資格情報は環境変数またはファイルから取得でき、プロセス引数にシークレットが含まれるのを避けます。
- `--redact` は、テナント、ルール、ソース、パターン、フィールド、依存関係、系統、来歴、
ワークスペース、ウォッチリスト、テンプレート、パッケージの識別子を、キー付き HMAC 仮名に置き換えます。検証済みの
依存関係プローブ式とその KQL 引数はシリアライズされません。ランダムバイトから生成された
`--redact-key-file` もマスキングを有効にし、別々の実行間で名前を安定させます。
- エクスポータはデフォルトでループバックにバインドします。
- deadair には電話 home 動作や使用状況テレメトリはありません。
レポートは機密性の高い SOC 成果物として扱ってください: それらはブラインド検知、ソース名、スキーマギャップ、
未使用の収集を特定します。
## ドキュメント
- [使用ガイド](https://github.com/big-comfy/deadair/blob/main/docs/usage.md) — 初回スキャン、レポート証拠、検出事項、CI ゲート、状態、フリート
- [テレメトリギャップの調査](https://github.com/big-comfy/deadair/blob/main/docs/investigate.md) — ソースコンシューマ、想定フィード、復旧
- [検証ステータス](https://github.com/big-comfy/deadair/blob/main/docs/validation.md) — テスト済みパスと現在の制限
- [アーキテクチャ](https://github.com/big-comfy/deadair/blob/main/docs/architecture.md) — バックエンド契約、データモデル、安全性プロパティ、制限
- [ベストプラクティス](https://github.com/big-comfy/deadair/blob/main/docs/best-practices.md) — ロールアウト順序、アラートコンテキスト、ルーティング
- [MSSP ガイド](https://github.com/big-comfy/deadair/blob/main/docs/mssp.md) — シークレット、マスキング、スケジューリング、テナント障害処理
- [実行されるが見えない検知](https://alephnull-sh.github.io/deadair/) — 問題と再現可能なシミュレーション
## コントリビューション
バグ、提案、またはサニタイズされた再現については issue を開いてください。コード変更はメンテナが対応します。
詳細は [CONTRIBUTING.md](https://github.com/big-comfy/deadair/blob/main/CONTRIBUTING.md) を参照してください。
## ライセンス
Apache-2.0.
