deadair v0.8.0

deadair 检查已启用的 SIEM 检测是否仍具备所需的遥测数据。
它会报告缺失或过期的数据、摄取延迟以及模式不匹配。

本地运行 · 只读 · 无代理 · 不上传遥测数据

阅读技术文章 · 入选 Detection Engineering Weekly · 入选 tl;dr sec #341

_{一次性 Elastic 实验环境中的缺失字段和延迟事件。打开图片可查看带播放控件的简短录屏，或使用 make record-scan-lab 复现。}

为什么选择 deadair

一条规则可能在所需数据消失后仍处于启用、已调度且无错误的状态。deadair 读取实时规则清单，使用后端原生语义解析每条规则的输入，并 检查其背后的具体数据源。

它能发现：

• 索引、别名或数据流选择器解析不到任何内容的规则；
• 混合选择器规则，其中一个声明的输入已消失，而另一个仍能解析；
• 匹配的数据源全部过期或为空的规则；
• 在 Elastic 上，运行时缺失已声明字段的规则；
• 在 Elastic 和符合条件的 Sentinel Scheduled 规则上，存在摄取滞后的盲区窗口；
• 在 Sentinel 上，已知数据源使用不兼容的 Basic 或 Auxiliary 表计划的规则；
• 在 Elastic 和 OpenSearch 上，健康的遥测数据没有被任何已启用的检测读取。

deadair 支持 Elastic Security、OpenSearch Security Analytics 和 Microsoft Sentinel。

快速开始

从 GitHub Releases 下载适用于 macOS、Linux 或 Windows 的二进制文件，或使用 Go 安装：

go install github.com/alephnull-sh/deadair/cmd/deadair@latest

打印针对你的 SIEM 的只读设置：

deadair setup elastic      # Elastic Security
deadair setup opensearch   # OpenSearch Security Analytics
deadair setup sentinel     # Microsoft Sentinel

运行一次设置，然后验证并扫描：

deadair check   # 验证凭据可以扫描
deadair scan    # 评估实时规则和遥测数据

退出码是稳定的：0 表示通过配置的门禁，1 表示有门禁发现，2 表示扫描失败。

要调查某个数据源及其消费检测：

deadair scan --json-out report.json --html-out report.html
deadair inspect --source CommonSecurityLog report.json

使用报告中的数据源名称。调查指南还涵盖了 单个 Sentinel 数据源、维护和恢复跟踪。

工作原理

Sentinel 遵循相同的规则到数据源模型，并增加了字面监视列表、已保存函数、ASIM 解析器、映射工作区和摘要表血缘。它还会显示共享表的某个过滤切片何时变得安静，或摘要管道何时落后。

使用指南描述了证据规则， 验证记录记录了实时测试覆盖情况。

_{两个防火墙数据源共享 CommonSecurityLog。一个停止；另一个继续报告。录屏展示了保存的失败和恢复扫描。实验条件见验证记录。}

deadair 检查检测的遥测数据是否存在且健康。它不验证规则 逻辑，也不证明模拟攻击会触发告警。这些工作请使用静态规则验证和端到端 检测测试。

发现

当策略中选择了相应类别时，生产者和摘要管道发现会影响退出状态。安静的设备数据源会与其共享表的其他消费者分开报告。

每个判定都限于配置的凭据所能看到的内容。JSON 报告包含 配置的表达式、已解析的数据源、解析方法、评估状态、后端元数据 和能力证据。工作示例和分类见使用指南。

连接 SIEM

Elastic：

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：

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：

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。 同一订阅的映射可以证明数据源可用性。跨订阅规则需要 与确切规则身份绑定的运行时证据。证据规则、工作区和 区域限制以及 Microsoft 的性能指南见 Sentinel 使用详情。

使用文档中记录的只读角色： Elastic、OpenSearch 或 Microsoft Sentinel。

CI、队列和监控

# 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 封装了针对 Elastic、OpenSearch 和 Sentinel 的单实例候选 门禁。它会写入作业摘要、上传脱敏 JSON 报告，并可在不安装规则的情况下应用 deadair 策略。Sentinel 工作流首先 对运行器进行 Azure 身份验证；该 Action 不定义 Azure 凭据输入。

有关可在你自己的环境中测试的配置，请参阅 CI 门禁行为、 队列和 MSSP 部署 以及 Prometheus 示例。

已测试的后端

Sentinel 一致性运行是手动的，不是计划 CI。

安全模型

• 所有适配器调用均为只读。可信的 Elastic 和 OpenSearch 测试以及单独的 Sentinel 实验 探针验证文档中记录的扫描身份无法执行代表性写入。
• 报告、HTML、状态文件和队列输出在 POSIX 系统上以 0600 写入。
• 凭据可以来自环境变量或文件，避免密钥出现在进程参数中。
• --redact 将租户、规则、数据源、模式、字段、依赖、血缘、来源、 工作区、监视列表、模板和包标识符替换为带密钥的 HMAC 假名。已验证的 依赖探针表达式及其 KQL 参数永远不会被序列化。由随机字节生成的 --redact-key-file 也会启用脱敏，并在不同运行之间保持名称稳定。
• 导出器默认绑定到回环地址。
• deadair 没有回传行为或使用遥测。

将报告视为敏感的 SOC 工件：它们会识别盲检测、数据源名称、模式缺口 和未使用的收集。

文档

• 使用指南 — 首次扫描、报告证据、发现、CI 门禁、状态和队列
• 调查遥测缺口 — 数据源消费者、预期数据源和恢复
• 验证状态 — 已测试路径和当前限制
• 架构 — 后端契约、数据模型、安全属性和限制
• 最佳实践 — 推出顺序、告警上下文和路由
• MSSP 指南 — 密钥、脱敏、调度和租户故障处理
• 运行但看不见的检测 — 问题及可复现的模拟

贡献

对于错误、建议或经过清理的复现，请提交 issue。维护者处理代码更改。 详情见 CONTRIBUTING.md。

许可证

Apache-2.0。