matt869/detection-validation-pipeline

# 检测验证流水线 证明你的检测确实触发了——如果没有触发，说明*原因*。 大多数检测测试报告只是简单地判定通过或失败。这掩盖了一个关键的区别： 一条规则没有触发是因为其**逻辑错误**，需要检测工程师介入；而一条规则没有 触发是因为**遥测数据根本没有到达**，这需要平台团队解决。针对不存在的数据 去调整规则比什么都不做更糟糕，因为它最终会在依然存在的缺口旁边留下一个绿勾。 因此，每个验证用例都会归结为以下三种状态之一： | | | | | --- | --- | --- | | **`detected`** | 规则匹配到了行为产生的事件。 | 控制措施有效。 | | **`visible`** | 遥测数据已到达；但规则没有匹配到任何数据。 | **检测缺口** → 修复规则。 | | **`blind`** | 所需类型的遥测数据未到达。 | **可见性缺口** → 修复数据采集。 | 完整推理见 [`docs/three-state-model.md`](docs/three-state-model.md)。 ## 试一试 无需 SIEM、实验室、凭据或配置。它会重放已录制的遥测数据，且不执行任何操作： ``` $ pip install -e . $ dvp run --profile quick-smoke ``` ``` [+] detected lsass_memory_access / T1003.001-lsass-handle-open 9.0s [+] detected powershell_encoded_command / T1059.001-powershell-encoded 2.0s [x] blind defender_exclusion_added / T1562.001-defender-path-exclusion [+] detected run_key_persistence / T1547.001-run-key-appdata 4.0s noisy(1) ... detected 15 ######################.. the control works visible 0 ........................ telemetry present, rule silent - detection gap blind 1 ##...................... no telemetry - visibility gap detection rate 94% telemetry visibility 94% detect latency p50 4.0s p95 5m 31s noisy rules 1 rule(s) also match quiet-baseline activity pass no-errors no cases errored pass expectations-met every case matched its documented expectation PASS all gates satisfied ``` 那个 `blind` 结果并不是失败。`defender_exclusion_added` 声明了 `expect: blind`，因为 Defender 频道尚未接入——该缺口已被记录、分配负责人并 注明日期，因此它报告为 `pass`，同时会在覆盖报告中保持可见状态，直到其被真正 修复。 `noisy(1)` 是一个真实的发现：该规则在静默的基线时间窗口内，也匹配到了一个 Teams 自动启动项。一条规则可以同时处于 `detected` 和 noisy 状态， 而同时具备这两种状态的规则并不是一个有效的控制措施。 ## 它的工作原理 ``` plan ─> baseline ─> emulate ─> settle ─> collect ─> classify ─> score ``` 1. **Plan** — 将 profile 解析为用例（一条规则 × 一次模拟测试）。 2. **Baseline** — 在模拟行为*之前*，在一个静默时间窗口内运行每条规则，以 测量其自身产生的噪声。 3. **Emulate** — 在默认拒绝的安全策略下，产生行为。 4. **Settle** — 等待数据接入（对于已录制的语料库会跳过此步骤）。 5. **Collect** — 每个用例执行两次查询：规则的逻辑查询，和遥测探针查询。 6. **Classify** — 三态模型判定。 7. **Score** — 覆盖率对比目标，与上次运行的差异对比，质量门禁。 ## 命令 ``` $ dvp doctor --backends # config, content and connectivity $ dvp rules lint # pre-commit hook material $ dvp rules compile lsass_memory_access --dialect splunk $ dvp rules score --explain # per-rule quality grades $ dvp run --profile quick-smoke --plan-only $ dvp coverage --gaps visibility # what is not being logged $ dvp coverage --navigator layer.json $ dvp runs diff # what changed since last time $ dvp report --latest --format html $ dvp dashboard # local read-only review UI ``` 退出代码是稳定的，因此 CI 可以区分“检测发生回归”(1) 和 “无法访问 SIEM”(5)。参见 [`docs/architecture.md`](docs/architecture.md#exit-codes)。 ## 规则 Sigma 形态的 YAML，包含三个附加字段：`telemetry:`（该规则依赖的日志源—— 这正是实现三态模型的关键），`validation:`（如何验证规则），和 `tuning:`（保 留在检测逻辑之外的本地例外情况）。 ``` title: LSASS process memory accessed with credential-dumping rights severity: critical attack: tactics: [credential-access] techniques: [T1003.001] telemetry: - sysmon_process_access detection: selection_handle: EventID: 10 TargetImage|endswith: '\lsass.exe' GrantedAccess: ['0x1410', '0x1fffff'] filter_known_good: SourceImage|endswith: ['\MsMpEng.exe', '\wmiprvse.exe'] condition: selection_handle and not filter_known_good validation: emulation: [T1003.001-lsass-handle-open] expect: detected max_latency: 3m ``` 一条规则会编译为所有方言。`rulekit` 会拒绝编译而不是进行近似处理—— 如果一条规则会静默丢失其 `not filter` 子句，它会编译失败，而不会被 部署。 ``` $ dvp rules compile lsass_memory_access --dialect splunk index=windows sourcetype="XmlWinEventLog:...Sysmon/Operational" EventCode=10 (EventID="10" AND TargetImage="*\\lsass.exe" AND (GrantedAccess="0x1410" OR ...)) AND NOT (SourceImage="*\\MsMpEng.exe" OR SourceImage="*\\wmiprvse.exe") ``` 支持平台：**Splunk** (SPL)，**Elastic/OpenSearch** (Lucene)，**Microsoft Sentinel/Defender** (KQL)，以及 **fixture**——后者会编译为一个 Python 谓词，这也使得整个流水线能够在 CI 中离线运行。 ## 安全性 该流水线旨在执行攻击者形态的行为，因此其默认状态是完全不执行任何操作。在 执行任何单个命令之前，必须满足八个条件—— 包括 `host_allowlist` 不为空（**空列表意味着全部拒绝**）， 已记录授权引用，以及交互式地传递了 `--execute` 参数。破坏性技术 (T1485/T1486/T1489/T1490/T1561) 被永久列入黑名单，无法通过 profile 启用。 本仓库不包含任何攻击性载荷。测试要么是产生相同形态遥测数据的良性 模拟，要么是 `executor: manual`—— 测试框架会预留一个时间窗口并对结果进行评分，但操作员会在其自身的权限 下执行该操作。 在使用 `--execute` 运行之前，请阅读 [`docs/threat-model.md`](docs/threat-model.md)。 ## 目录结构 ``` detections/ Rules, by platform and tactic mapping/ ATT&CK reference, telemetry catalogue, coverage targets fixtures/ Emulation test definitions + recorded event corpora config/ Settings, backends, validation profiles baseline/ What "quiet" looks like, and what noise is accepted harness/ The pipeline: core, backends, emulation, analysis, reporting rulekit/ Rule parsing, linting, scoring, query compilation storage/ SQLite schema and migrations dashboard/ Local read-only review UI infra/ Sysmon config, auditd rules, CloudTrail terraform docs/ Architecture, three-state model, threat model, ADRs ``` ## 环境要求 Python 3.11+。**PyYAML 是唯一必需的依赖项**——报告、HTML 渲染器和仪表板均使用标准库构建，因此它可以运行在没有网络 访问的加固主机上。`httpx` 仅用于实时 SIEM 后端 (`pip install -e '.[live]'`)。具体原因见 [ADR 0003](docs/adr/0003-minimal-dependencies.md)。 ## 开发 ``` $ pip install -e '.[dev]' $ pytest $ ruff check . $ dvp rules lint --dialect splunk --dialect elastic ``` 离线测试套件无需任何基础设施。`make ci` 会运行与 `scheduler/jobs.yml` 中的流水线相同的检查。 ## 许可证 Apache 2.0。

标签：Detection as Code, LNA, Python, 安全运营, 恶意代码分类, 扫描框架, 攻击模拟, 无后门, 运行时操纵, 逆向工具, 驱动签名利用