AshwinNHacker/detection-drift-tracker

# 检测 Drift Tracker **检测软件/内容更新间的检测规则行为差异——包括字段级*和*行为级。** 检测规则（Sigma、SIEM 关联规则、EDR 内容）始终在悄然发生偏移（drift）：供应商重命名了二进制文件，“清理”提交缩小了 `contains` 匹配范围，条件被重构且布尔逻辑发生细微变化。对 YAML 文件进行普通的 `git diff` 只能告诉你*某些东西*变了。它不会告诉你**该规则现在捕获到了什么以前没捕获到的东西——或者更糟的是，它以前能捕获而现在却捕获不到什么。** Detection Drift Tracker 通过以下方式回答了这个问题： 1. **解析**每个规则版本（Sigma 样式的 YAML）为结构化模型。 2. **语义化对比字段**——新增/移除/修改的选择（selections）、条件更改、日志源（logsource）更改——忽略装饰性的 YAML 干扰信息（键顺序、空格）。 3. **将两个规则版本在样本事件语料库上进行模拟**，并对比*匹配结果*：哪些事件是新匹配上的，哪些不再匹配（覆盖范围丢失），哪些保持稳定。 4. **对偏移进行 0-100 评分**，并划分严重性等级（`none`/`low`/`medium`/`high`/`critical`），其权重设置使得悄然的覆盖范围丢失主导得分——因为停止触发的规则远比变得更嘈杂的规则危险得多。 5. **生成报告**，输出为独立的 HTML 文件（无 CDN 调用，离线安全）以及用于 CI 门控 / SOAR 摄取的 JSON。 它可以直接对比两个文件，或者遍历规则的整个 **git 历史记录**，并报告每次提交转换时的偏移——因此你可以将其指向你的 Sigma 分支或内部 detection-as-code 仓库，并获得完整的偏移时间线。 ``` $ drift-tracker diff --old rule_v1.yml --new rule_v2.yml --events events.json === Suspicious PowerShell Encoded Command Execution :: old -> new === Severity: CRITICAL Score: 75.7/100 Behavioral: 1 lost, 2 gained, 1 stable (of 7 sample events) - Detection condition logic changed. - 3 selection field value(s) added/removed/modified. - 1 metadata field(s) changed (level/status/tags/id). - COVERAGE LOSS: 1/7 sample event(s) that used to match no longer do. - 2/7 sample event(s) now match that didn't before (possible expanded coverage or new false positives). ``` ## 为什么这很重要 如今，大多数检测偏移的发现都经历了一个艰难的过程：事件响应人员注意到某个规则*本应*触发却没有触发，并将其追溯到几个月前的一次内容更新。该工具将这种发现“左移”（提前）到了代码审查 / CI 阶段——它在每次更改时针对具有代表性的遥测数据运行实际的规则逻辑，而不仅仅是粗略查看文本差异。 其典型的应用场景包括： - **detection-as-code 仓库的 Pre-merge CI 检查**：如果任何规则更改的得分为 `HIGH`/`CRITICAL`，则使构建失败（或要求签核）。 - **更新后的 SOC 审计**：在 SIEM/EDR 内容包更新后，对比供应商的旧版和新版规则导出文件，查看发生了哪些悄然的变更。 - **检测工程 QA**：搭配一个不断增长的回归语料库（包含真实经过脱敏处理的攻击遥测数据和良性噪声），将其视为你检测项的单元测试套件。 ## 安装说明 ``` git clone https://github.com/AshwinNHacker/detection-drift-tracker.git cd detection-drift-tracker pip install -e . ``` 需要 Python 3.9+。唯一的运行时依赖是 `PyYAML`。 用于开发（测试）： ``` pip install -e ".[dev]" pytest ``` ## 用法 ### 1. 直接对比两个规则文件 ``` drift-tracker diff \ --old path/to/rule_v1.yml \ --new path/to/rule_v2.yml \ --events path/to/sample_events.json \ --html report.html \ --json report.json ``` `--events` 是可选的——省略它则仅进行字段级别的对比（不进行行为模拟）。请参阅 [`examples/sample_events/events.json`](examples/sample_events/events.json) 了解预期的格式要求：一个包含扁平事件对象的 JSON 列表（或 `{"events": [...]}`），为了报告的易读性，每个对象最好携带一个 `_id` 键。 ### 2. 遍历规则的 git 历史记录 ``` drift-tracker history \ --repo /path/to/rules-repo \ --rule-path sigma/windows/process_creation/proc_creation_win_powershell_enc.yml \ --events path/to/sample_events.json \ --html history_report.html ``` 这会找到涉及该文件的所有提交（`git log --follow`），并将每个版本与前一个版本进行对比，这样你就能获得完整的偏移事件时间线，而不仅仅是前后的快照对比。 ### 3. 运行内置演示 ``` drift-tracker demo --html demo_report.html ``` 运行包含的示例规则对（见下文）并直接打开报告——这是查看该工具实际运行效果的最快方式。 ### 退出代码（用于 CI 门控） | 所有结果中的最严重等级 | 退出代码 | |---|---| | none / low / medium | `0` | | high | `1` | | critical | `2` | 将其接入 CI 作业中： ``` - name: Check detection rule drift run: drift-tracker diff --old rules/old/x.yml --new rules/new/x.yml --events tests/events.json ``` 遇到 high/critical 级别的偏移时，非零退出码将使作业失败。 ## 本仓库内置的示例 [`examples/rules/suspicious_powershell_v1.yml`](examples/rules/suspicious_powershell_v1.yml) 和 [`suspicious_powershell_v2.yml`](examples/rules/suspicious_powershell_v2.yml) 模拟了一次真实的内容重构： - **新增**了 `pwsh.exe` (PowerShell 7+) 到进程匹配中——真正拓宽了覆盖范围。 - **缩小**了编码命令（encoded-command）的匹配范围，从 `-enc`（纯子字符串）更改为 `-enc `（要求带有尾随空格），其假设是这“与以前一样，只是更干净了”。实际上，这悄悄地导致它不再匹配完整的 `-EncodedCommand` 拼写，而分析人员和恶意软件目前都仍在使用这种完整拼写。 - **新增**了一个 `-nop -w hidden` 选择，并将条件从简单的 `and` 重写为混合了 `and`/`or`/`1 of` 的表达式。 运行 `drift-tracker demo`，你会清楚地看到：一个曾经匹配的事件不再匹配（覆盖范围丢失），两个新事件现在匹配上了（因为 pwsh.exe 的范围扩大），并且整体更改的得分为 `CRITICAL`——这是正确的，因为在真正的改进中悄然混入了一个检测漏洞。 ## 规则匹配的工作原理（及其局限性） 本项目实现了 [Sigma 规范](https://github.com/SigmaHQ/sigma-specification) 的一个**实用子集**——足以对真实的检测逻辑进行建模，但它并不是一个经过认证的、完全符合规范的 Sigma 引擎。如果你需要完全兼容 Sigma 标准（所有后端、所有修饰符、诸如 `count()`/`near` 等聚合函数），请将此工具与 [`pySigma`](https://github.com/SigmaHQ/pySigma) 搭配用于转换步骤，并将 Detection Drift Tracker 作为在此之上的偏移/回归检测层使用。 支持： - 条件语句中的 `and` / `or` / `not` / 括号 - `1 of ` / `all of ` - `1 of them` / `all of them` - `1 of *` / `all of *` 通配符选择组 - 字段修饰符：`contains`、`startswith`、`endswith`、`re`、`all`、`base64`、`cased` - 普通字段值中的通配符（`*`、`?`） - 列表值作为 OR 组；选择映射（selection-maps）列表作为 OR 组 不支持（目前还不行——见 [路线图](#roadmap)）： - Sigma 聚合条件（`count() by ... > N`，`near`） - 关联规则（Sigma 较新的多规则关联规范） - 字段间对比（`|fieldref`） ## 架构 ``` ┌──────────────┐ rule v1 ────▶ │ │ │ parser.py │ Sigma-style YAML → Rule model rule v2 ────▶ │ │ └──────┬───────┘ │ ┌──────────────┼────────────────────┐ ▼ ▼ ┌────────────────┐ ┌──────────────────┐ │ diff_engine.py │ │ simulator.py │ │ field-level │ │ compiles condition│ │ semantic diff │ │ runs vs sample │ └────────┬────────┘ │ event corpus │ │ └─────────┬──────────┘ │ field changes │ match delta └───────────────┬─────────────────────┘ ▼ ┌───────────────┐ │ scorer.py │ 0-100 drift score + severity └───────┬───────┘ ▼ ┌───────────────┐ │ report.py │ HTML (self-contained) + JSON └───────────────┘ git_source.py pulls historical file versions from a repo and feeds pairs of Rule objects through the same pipeline (see analyzer.py). ``` 有关每个模块和评分依据的更深入讲解，请参阅 [`docs/architecture.md`](docs/architecture.md)。 ## 项目布局 ``` detection-drift-tracker/ ├── src/drift_tracker/ │ ├── models.py # Rule, FieldChange, MatchDelta, DriftResult dataclasses │ ├── parser.py # Sigma-style YAML → Rule │ ├── diff_engine.py # semantic field-level diff │ ├── simulator.py # condition tokenizer/parser + event matching │ ├── scorer.py # drift scoring + severity buckets │ ├── git_source.py # git history retrieval (subprocess, no GitPython dep) │ ├── analyzer.py # orchestration (diff + simulate + score) │ ├── report.py # HTML / JSON report generation │ └── cli.py # `drift-tracker` command-line entry point ├── examples/ │ ├── rules/ # example v1/v2 rule pair used by `demo` and tests │ └── sample_events/ # example event corpus ├── tests/ # pytest suite (parser, diff, simulator, scorer, e2e) ├── docs/architecture.md └── .github/workflows/ci.yml ``` ## 路线图 - [ ] 支持 Sigma `count()`/聚合和关联规则的偏移检测 - [ ] 在相同的 `Rule` 模型下支持可插拔的规则格式（Suricata/Snort、YARA） - [ ] 输出 Markdown/SARIF 报告以用于 GitHub PR 标注 - [ ] 历史趋势视图（跨整个仓库查看每个规则随时间变化的偏移分数） - [ ] 可选集成 `pySigma` 以进行完全规范的条件评估 欢迎贡献——请参阅 [CONTRIBUTING.md](CONTRIBUTING.md)。 ## 许可证 [MIT](LICENSE)

标签：DevSecOps, 上游代理, 安全规则引擎, 安全运营, 恶意代码分类, 扫描框架, 网络安全研究, 逆向工具