muhdajimmeh-byte/detection-as-code

# 检测即代码：经过单元测试的 Sigma 规则库 [](https://github.com/muhdajimmeh-byte/detection-as-code/actions/workflows/detections.yml) 一个 Windows 检测库，其中**每条规则都会在 CI 中针对真实事件** 数据执行，被编译为 Splunk SPL 和 Microsoft Sentinel KQL，并映射至 MITRE ATT&CK。 大多数检测仓库只能对它们的规则进行 *lint*：它们检查 YAML 是否能被解析以及必需的键是否存在。这只能抓出拼写错误，却抓不到 逻辑错误。一条规则可能拥有完美的 YAML，通过了代码审查，在生产环境中闲置了 一年，却什么也匹配不到——而且直到漏报了某个安全事件， 没有人会发现这一点。 在这里，每条规则都配备了一个它必须触发的 **真阳性 (true-positive) 固件** 和一个它必须保持静默的 **真阴性 (true-negative) 固件**。这两者都会在每次推送时运行。如果一条规则 停止了检测，或者开始过度检测，构建就会失败。 ## 为什么这很重要（该机制捕获的一个真实 Bug） 在构建评估器时，`contains` 修饰符会在解析转义符之前，将其通配符追加到 原始字符串末尾。因此，以反斜杠结尾的值—— `'\CurrentVersion\Run\'`，这也是这里大多数注册表规则的形式——会变成 `\CurrentVersion\Run\*`，而解析器会将末尾的 `\*` 读取为 *转义的字面量星号*。该规则在静默中要求注册表路径中包含字面量 `*`。 它能被解析。它通过了 lint。人类读起来也完全正确。但它永远无法触发。 测试固件在几秒钟内就抓住了这个问题，现在它已被一个 [回归测试](tests/test_sigma_eval.py) 所固化。这仅仅通过一个 Bug 就完整地论证了 检测即代码的理念：**你无法仅凭代码审查来确信一条规则是否 匹配。你必须运行它。** ## 每次推送时运行的内容 | 阶段 | 验证了什么 | | --- | --- | | Schema 验证 | 稳定的 UUID，ATT&CK 战术 *和* 技术，严重程度，已记录的误报，以及分析师能够真正据此进行分流的描述 | | 条件分析 | 条件能够被解析，并且仅引用了实际存在的搜索标识符；没有孤立的 selection 块 | | **行为测试** | 每条规则在其真阳性固件上触发，并在其真阴性固件上保持静默 | | 关联测试 | 基础规则的 UUID 引用能够被解析；窗口化逻辑在突发操作时触发，而不会在分散在一个上午的相同命令上触发；`group-by` 能够真正隔离账户 | | 引擎单元测试 | 评估器自身的转义、修饰符和条件解析行为 | | 查询编译 | 每条规则都能编译为 Splunk SPL 和 Sentinel KQL，或者以记录在案的理由明确选择跳过 | | 覆盖矩阵 | 生成 [`docs/attack-coverage.md`](docs/attack-coverage.md)，如果提交的副本发生偏移，CI 将会失败 | ## 快速开始 ``` git clone https://github.com/muhdajimmeh-byte/detection-as-code cd detection-as-code python -m venv .venv && . .venv/bin/activate # Windows: .venv\Scripts\activate pip install -r requirements.txt pytest tests -q # run every rule against its fixtures python tools/convert.py --check # verify all rules compile to SPL + KQL python tools/convert.py --target kql --out build/ python tools/coverage.py # regenerate the ATT&CK matrix ``` 无需 SIEM。这里的固件是真实的 Sysmon 事件结构，因此该库可以在 笔记本电脑上进行测试，并且无需更改任何规则即可部署到 SIEM 中。 ## 覆盖范围 参见 [`docs/attack-coverage.md`](docs/attack-coverage.md) —— 它直接根据 规则本身生成，其中包含一份明确的列表，指出了**尚未**覆盖的战术。 一个只列出战果的覆盖矩阵不过是一份营销文件。 ## 仓库结构 ``` rules/ Sigma rules, one directory per ATT&CK tactic correlation/ Sigma v2 correlation rules (burst / threshold logic) tests/ fixtures/// positive_*.json events the rule MUST match negative_*.json events the rule MUST NOT match test_rules.py schema + behaviour tests, parametrised per rule test_correlation.py windowed correlation tests over event sequences test_sigma_eval.py unit tests for the evaluator itself tools/ sigma_eval.py Sigma evaluator (modifiers, conditions, correlations) convert.py Sigma -> Splunk SPL and Sentinel KQL coverage.py generates docs/attack-coverage.md docs/ attack-coverage.md generated; CI fails if stale tier1-triage-playbook.md how to work an alert from this library investigations/ full case write-ups ``` ## 值得捍卫的设计决策 **调优过滤器是规则的一部分，而不是事后补充。** 每条规则都带有一个 `falsepositives` 块，指明了实际上会导致噪音的原因以及如何过滤它。 `test_rule_documents_false_positives` 会拒绝 "None" 和 "Unknown" —— 一条没有 记录误报的规则没有被调优过，它只是被写出来而已。 **访问掩码规则拒绝被翻译。** LSASS 规则是基于进程访问掩码进行匹配，而 不是匹配 `mimikatz.exe`，因此即使工具被重命名它也能生效。由于 Defender XDR 不公开该掩码，因此该规则明确地 [选择跳过](rules/credential-access/lsass_memory_access.yml) KQL 转换， 而不是输出一个看似提供覆盖却什么也抓不到的查询。如果选择跳过的规则 后来又开始能够编译，CI 也会失败，从而确保这份列表保持诚实。 **嘈杂的基础规则保持为信息级别。** 单独的 `whoami` 并不是一个警报 —— 它只是 遥测数据。[发现突发关联](rules/correlation/discovery_command_burst.yml) 仅在一个账户于五分钟内在一台主机上运行了五个或更多不同的发现命令时才会触发。一项测试强制要求为关联提供数据的基础规则 级别为 `informational` 或 `low`，因此突发操作永远不会产生重复的工单。 **`OriginalFileName` 伴随 `Image`。** 将 `powershell.exe` 重命名为 `update.exe` 可以绕过基于镜像名称的规则。但二进制文件内部的链接器元数据 不会改变，因此规则会同时匹配这两者 —— 并且有一个固件证明了这一点。 ## 技术栈 Sigma · MITRE ATT&CK · Sysmon · Splunk SPL · Microsoft Sentinel KQL · Python · pytest · GitHub Actions ## 作者 **Muhammad Azim** — [LinkedIn](https://linkedin.com/in/azim-muhammad-bb9791411/) · [GitHub](https://github.com/muhdajimmeh-byte) ## 免责声明 `tests/fixtures/` 中的所有遥测数据都是合成的，由人工编写以匹配真实的 Sysmon 事件结构。没有生产数据，没有真实的主机名，没有真实的凭证。 记录在案的 IP 使用了 RFC 5737 为文档保留的 `192.0.2.0/24` 范围。 ## 许可证 MIT

标签：Sentinel KQL, Sigma规则, Splunk SPL, URL发现, 安全检测, 安全规则引擎, 检测即代码, 目标导入, 逆向工具