Big-Comfy/deadair

**deadair 能够发现你的 SIEM 中处于“致盲”状态的检测规则。** 你通常会在需要进行调查时才发现某个日志源失效了：索引已经沉寂了三周，而在此期间，每一个读取该索引的规则一直都在返回干净、无声的假阴性。规则执行监控从未标记出任何问题，因为它只检查规则是否运行过——而不是检查规则是否有数据可供运行。 deadair 检查的则是另一半。它以只读方式连接到 Elastic Security 或 OpenSearch Security Analytics，构建你的规则与其查询的索引之间的依赖图，并报告： - **Dead** — 无法触发的已启用规则：匹配不到任何索引的模式，或者所有匹配的源均已过期或为空。比如在周五晚上停止发送数据的 winlogbeat，能在周一早上就浮现出来，而不是等到事件响应（IR）中途才发现。 - **Impaired** — 视野受损但仍会触发的规则：例如在一个被 ILM 设定为 30 天删除的索引上执行 90 天的回溯，`required_fields` 在上次集成升级时被重命名，或者摄入延迟过大，导致事件在检测窗口已经关闭后才到达。 - **Unused** — 你正在花钱摄入、但没有已启用规则去读取的遥测数据。即消耗了摄入预算却没有带来任何覆盖。 每个源都附带其影响范围：如果该源失效，将有多少已启用的规则随之致盲。单二进制文件，无需代理，SIEM 端无需安装任何内容。 [示例](#example) · [快速上手](#get-started) · [用法](#usage) · [CI 集成](#in-ci) · [Fleet 模式](#fleet) · [Exporter](#exporter) · [文档](#docs) ## 示例 一个安装了预构建检测包（1,274 条规则）的 Elastic 8.17 原生集群，在 0.8 秒内完成扫描：

这 45 条全部是已启用的预构建规则，其索引模式与集群中的任何内容都不匹配——它们已被调度、正在执行，在规则监控中显示为绿色，但实际上处于致盲状态。其中一个是大多数环境默认开启的 Elastic Defend 促发规则。各种格式的示例报告均位于 [docs/examples](docs/examples/) 中。 ## 快速上手 从 [releases 页面](../../releases) 下载二进制文件 —— 支持 macOS、Linux 和 Windows，以及 amd64 和 arm64 架构 —— 或者通过 `make build` 自行构建。然后运行： ``` deadair setup # prints the least-privilege role, key command, and env exports deadair check # verifies the connection and each privilege individually deadair scan # first report ```

## 用法 ``` export DEADAIR_ES_URL=https://es.example.internal:9200 export DEADAIR_KIBANA_URL=https://kibana.example.internal:5601 export DEADAIR_API_KEY= deadair scan # terminal summary deadair scan --json # full report deadair scan --out r.json --html-out r.html # files, created 0600 ``` OpenSearch：`DEADAIR_BACKEND=opensearch`，`DEADAIR_OPENSEARCH_URL`，基本认证（[设置](docs/credentials/opensearch.md)）。 退出代码：`0` 健康，`1` 有发现，`2` 扫描失败。 | 标志 | 用途 | |---|---| | `--max-stale 30m` | 源在静默多长时间后被视为过期 | | `--include` / `--exclude` | 限制报告列表范围；不影响最终判定结果 | | `--state-file s.json` | 容量基线：工作日/小时历史数据、预热、滞后效应 | | `--downtime-file d.json` | 声明的维护窗口；在此期间内抑制发现 | | `--schema` | 扫描之间的 field_caps 偏差（需要配合 `--state-file`） | | `--redact` | 输出稳定的摘要以替代源/规则名称 | HTML 报告：

## CI 集成 退出代码可用于控制流水线门禁：如果某个拉取请求提交了一条读取死索引的规则，将导致构建失败。 ``` deadair scan --rule new-rule.json # evaluate a candidate rule; exit 1 if it can't see data here deadair diff last-week.json today.json # exit 1 if something newly died or degraded ``` `--rule` 接收来自你 infrastructure-as-code 仓库的规则 JSON 或 ndjson 导出文件，并在不安装的情况下针对实时环境对其进行评估；已有的发现不会影响其退出代码。`diff` 比较两份已保存的报告，且仅在发生回归时报错——这是在尚未清理完历史积压时最合适的门禁机制。这两者均适用于已脱敏的报告，因为摘要是稳定的。

## Fleet 模式 对于拥有多个 SIEM 的环境 —— 例如 MSSP 的客户群、生产/测试环境对、并购后的系统蔓延 —— `--fleet` 可以在一次运行中扫描每个实例，并汇总重复的内容。“在 12 个租户中有 3 个致盲”在报告中仅显示为一行，而不是去查阅十二个控制台。 ``` deadair scan --fleet fleet.json # scan every instance listed in fleet.json deadair serve --fleet fleet.json # per-instance metrics from one exporter ``` ``` {"instances": [ {"name": "acme-prod", "backend": "elastic", "es_url": "https://...", "kibana_url": "https://...", "api_key_env": "ACME_KEY"}, {"name": "beta-corp", "backend": "opensearch", "opensearch_url": "https://...", "username": "deadair", "password_env": "BETA_PW"} ]} ``` 机密信息通过环境变量或文件引用，绝不写入配置中。实例按顺序扫描，一次扫描一个租户的 SIEM；无法连接的租户会被报告并返回退出代码 `2`，且不会影响其他租户的可见性。配合 `--state-file`，基线会按实例独立保存。 每个指标都带有 `instance` 标签，并且 `--redact` 会对租户名称及其他所有内容进行摘要化处理，从而确保面向 MSSP 客户的报告中不包含租户身份信息。 在两个后端上对三个租户进行的实时扫描：

## Exporter `deadair serve` 会按设定间隔进行扫描并暴露 Prometheus 指标。适用于 Grafana/Alertmanager 的仪表盘和告警规则位于 [contrib](contrib/) 目录中。抓取操作读取的是缓存快照；抓取负载永远不会触及 SIEM 本身。 ``` deadair serve --interval 5m # binds 127.0.0.1:9317 ``` ## 后端 目前支持两种后端，且仅支持这两种： | 后端 | 版本 | 状态 | |---|---|---| | Elastic Security | 8.x | 每次推送均在实时集群上进行 CI 测试 | | OpenSearch Security Analytics | 2.x | 每次推送均在实时集群上进行 CI 测试 | Splunk 永远不在考虑范围内。其他 SIEM —— Microsoft Sentinel、Google SecOps 等 —— 均为按需求排序的候选目标：如果你正在使用某一个并希望在其上运行 deadair，请[提交一个 issue](../../issues)。后端实现必须提供的内容已在 [architecture.md](docs/architecture.md) 中详细记录。 ## 报告处理 deadair 报告会映射出检测盲区。默认假设其存在泄露风险： - 架构上原生限制为只读。[docs/credentials](docs/credentials/) 中定义的最小权限角色已在 CI 中针对实时集群进行了验证，包括对写入操作的拒绝测试。 - 报告和状态文件以 `0600` 权限写入。 - Exporter 默认绑定到回环地址；由于指标标签包含源名称，因此在非回环环境下使用时，请配合 `--redact` 或设置带有认证的抓取路径。 - 机密信息通过环境变量或文件传入，绝不使用 argv。无任何数据回传，无任何使用情况遥测。 ## 文档 - [使用指南](docs/usage.md) — 涵盖所有工作流，以及针对每类发现结果的处理建议。 - [最佳实践](docs/best-practices.md) — 发布顺序、避免误报、Fleet 模式。 - [架构说明](docs/architecture.md) — 数据模型、API 成本、安全属性。 ## 开源协议 Apache-2.0。即使未来出现商业层，本仓库中的所有内容也将始终保持为 Apache-2.0。

标签：EVTX分析, Go, Ruby工具, 告警可靠性, 安全运营, 扫描框架, 日志审计, 自定义请求头, 运维监控