Al-Gharbi/win-ir-triage

# win-ir-triage **Windows 事件响应分诊与时间线构建工具。** 解析 Windows EVTX 事件日志，通过真正的 Sigma 格式检测规则引擎 （手写评估器，无 `eval()`）运行，将命中结果与 MITRE ATT&CK 进行关联，并生成双语（英语/阿拉伯语，全 RTL）HTML 事件 时间线 —— 外加 JSON 和 ATT&CK Navigator 导出，以便输入到其他 工具中。    ## 为什么开发此工具 这里的大多数独立组件（EVTX 解析、Sigma 规则、MITRE 映射）已经作为成熟的、独立的工具存在。在快速分诊场景中通常缺失的是把它们粘合在一起：将其指向少量导出的 日志，即可获得一个按时间顺序排列、优先级排序并带有 MITRE 标签的视图 —— 而无需先搭建完整的 SIEM。这适用于案件的前 30 分钟，而不是作为 Splunk/Elastic 的替代品。 ## 功能 - **真正的 Sigma 格式规则** — [Sigma](https://github.com/SigmaHQ/sigma) YAML 检测格式的一个真实（有文档记录的）子集： 命名的 selection/filter 块，`contains` / `startswith` / `endswith` / `re` 修饰符，list-as-OR 和 `|all` list-as-AND，以及布尔值 `condition` 表达式（`and` / `or` / `not` / 括号）—— 由一个小巧的手写递归下降解析器匹配，而非使用 `eval()`。 - **10 条内置检测规则**，涵盖 Persistence、Defense Evasion、 Credential Access、Execution、Privilege Escalation、Lateral Movement 和 Discovery（参见[下表](#bundled-rule-pack)）。 - **MITRE ATT&CK 关联**，包括可直接导入的 [ATT&CK Navigator](https://mitre-attack.github.io/attack-navigator/) 层导出。 - **双语 HTML 报告**（英语/阿拉伯语，实时切换，适当的 RTL 布局）—— 专为使用阿拉伯语的分析师和利益相关者构建，而不是事后的草率翻译。 - **JSON 导出**，用于输入到其他工具中。 - 同时处理经典的 **Windows Security auditing** 事件和 **Sysmon** 事件（以及某些 provider，例如日志清除事件，用来代替 `` 的基于 `` 的 schema）。 ## 工作原理 ``` .evtx files rules/*.yml (Sigma subset) | | v v parser.py ----------------> sigma.py (flatten to one record (evaluate every rule per event, System + against every event) EventData/UserData in one namespace) | | +----------> timeline.py <-+ (sort chronologically, attach hits, summarize) | v report.py (bilingual HTML / JSON / Navigator layer) ``` 事件被扁平化为每条记录一个扁平的 dict（`EventID`、`Channel`、 `Computer`，加上每个合并到同一命名空间的 `` 字段），这是特意设计的，以便规则文件可以像现实中的 Sigma 规则（`Image`、`TargetUserName`、`GrantedAccess`、 ...）那样引用字段，且无需转换层。 ## 安装说明 ``` git clone https://github.com/Al-Gharbi/win-ir-triage.git cd win-ir-triage pip install -r requirements.txt ``` 需要 Python 3.10+（全程使用 `from __future__ import annotations` 和 现代 type-hint 语法）。 ## 用法 ``` python -m win_ir_triage \ --evtx Security.evtx Microsoft-Windows-Sysmon%4Operational.evtx \ --rules rules/ \ --case-name "HOST01-2026-05-11" \ --out-dir out/ \ --json --navigator ``` 这将打印一份控制台摘要（严重程度计数、触及的 MITRE 技术） 并写入 `out/HOST01-2026-05-11.html`（在浏览器中直接打开 — 完全自包含，无外部资产），此外还可以选择生成 `.json` 时间线和 `.navigator.json` ATT&CK 层。 请参阅 [`examples/sample_report.html`](examples/sample_report.html) 获取 完整的示例报告（由下文描述的合成 fixture 生成，而非真实数据）。 ## 内置规则包 | ID | 标题 | 战术 | MITRE | |----|-------|--------|-------| | wit-001 | Member Added to Local Administrators Group | Persistence / Priv Esc | T1098, T1136.001 | | wit-002 | New Local User Account Created | Persistence | T1136.001 | | wit-003 | Windows Event Log Cleared | Defense Evasion | T1070.001 | | wit-004 | Suspicious LSASS Process Access | Credential Access | T1003.001 | | wit-005 | Suspicious Encoded/Hidden-Window PowerShell | Execution | T1059.001 | | wit-006 | UAC Bypass via Registry Hijack (Fodhelper/EventVwr-style) | Privilege Escalation | T1548.002 | | wit-007 | Suspicious Service Installation (PsExec-style) | Lateral Movement | T1569.002 | | wit-008 | Host/Network Reconnaissance Commands | Discovery | T1087, T1082, T1016 | | wit-009 | Explicit Credential Logon / Interactive RDP | Lateral Movement | T1078, T1021.001 | | wit-010 | Office/PDF App Spawning a Command Interpreter | Initial Access / Execution | T1566.001, T1204.002 | 编写自己的规则只需将 `.yml` 文件添加到 `rules/` 中 —— 请参阅 [`rules/persistence_account_added_to_admins.yml`](rules/persistence_account_added_to_admins.yml) 获取最小示例以及下方的 [Sigma 子集规范](#sigma-subset-supported--not-supported)。 ## Sigma 子集：支持 / 不支持 **支持：** 通过 `condition` 字符串 （`and`/`or`/`not`/括号）组合的命名 `detection` 块；使用 `|contains`、 `|startswith`、`|endswith`、`|re` 进行字段匹配；作为 OR 的列表值；用于 AND-across-list 的 `|all` 可组合 修饰符；不区分大小写的字符串匹配；无论零填充如何对十六进制字段进行数值比较（有关最后一个为何 存在的说明，请参阅下方的[方法论](#methodology--validation)）。 **（目前）不支持** —— 此处文档记录它们而不是静默失败： `1 of selection*` / `all of them` 聚合量词，Sigma 关联规则 / `near()` 时间范围，以及完整的官方 Sigma value-list 扩展。使用这些内容的规则将会加载，但不支持的部分只会被简单地忽略不评估 —— 如果对特定规则有疑问，请检查 [`win_ir_triage/sigma.py`](win_ir_triage/sigma.py)。向 SIEM 查询语言（Splunk SPL、 Elastic、Sentinel KQL）的真正转换有意被排除在此工具的范围之外 —— 那是一个已经解决的问题（[`pySigma`](https://github.com/SigmaHQ/pySigma) 做得很好）；本项目关注的是**直接的、本地的、无需 SIEM 的评估**，这是一个不同的使用场景。 **⚠️ 一个有文档记录的 YAML 陷阱：** 如果一个规则在同一个 selection 块内需要对*同一个字段*设置两个条件，你不能重复键名 （在同一个映射中先 `Image|contains: 'a'` 然后 `Image|contains: 'b'`）—— YAML 会静默地仅保留最后一个。请改用带有 `|all` 修饰符的列表：`Image|contains|all: ['a', 'b']`。这正是 在开发 `wit-006`（见下文）期间发现的 bug。 ## 方法论 / 验证 每条内置规则在开发期间都针对来自 [**EVTX-ATTACK-SAMPLES**](https://github.com/sbousseaden/EVTX-ATTACK-SAMPLES) （Samir Bousseaden）的真实、带有技术标签的样本进行了验证 —— 这是一个众所周知的公开 EVTX 导出语料库，每份样本捕获了一种特定的 ATT&CK 技术。该数据集**未捆绑** 在此仓库中（它是 GPL 许可的，并且相当大）；如果要 重现验证或针对真实技术样本对新规则进行压力测试，请单独 clone 它。 该测试过程捕获了两个真实的 bug，它们都被保留为回归测试，因此它们不会再静默重现： 1. **十六进制零填充不匹配** —— Sysmon 的 `GrantedAccess` 字段 根据 provider/OS 版本的不同，零填充方式不一致（`0x1f1fff` vs `0x001f1fff`），这破坏了针对真实样本的 LSASS 访问规则上的纯字符串相等匹配。通过按数值比较 十六进制外观的值已修复。请参阅 `tests/test_sigma_engine.py` 中的 `test_hex_values_match_regardless_of_zero_padding`。 2. **重复的 YAML 键静默冲突** —— UAC 绕过规则（`wit-006`）的早期草稿在同一 块中有两个 `TargetObject|contains:` 键；YAML 只保留了第二个，静默丢弃了第一个 条件。使用 `|contains|all` 重写（参见上文的陷阱）。 单元测试套件（`tests/`）本身使用了一个小巧的、完全**原创的、 手写的合成事件 fixture** （`tests/fixtures/synthetic_incident.py`），而不是捆绑第三方的 样本数据 —— 这是一个虚构的、戏剧化的单主机场景（钓鱼 附件 → 编码的 PowerShell → 凭据转储 → 后门管理员 账户 → 横向移动 → 日志清除），旨在测试每一条 捆绑规则以及一个故意的良性事件，因此该套件具有零 外部数据依赖性，并且运行时间远不到一秒。`examples/` 中的示例 报告也是由这同一个 fixture 生成的。 ``` pytest tests/ -v ``` ## 路线图 - Registry hive 解析（Run/RunOnce 键、UserAssist），以将覆盖范围扩大到 基于事件日志的 artifact 之外 - `1 of selection*` / `all of them` Sigma 量词支持 - 可选的真正 `pySigma` 后端，用于在本地评估器之外进行 SIEM 查询导出 - Prefetch / Amcache / ShimCache 摄取 ## 许可证 MIT —— 参见 [LICENSE](LICENSE)。 ## 鸣谢 规则验证针对 Samir Bousseaden 的公开 [EVTX-ATTACK-SAMPLES](https://github.com/sbousseaden/EVTX-ATTACK-SAMPLES) 数据集进行（未在此处重新分发 —— 参见 [方法论](#methodology--validation)）。检测逻辑受 [Sigma](https://github.com/SigmaHQ/sigma) 项目和 [MITRE ATT&CK](https://attack.mitre.org) 框架启发。

标签：AMSI绕过, Python, 威胁检测, 安全运营, 库, 应急响应, 扫描框架, 无后门, 逆向工具