Big-Comfy/detsema

**detsema 可以告诉你哪些检测规则永远无法匹配它们所监控的事件。** 它完全离线运行，无需连接 SIEM。它将检测规则编译为类型化的中间 表示，将规则读取的每个字段与已声明的 schema 清单进行连接比对，并报告 规则执行健康状况永远无法体现的逻辑端缺陷。 使用它来回答三个“检测即代码” (detection-as-code) 的问题： - 哪些规则依赖于 pipeline 中没有任何数据源会输出的字段 —— 即无论 telemetry 多么健康，也永远无法匹配的谓词？ - 哪些规则悄无声息地与我的 schema 冲突 —— 例如大小写错误、对字符串字段进行数值比较 —— 并且在部署时毫无提示？ - 我的语料库 (corpus) 实际读取了什么：完整的字段依赖足迹（按规则统计以及整个语料库范围）？ 无需 agent。无需凭证。输入文件，输出结果。目前仅支持 Sigma 这一种 dialect。 [入门指南](#get-started) | [检查结果](#findings) | [CI 门禁](#ci-gates) | [Schema 清单](#schema-inventories) | [支持的 dialect](#supported-dialects) | [验证](#validation) | [文档](#docs) ## 示例 此演示针对一个全新的公开 [SigmaHQ/sigma](https://github.com/SigmaHQ/sigma) 克隆仓库运行了依赖普查 —— 包含 3,140 条规则：

99.7% 的语料库被编译为可靠的 IR；那 9 条未能成功编译的规则会被标记为 `unsupported` (不支持) 结论，绝不会进行静默的近似处理。覆盖范围契约详见 [SUBSET.md](SUBSET.md)。 将规则与已声明的 schema 进行比对检查，可以找出隐蔽的破坏性问题：

示例的文本、JSONL 和 SARIF 报告位于 [docs/examples](docs/examples/) 中。 如需更深入的解释 —— 为什么检测逻辑需要一个编译器，以及类型化的 IR 能带来什么价值 —— 请阅读 [Detection rules are programs](https://big-comfy.github.io/detsema/)。 ## 开始使用 从 [releases 页面](https://github.com/Big-Comfy/detsema/releases) 下载适用于 macOS、Linux 或 Windows（amd64 和 arm64）的二进制文件，或者从源码安装： ``` go install github.com/Big-Comfy/detsema/cmd/detsema@latest ``` 然后运行： ``` detsema deps --rules ./rules # the corpus footprint detsema schema infer --events sample.ndjson --out schema.json # declare ground truth from real events detsema check --rules ./rules --schema schema.json # verdicts ``` 退出代码是稳定的：`0` 表示正常无误，`1` 表示发现了达到或高于 `--fail-on`（默认为 `error`）级别的问题，`2` 表示运行失败。 ## 检查结果 detsema 将规则*读取*的内容与 pipeline *提供*的内容区分开来，并对两者之间的差异做出判定。 | 问题类型 | 含义 | 通常的责任方 | |---|---|---| | `unknown-field` | 规则读取了 schema 中未声明的字段；该谓词永远无法匹配 | 检测工程 (detection engineering) | | `case-mismatch` | 字段与已声明的字段仅大小写不同；后端对于这种情况能否生效存在分歧 | 检测工程 (detection engineering) | | `type-mismatch` | 对类型不兼容的字段进行数值比较或 CIDR 匹配 | 内容或解析器所有者 | | `unsupported` | 规则使用了文档记录覆盖范围之外的构造；无法给出判定结论 | 规则作者，或 detsema（请提交 issue） | 每项检查结果都包含规则文件、行号、标题和 ID。不支持的规则依然会贡献那些已成功解析的字段引用，并被标记为 partial (部分的) —— 这是一个下限，绝不会作为完整结果呈现。 实用标志 (flags)： | 标志 | 用途 | |---|---| | `--schema inv.json` | 用于进行判定比对的清单；省略此项仅检查解析健康状况 | | `--format text\|jsonl\|sarif` | 面向人类、pipeline 或代码扫描的输出格式 | | `--fail-on error\|warning\|note\|never` | CI 门禁阈值 | | `--out FILE` | 将报告写入 stdout 以外的其他位置 | ## CI 门禁 SARIF 输出会在问题行号处对规则 PR 进行注解： detsema 自身的 CI 在每次 push 时都会运行 SigmaHQ 普查，作为解析覆盖率的回归测试门禁 —— 即演示中用到的同样两条命令，任何人都可以复现。 ## Schema 清单 判定结论的准确性，仅取决于它所比对的基准真相 (ground truth)，因此每份 `check` 报告 都会注明它所信任的清单。清单是一个 JSON 文件 （[格式](examples/schema/windows-process-creation.json)，`detsema-schema/v1`），可通过以下三种方式构建： | 来源 | 命令 | 基准真相质量 | |---|---|---| | 真实事件样本 | `detsema schema infer --events sample.ndjson` | 来源于 pipeline 实际输出内容的证据 | | Elastic Common Schema | `detsema schema import-ecs ecs_flat.yml` | 标准规范，而非你的实际部署环境 | | 手动编写 | 任意编辑器 | 取决于你的文档质量 | 计划中：[deadair](https://github.com/Big-Comfy/deadair) —— 由同一维护者维护的、负责此问题环境端部分的工具 —— 它以只读方式从实时的 Elastic/OpenSearch 映射中导出清单， 从而让静态判定建立在集群事实之上。deadair 负责查找那些结构完好但缺乏 telemetry 支持的规则； detsema 负责查找那些 telemetry 充足但逻辑损坏的规则。两者对彼此负责的故障类型互不感知。 ## 支持的 dialect | Dialect | 状态 | 证据 | |---|---|---| | Sigma | 支持 | 99.7% 的公开 SigmaHQ 语料库可编译为可靠的 IR；契约详见 [SUBSET.md](SUBSET.md)；CI 中包含普查 | | KQL / EQL (子集) | 计划中 | 将由 deadair 的 Elastic 后端作为首个使用者拉取 | | SPL (子集) | 按需求排序 | 无时间表 | 支持状态说明： | 状态 | 含义 | |---|---| | 支持 | 具备文档化的覆盖契约、语料库规模的证明、健全性测试以及稳定的输出兼容性 | | 预览 | 已存在前端，契约已文档化，但语料库验证尚不完整 | | 计划中 | 已确定范围但尚未开始；不提供支持保证 | 每种 dialect 的健全性标准：如果出现 IR 无法精确表示的构造，将明确给出 `unsupported` (不支持) 的判定结论。 错误的判定比没有判定更糟糕。 ## 验证 语料库数据可通过 `make corpus` 复现，并在每次 push 时于 CI 中运行。`Eval` 语义由表驱动 (table-driven) 的规范一致性测试覆盖，包括对真实规则结构进行的 YAML→IR→eval 往返测试。与独立的 Sigma 引擎 （Hayabusa、Chainsaw）进行差异化评估，以及在生产仓库中进行内部“吃自己的狗粮” (dogfooding) 测试均已列入计划，并在 [验证](docs/validation.md) 中如实记录 —— 包含已证明的内容以及尚未证明的内容。 如果 detsema 给出的判定结论与 Sigma 规范或真实后端相矛盾， 这将被本项目视为最高优先级的 bug： [错误判定报告模板](.github/ISSUE_TEMPLATE/false_verdict.md)。 ## 报告处理 检查结果会暴露出你的盲区规则和 schema 字段。请将报告视为敏感的 SOC 资产。 - detsema 在运行时不建立任何网络连接，没有电话回传 (phone-home) 行为或使用情况 遥测。 - 规则内容绝不打包：SigmaHQ 语料库在测试时根据其自身的 许可证进行克隆；`examples/` 中的所有内容均为合成数据。 - 见证事件（来自第 2 阶段）在构建上均属于合成的良性数据。 ## 文档 - [使用指南](docs/usage.md) - 首次普查、schema 清单、判定结论、输出格式、CI 门禁。 - [文章](https://big-comfy.github.io/detsema/) - 为什么检测逻辑需要一个编译器。 - [架构](docs/architecture.md) - IR 模型、处理流程契约、安全属性、范围。 - [验证](docs/validation.md) - 已证明的内容、复现方法以及尚未证明的内容。 - [SUBSET.md](SUBSET.md) - Sigma 覆盖契约。 ## 许可证 Apache-2.0。如果未来出现商业层级，本仓库中的所有内容仍将保持 Apache-2.0 许可证。

标签：EVTX分析, Go, Homebrew安装, Ruby工具, 云安全监控, 安全合规, 安全运营, 扫描框架, 日志审计, 网络代理, 规则校验, 静态分析