stefanicla/gaphound

# GapHound **GapHound** 是一款命令行工具，用于将威胁行为者的 MITRE ATT&CK 技术与您的 Sigma 检测规则进行比对。它会告诉您哪些攻击者行为已被捕获、哪些被遗漏（差距），以及哪些差距最为关键——随后生成优先级报告和 ATT&CK Navigator 图层以供可视化。 专为需要解答以下问题的检测工程师和威胁情报分析师设计：*“如果该行为者明天攻击我们，我们的 SIEM 究竟能对他们的哪些动作发出告警——而哪些又会悄无声息地漏掉？”* ## 问题陈述 安全团队在编写检测规则上投入巨大，但他们很少对**覆盖率**有清晰的认知：他们的规则实际检测到了哪些攻击技术，又遗漏了哪些。这导致了盲区——即没有任何告警覆盖的攻击者行为，往往只有在事件发生后才被发现。 GapHound 通过将两个知名框架进行映射比对来解决此问题： - **MITRE ATT&CK** — 一个关于对手战术、技术和程序 (TTP) 的知识库。每个威胁行为者都由已知使用的技术进行编目。 - **Sigma** — 一种用于 SIEM 检测规则的通用特征码格式。每个 Sigma 规则的 `tags` 字段声明了它所检测的 ATT&CK 技术。 通过比对两者，GapHound 会识别出差距并按优先级进行排序，让您明确应将检测工程的重点放在何处。 ## 使用的 CTI 概念 | 概念 | GapHound 的使用方式 | |---------|---------------------| | **MITRE ATT&CK** | 加载 ATT&CK Enterprise STIX 数据包，并解析每个威胁行为者已知的技术（包括子技术及其父级关系）。 | | **Sigma** | 解析 Sigma 规则文件 (`*.yml`/`*.yaml`)，从 `tags` 字段中提取 ATT&CK 技术 ID，并构建覆盖率映射。 | | **痛苦金字塔 (Pyramid of Pain)** | 高价值战术（凭据访问、持久化、防御规避等）中的差距得分更高，因为检测到这些会给攻击者造成最大的痛苦。低价值差距（发现、收集）排名较低。 | | **检测覆盖率** | 计算至少被一条 Sigma 规则覆盖的某行为者技术的百分比——这一数值总结了您针对该行为者的检测态势。 | | **子技术汇总** | 针对父级技术（例如 `T1059`）打标签的规则通常也能捕获其子技术（例如 `T1059.001` PowerShell）。GapHound 可以选择将父级覆盖视为对子级的部分覆盖——这是在精确度和覆盖广度之间进行的一种务实权衡。 | ## 安装说明 ### 前置条件 - [uv](https://docs.astral.sh/uv/)（Python 包及版本管理器） - 约 50 MB 磁盘空间用于存放 ATT&CK STIX 数据包（首次运行时自动下载） ### 设置 ``` # Clone 仓库 git clone && cd gaphound # 安装所有依赖 + 创建 virtual environment (Python 3.14) uv sync # 验证安装 uv run gaphound --version ``` 首次使用时，GapHound 会下载 MITRE ATT&CK Enterprise STIX 数据包（约 50 MB）并将其缓存在 `~/.gaphound/attack/enterprise-attack.json`。随后的运行无需联网，且瞬间完成。 ## 使用说明 ### 列出已知的威胁行为者 ``` # 所有 actors (按名称排序) uv run gaphound list-actors # 按名称或别名搜索 uv run gaphound list-actors --search bear # 限制输出 uv run gaphound list-actors --limit 10 ``` ### 显示行为者的技术 ``` # 按名称 (不区分大小写) uv run gaphound show-actor APT29 # 按别名 uv run gaphound show-actor "Cozy Bear" ``` ### 分析检测覆盖率（主命令） ``` uv run gaphound analyze --actor "APT29" --rules ./data/sigma_rules --out ./output ``` 选项： | 标志 | 默认值 | 描述 | |------|---------|-------------| | `--actor` / `-a` | *(必填)* | 威胁行为者名称或别名 | | `--rules` / `-r` | `./data/sigma_rules` | Sigma `.yml`/`.yaml` 规则文件夹 | | `--out` / `-o` | `./output` | 报告文件的输出目录 | | `--md` / `--no-md` | 开启 | 生成 Markdown 报告 | | `--html` / `--no-html` | 关闭 | 生成带样式的 HTML 报告 | | `--navigator` / `--no-navigator` | 开启 | 生成 ATT&CK Navigator 图层 JSON | | `--subtechnique-rollup` | 关闭 | 将父级技术覆盖视为同时覆盖子技术 | ### 示例：包含所有输出的完整分析 ``` uv run gaphound analyze --actor "APT29" \ --rules ./data/sigma_rules \ --out ./output \ --html \ --subtechnique-rollup ``` 这会在 `./output/` 目录下生成三个文件： | 文件 | 描述 | |------|-------------| | `gaphound_APT29.md` | Markdown 报告（摘要、已覆盖表、优先级差距表、方法论） | | `gaphound_APT29.html` | 带样式的 HTML 报告（独立文件，可在任何浏览器中打开） | | `gaphound_APT29_navigator.json` | ATT&CK Navigator 图层（在 [mitre-attack.github.io/attack-navigator](https://mitre-attack.github.io/awhettack-navigator) 加载） | ### 终端输出 `analyze` 命令会在终端打印出详细的摘要： ``` Actor: APT29 (G0016) Techniques used: 119 Coverage: 3.4% (4 covered / 115 gaps / 119 total) Top gaps (highest priority first): Score ID Name Tactics 25 T1001.002 Steganography Command and Control 25 T1003.004 LSA Secrets Credential Access 25 T1003.006 DCSync Credential Access 25 T1021.001 Remote Desktop Protocol Lateral Movement ... Wrote output/gaphound_APT29.md Wrote output/gaphound_APT29_navigator.json ``` ### ATT&CK Navigator 图层 通过 **Open Existing Layer → Upload from File**，在 [mitre-attack.github.io/attack-navigator](https://mitre-attack.github.io/attack-navigator) 加载生成的 `*_navigator.json`。已覆盖的技术显示为绿色，差距显示为红色，以便您在 ATT&CK 矩阵网格中直观地看到盲区。 ### 更新 ATT&CK 数据 ``` uv run gaphound update-attack ``` 强制重新下载最新的 ATT&CK STIX 数据包。 ## 工作原理 ``` ┌─────────────────┐ ┌──────────────────┐ │ ATT&CK STIX │ │ Sigma Rules │ │ (actor → techs) │ │ (tags → techs) │ └────────┬────────┘ └────────┬─────────┘ │ │ ▼ ▼ attack_ingest.py sigma_parser.py (resolve actor + (parse YAML, techniques) extract ATT&CK IDs) │ │ └──────────┬───────────┘ ▼ gap_engine.py (COVERED / GAP / EXTRA sets, scoring, rollup) │ ▼ report.py (Markdown + HTML + Navigator layer) ``` ### 架构 - **`src/gaphound/`** — Python 包（src 布局，以可编辑模式安装）。 - `models.py` — pydantic v2 冻结模型：`Tactic`、`Technique`、`Actor`、 `Rule`、`LogSource`、`GapResult`、`GapItem`、`CoveredItem`。 - `attack_ingest.py` — 下载/缓存 ATT&CK STIX 数据包，按名称或别名解析行为者（不区分大小写），检索其技术。 - `sigma_parser.py` — 递归扫描 Sigma 规则文件夹（通过 pySigma），从 `tags` 中提取 ATT&CK 技术 ID，构建覆盖率映射。 - `gap_engine.py` — 将行为者技术与覆盖率映射进行比对， 生成 COVERED/GAP/EXTRA 集合，计算覆盖率百分比，并对差距进行评分。 - `report.py` — 将结果渲染为 Markdown、HTML (jinja2) 和 ATT&CK Navigator 图层 JSON。 - `cli.py` — 包含 `list-actors`、`show-actor`、`update-attack` 和 `analyze` 命令的 typer CLI；丰富的终端输出。 - **`data/sigma_rules/`** — 9 个示例 Sigma 规则（开箱即用）。 - **`tests/`** — 73 个测试，无需网络（使用内存中的 STIX fixture）。 ### 差距评分模型 差距通过一个简单且可解释的评分模型进行优先级排序： | 组件 | 分数影响 | 原理 | |-----------|-------------|-----------| | 基础分 | +10 | 每一个差距都很重要。 | | 高价值战术 | +15 | 执行、持久化、权限提升、防御规避、凭据访问、横向移动、命令与控制、影响。这些对应入侵过程中最具破坏性的阶段。 | | 父级已覆盖（仅汇总） | −5 | 宽泛的父级规则很可能捕获部分子技术，因此差距的紧迫性较低。 | **分数范围：** 5–25。报告展示了每个差距的分数明细，以便分析师理解*为什么*某项差距会排在相应的位置。 ## 开发 ``` # Quality gates (在完成任何更改之前运行) uv run ruff check src tests # lint uv run ruff format --check src tests # formatter uv run mypy src/gaphound # typecheck uv run pytest -q # all tests # 运行单个测试 uv run pytest tests/test_gap_engine.py::test_rollup_on_parent_covers_subtechnique ``` 有关详细的贡献者指南、架构说明和注意事项，请参阅 `AGENTS.md`。 ## 技术栈 | 工具 | 用途 | |------|---------| | [Python 3.14](https://www.python.org/) | 编程语言 | | [uv](https://docs.astral.sh/uv/) | 包与版本管理 | | [typer](https://typer.tiangolo.com/) | CLI 框架 | | [rich](https://rich.readthedocs.io/) | 终端输出 | | [pydantic v2](https://docs.pydantic.dev/) | 数据模型 | | [mitreattack-python](https://github.com/mitre-attack/mitreattack-python) | ATT&CK STIX 摄取 | | [pySigma](https://github.com/SigmaHQ/pySigma) | Sigma 规则解析 | | [jinja2](https://jinja.palletsprojects.com/) | HTML 报告模板 | | [pytest](https://docs.pytest.org/) | 测试 | | [ruff](https://docs.astral.sh/ruff/) | Lint 与格式化 | ## 许可证 MIT

标签：威胁情报, 安全, 安全规则引擎, 开发者工具, 覆盖率分析, 超时处理, 逆向工具