ahkecha/wazuh-sigma

## 是证据，而非营销 当前提交的 Windows 基准是在严格模式下基于 **2,403 条 SigmaHQ 规则** 测量的。 | 测量指标 | 当前基准 | |---|---:| | 评估的 Sigma 规则 | **2,403** | | 语义安全的编译 | **1,925** | | 明确拒绝的规则 | **478** | | 严格转换覆盖率 | **80.11%** | | 生成的 Wazuh XML 规则 | **10,701** | | 平衡的输出块 | **4** | | XML 验证失败 | **0** | | 块验证失败 | **0** | | 原生 `wazuh-analysisd -t` | **通过** | | 测试的 Wazuh 版本 | **4.14.6** | 该基准是可重现且已提交的： - [`evidence/corpus-baseline.json`](evidence/corpus-baseline.json) - [`evidence/semantic-baseline.json`](evidence/semantic-baseline.json) - [`evidence/native-validation-baseline.json`](evidence/native-validation-baseline.json) ## 为什么会有这个项目 Sigma 和 Wazuh 不共享相同的执行模型。 Sigma 具有 selections、modifiers、分组的 boolean 条件、wildcard selectors、negation 和 abstract fields。Wazuh 具有 XML 规则、特定于 decoder 的字段名称、父 SID 关系、PCRE2 约束和 target-version 行为。 一个简单的转换器可能会生成看起来合法的 XML，同时悄悄地改变： - 将 `AND` 变为 `OR`； - 将分组的逻辑变为扁平化的 predicates； - 将排除项变为被忽略的过滤器； - 将字段语义变为猜测的名称； - 将一个 Sigma 检测变为范围过广的 Wazuh 警报。 **Wazuh Sigma Pipeline 旨在防止此类故障。** ### 转换器与编译器 | 基本转换器 | 本项目 | |---|---| | 重写语法 | 保留语义模型 | | 扁平化条件 | 构建显式的 boolean IR | | 猜测目标字段 | 使用版本化且由 fixture 支持的 mappings | | 输出一个看似合理的规则 | 规划精确的父子规则结构 | | 将 regex 编译成功视为成功 | 验证 XML 和原生 Wazuh 解析器 | | 隐藏不支持的规则 | 使用确定性的诊断信息拒绝它们 | | 追求高百分比 | 追求经得起推敲的检测 | ## 编译器架构 ``` flowchart LR A[Sigma YAML] --> B[pySigma parser] B --> C[Normalized condition tree] C --> D[Explicit boolean IR] D --> E[Semantic normalization] E --> E1[De Morgan normalization] E --> E2[DNF planning] E --> E3[Explosion limits] M[Fixture-backed field registry] --> F[Target lowering] P[Parent SID catalogue] --> F E --> F F --> G[Rule plan] G --> G1[Single-rule lowering] G --> G2[Exact child-rule lowering] G --> G3[Stable rule IDs] G --> H[Wazuh XML emission] H --> I[Structural validation] I --> J[Balanced chunks + manifest] J --> K[Native Wazuh validation] K --> L[Reports / deployment] CACH[Content-addressed cache] -. unchanged fragments .-> G AI[Optional OpenAI advisor] -. non-authoritative review .-> L CAL[Optional Caldera validation] -. controlled behavioral evidence .-> L ``` ### 编译流水线 ``` Sigma source │ ├─ parse and normalize with pySigma ├─ build boolean IR ├─ preserve AND / OR / NOT / grouping / selectors ├─ normalize grouped NOT with exact De Morgan transformations ├─ lower representable branches to Wazuh predicates ├─ generate deterministic child rules when one rule is insufficient ├─ resolve fixture-backed Wazuh fields and parent SIDs ├─ emit deterministic XML, chunks and reports └─ validate against Wazuh itself ``` ## 信任契约 编译器遵循五条不可协商的规则： 1. **绝不扁平化 boolean 逻辑。** 一条语法有效但语义不同的规则即为编译失败。 2. **绝不捏造 Windows 字段。** 严格模式要求有经过验证的 mapping，否则拒绝该规则。 3. **绝不隐藏不支持的行为。** 每次拒绝都会被分类和报告。 4. **绝不将解析器的接受与检测的正确性混为一谈。** 原生加载和行为触发是两道独立的关卡。 5. **绝不让可选系统成为权威。** AI 和 Caldera 集成无法取代确定性编译和 Wazuh 证据。 ## 语义降级 后端消费 pySigma 解析的条件树，并通过显式的 IR 对其进行降级。 | Sigma 构造 | 严格降级策略 | |---|---| | 跨不同字段的 AND | 多个 Wazuh 字段 predicates | | 同一字段上的 AND | 在可证明安全的情况下，使用独立的 PCRE2 lookaheads | | 同一字段上的 OR | PCRE2 alternation | | 跨不同字段集的 OR | 确定性的子规则分支 | | 分组/嵌套条件 | 精确的归一化和分支规划 | | 单个和分组的 NOT | predicate negation 加上精确的德·摩根归一化 | | `1 of` / `all of` selectors | 在 IR 降级之前由 pySigma 解析 | | IPv4 CIDR | 有界的 dotted-quad PCRE2 | | 超大的同字段 OR | 保持语义的子规则拆分 | | 无法表示的表达式 | 显式的故障安全拒绝 | ### 示例：为什么子规则很重要 类似这样的条件： ``` (process_image AND suspicious_argument) OR (parent_image AND network_destination) ``` 无法在一条 Wazuh 规则中扁平化为四个字段。那将要求所有四个 predicates 同时满足，并将 `OR` 变为了 `AND`。 相反，编译器会规划独立的分支，并输出为保留原始表达式所需的 Wazuh 规则结构。 ### 爆炸控制 正确的 DNF 展开在操作上仍然可能具有危险性。编译器对以下各项强制执行确定性限制： - DNF alternatives； - 每个 alternative 中的 predicates； - 生成的子规则； - 递归深度； - PCRE2 模式大小； - 总规则计划大小。 超过限制将拒绝整条 Sigma 规则。编译器绝不会输出不完整的解释。 ## 覆盖率演进历程 该项目刻意选择退一步，然后再向前进。 | 里程碑 | 严格覆盖率 | 发生了什么变化 | |---|---:|---| | 宽松基准 | **88.10%** | 输出量大，但语义审计暴露了不安全的降级 | | Boolean IR 基准 | **41.91%** | 对所有未经证明的条件形状执行故障安全关闭 | | 精确的子规则降级 | **66.50%** | 恢复了不同字段的 OR，而无需扁平化逻辑 | | 分组的 NOT + IPv4 CIDR | **79.15%** | 增加了德·摩根归一化和有界的 CIDR 降级 | | Fixture mappings + 安全的 OR 拆分 | **80.11%** | 恢复了经过验证的 mappings 和超大的 alternations | 41.91% 的结果并不是倒退。它是报告的数字变得值得信赖的关键点。 ## 当前的严格拒绝面 剩下的 478 条 Windows 规则被故意拒绝。 | 拒绝类别 | 规则数 | |---|---:| | 没有 fixture 支持的 mapping 的不受支持的 Windows 字段 | **216** | | DNF alternatives 超过配置限制 | **103** | | 生成的子规则超过配置限制 | **58** | | 未证明的 Null/existence 检查 | **58** | | 未证明的 IPv6 CIDR canonicalization | **16** | | `base64offset` | **7** | | 无字段的值表达式 | **7** | | 每个 DNF alternative 中的 predicates 超过限制 | **6** | | 没有安全支持组合的 `all` | **5** | | `fieldref` | **1** | | `ignorecase` | **1** | 这是一项功能，而不是隐藏的技术债务：不支持的语义保持可见，而不是变成微弱的检测。 ## 快速开始 需要 **Python 3.10–3.12**。 ``` git clone https://github.com/ahkecha/wazuh-sigma-pipeline.git cd wazuh-sigma-pipeline python -m venv .venv source .venv/bin/activate python -m pip install --upgrade pip python -m pip install -e ".[test]" python -m pytest ``` ### 编译并验证示例语料库 ``` sigma-convert \ --directory examples/sigma \ --output build/sigmahq/sigma_rules.xml \ --report build/conversion-report.json sigma-validate \ --rules build/sigmahq/sigma_rules.xml \ --output text sigma-validate \ --rules build/sigmahq/chunks \ --output text ``` 转换器输出： ``` build/sigmahq/ ├── sigma_rules.xml └── chunks/ ├── sigma_rules_001.xml ├── sigma_rules_002.xml ├── ... └── manifest.json ``` 已安装的命令： ``` sigma-convert sigma-validate sigma-deploy-wazuh sigma-pipeline sigma-windows-analysis ``` 在 PowerShell 上： ``` .\.venv\Scripts\Activate.ps1 ``` ## 操作 pipeline 由配置驱动的 CLI 将生命周期公开为显式的关卡： ``` sigma-pipeline doctor --config pipeline.yml sigma-pipeline convert --config pipeline.yml sigma-pipeline validate --config pipeline.yml sigma-pipeline smoke --config pipeline.yml ``` | 命令 | 职责 | |---|---| | `doctor` | 验证配置、路径、凭据、mappings 和阻碍就绪的因素 | | `convert` | 解析、降级并输出受管的 Wazuh 产物 | | `validate` | 验证现有的 XML 或 chunk 目录 | | `smoke` | 作为一个本地发布关卡运行转换和验证 | | `deploy` | 验证、备份、上传、重启、验证并回滚 | | `advise` | 生成可选的非权威质量调查结果 | | `active-test` | 运行受控的 Caldera 激励并查询 Wazuh 证据 | 相对路径从配置文件目录解析。未知的配置键会导致验证失败，而不是被静默忽略。 ### 最小配置 ``` sigma_dir: examples/sigma output_file: build/sigmahq/sigma_rules.xml conversion_report: build/conversion-report.json validation_report: build/validation-report.json strict_validation: true wazuh: rule_id_start: 900000 rule_id_end: 949999 windows_field_mapping_mode: strict host: https://wazuh.example.com:55000 remote_file: sigma_rules.xml insecure: false ca_bundle: /etc/ssl/certs/internal-ca.pem incremental_cache: enabled: false directory: build/conversion-cache manifest: build/conversion-cache/manifest.json strict: false advisor: enabled: false mode: report-only ``` 凭据和 API 密钥应放在环境变量中——而不是 `pipeline.yml` 中。 ## 由 Fixture 支持的 Windows Mapping Windows EventChannel 字段名是 decoder 的输出，而不是猜测。 ``` Sigma field │ ├─ logsource product / service / category ├─ event provider and channel context ├─ decoded Wazuh fixture evidence └─ mapping registry version ▼ win.system.* or win.eventdata.* ``` 严格模式会拒绝未知字段，而不是将其转换为看似合理的全小写名称。 ``` wazuh: windows_field_mapping_mode: strict ``` 最新恢复仅添加了以下内容的受范围限制且由 fixture 支持的 mappings： ``` Action AppName ApplicationPath ExceptionCode ModifyingApplication NewValue Service Workstation ``` 在以下位置阅读证据模型： - [Windows EVTX 字段 Mapping](docs/windows-evtx-field-mapping.md) - [Wazuh 父 SID Mapping](docs/wazuh-parent-rule-mapping.md) ## 验证阶梯 生成的规则将穿过逐步增强的关卡： ``` 1. Sigma parsing 2. Semantic IR construction 3. Fail-closed lowering checks 4. PCRE2 construction and limits 5. XML structural validation 6. Rule ID and parent SID validation 7. Balanced chunk validation 8. Native wazuh-analysisd -t 9. Behavioral event-to-alert validation ``` 提交的基准已针对当前生成的语料库通过了第 1-8 层。第 9 层仍然是独立的操作证明要求。 ### 原生 Wazuh 验证 ``` python -m pip install -e ".[test]" docker compose up -d docker cp wazuh-rule-test:/var/ossec/ruleset/rules build/wazuh-builtin-rules python scripts/normalize_wazuh_rules.py build/sigmahq \ --target-rules-dir build/wazuh-builtin-rules docker compose up -d --force-recreate docker compose exec -T wazuh.manager \ /var/ossec/bin/wazuh-analysisd -t ``` 一次成功的原生解析器运行必须以状态码 `0` 退出，且没有解析器错误。 ## 安全部署 ``` sigma-pipeline deploy \ --config pipeline.yml \ --preflight-smoke \ --backup-remote \ --rollback-on-failure \ --restart ``` 部署保护措施包括： - 认证前的本地验证； - TLS 验证和可选的自定义 CA 捆绑包； - 受管远程文件名； - 远程备份； - 重启验证； - 规则可见性检查； - 失败时回滚； - 针对现有 Wazuh 规则 ID 的冲突检查。 `--insecure` 仅适用于隔离的开发环境。 ## 确定性的增量构建 大型语料库可以重用未更改的编译片段，同时保留稳定的 Wazuh ID。 ``` incremental_cache: enabled: true directory: build/conversion-cache manifest: build/conversion-cache/manifest.json strict: false ``` 缓存是一种优化，绝不是信任边界。在发布或部署之前，始终会重新组装并验证完整的规则集。 请参阅 [增量缓存设计](docs/INCREMENTAL_CACHE.md)。 ## 刻意置于信任核心之外的可选系统 ### OpenAI advisor advisor 可以审查严重程度和检测质量，但它无权绕过编译器或验证失败。 ``` python -m pip install -e ".[advisor]" export OPENAI_API_KEY="..." sigma-pipeline advise --config pipeline.yml ``` 控制措施包括结构化响应、消毒处理、有界重试、确定性接受策略、默认仅报告以及内容寻址缓存。 请参阅 [Advisor 文档](docs/ADVISOR.md)。 ### Caldera 主动验证 主动测试工作流可以在实验室中部署受控激励，并验证 Wazuh 证据。 ``` sigma-pipeline active-test \ --config pipeline.yml \ --preflight-smoke \ --deploy \ --restart ``` Caldera 在已注册的 agent 上执行命令。此工作流属于隔离的测试环境，被刻意排除在普通 CI 之外。 ## 仓库结构图 ``` src/wazuh_sigma/ ├── backend/ boolean IR, semantic lowering and XML emission ├── converter/ Sigma loading, normalization, reporting and CLI ├── fields/ fixture-backed field registry ├── validator/ structural and native validation helpers ├── incremental/ stable IDs and content-addressed fragment reuse ├── deploy/ Wazuh API deployment, backup and rollback ├── advisor/ optional OpenAI review layer ├── active_testing/ optional Caldera-backed behavioral validation ├── config.py strict pipeline configuration ├── naming.py canonical Sigma/Wazuh naming └── pipeline.py lifecycle orchestration evidence/ committed reproducibility baselines examples/sigma/ small runnable Sigma corpus tests/ maintained unit and integration tests docs/ design, operations and support documentation scripts/ normalization and operational utilities build/ generated artifacts; ignored by Git ``` ## 文档 | 文档 | 目的 | |---|---| | [架构](docs/ARCHITECTURE.md) | 组件、边界、信任模型和 runtime 流程 | | [Pipeline](docs/PIPELINE.md) | 阶段、报告、CI 合同和扩展点 | | [Runbook](docs/RUNBOOK.md) | 操作、恢复、回滚和故障排除 | | [项目结构](docs/PROJECT_STRUCTURE.md) | 模块所有权和仓库布局 | | [转换覆盖率](docs/CONVERSION_COVERAGE.md) | 语料库方法论、基准和发布关卡 | | [支持矩阵](docs/SUPPORT_MATRIX.md) | 支持的版本、语义和就绪边界 | | [Windows EVTX Mapping](docs/windows-evtx-field-mapping.md) | Mapping 证据和贡献者工作流 | | [父 SID Mapping](docs/wazuh-parent-rule-mapping.md) | 父规则锚定和 target-version 说明 | | [增量缓存](docs/INCREMENTAL_CACHE.md) | 指纹、稳定 ID、失效和恢复 | | [Advisor](docs/ADVISOR.md) | Provider、策略、消毒处理和操作模式 | ## 已知边界 本项目处于 **Beta** 阶段，不声称具有普遍的 Sigma 兼容性。 当前的边界包括： - 以 Windows 为先的由 fixture 支持 mapping 覆盖率； - 严格拒绝不受支持或未经验证的字段； - 在 decoder 文本 canonicalization 得到证明之前，拒绝 IPv6 CIDR； - 不支持的 null 检查、`base64offset` 和 `fieldref` 语义； - 故意的 DNF 和子规则爆炸限制； - 特定于 Wazuh 版本的父 SID 和已解码的字段行为； - 将行为级别的事件到警报的验证作为单独的发布关卡。 对于不支持的规则，正确的响应应是给出精确的诊断——而不是产生一个较弱的检测。 ## 贡献 高价值的贡献包括： - 经过消毒处理的 Wazuh 解码事件 fixtures； - 带有出处的已验证字段 mappings； - Sigma 语义边界情况和差分测试； - Wazuh 版本兼容性证据； - 减少子规则数量的安全规则计划优化； - 由真实 decoder fixtures 支持的 Linux 和 macOS 遥测配置文件； - 行为级别的 `wazuh-logtest` 或同等的事件到警报测试。 每一个语义更改都应包含正面、部分和负面的情况。每一个被描述为已验证的 mapping 都应包含证据。 ## 许可证 管理本仓库的许可证是 [PolyForm Noncommercial License 1.0.0](LICENSE.md)。

标签：PB级数据处理, Python, Wazuh, 安全运维, 无后门, 规则编译器, 逆向工具