JoseArgento/attack-mapper

# attack-mapper 🎯 [](https://github.com/JoseArgento/attack-mapper/actions/workflows/ci.yml) [](https://github.com/JoseArgento/attack-mapper/actions/workflows/update-attack-db.yml) [](https://pypi.org/project/attack-mapper/) [](LICENSE) 将你的 **Sigma 检测规则**映射到 **MITRE ATT&CK** 矩阵上，快速寻找你的 覆盖盲区 —— 快速、离线且 CI 友好。 作为检测工程工具包的一部分，它与 *Detection-as-Code* 流水线 (Sigma → CI → SIEM) 完美搭配。它可以回答每个 蓝队最终都会问的问题：*“我的规则实际覆盖了哪些 ATT&CK 技术， 以及盲区在哪里？”* ## 功能 - 🔍 通过以下方式从 Sigma 规则中提取 ATT&CK 技术 ID： - 规范的 `attack.` 标签， - 原始的 `T1059` 标签， - `references:` 中的 `attack.mitre.org/techniques/...` URL。 - 📊 在终端中显示按战术划分的覆盖条形图 + 总体覆盖率。 - 🎨 **四种 HTML 样式**展示你的覆盖情况： - `matrix`（默认）— 带有技术筹码的战术卡片， - `rows` — 紧凑的战术进度条， - `heat` — 每个技术的密集热力图， - `report` — 打印就绪的档案，带有规范的垂直 ATT&CK 列， 子技术嵌套在其父技术下（将其转为 PDF 可用于审计/作品集）。 - 🟢 已覆盖的技术（包括已覆盖子技术的父技术） 渲染为绿色；盲区渲染为红色；明确忽略的渲染为灰色。 - 🔎 **范围过滤器** — `--include` 和 `--ignore` 将分析范围缩小到你 关心的技术/战术（或排除你不关心的）。报告会显示当前的活动 范围，以便读者了解过滤了哪些内容。 - 🏅 **作品集徽章** (`--badge`) — 一枚 shields.io 风格的 SVG 覆盖率徽章。 - 🧾 **JSON 摘要** (`--json`) — 用于仪表盘/CI 的机器可读输出。 - 🧭 **ATT&CK Navigator 导出** — 每个 HTML 报告都嵌入了一个 “导出 layer”按钮，可下载随时可导入的 Navigator layer。 - 🧱 使用**真实的 MITRE ATT&CK 企业数据集**（v19 结构： Stealth + Defense Impairment）。已撤销/弃用的技术被 过滤掉，因此覆盖率分母与官方矩阵匹配 （15 个战术，222 个技术，475 个子技术）。以紧凑的 JSON 形式发布，运行时无需联网。 - ✅ 纯 Python 标准库 + `pyyaml`；极小的依赖占用。 - 🤖 当没有任何映射时返回非零退出码 → 在你的 检测仓库中将其用作 **CI 门禁**。 ## 截图 | `report`（打印就绪档案） | `matrix`（卡片） | | --- | --- | |  |  | ## 安装说明 ``` pip install attack-mapper ``` 用于开发： ``` python -m venv .venv && source .venv/bin/activate pip install -e ".[dev]" pytest ``` ## 运行说明 ``` # 映射包含 Sigma rules 的文件夹，打印 terminal report，生成 HTML (matrix) attack-mapper rules/ --html sample/coverage_matrix.html # 尝试其他 HTML styles attack-mapper rules/ --html sample/coverage_rows.html --style rows attack-mapper rules/ --html sample/coverage_heat.html --style heat attack-mapper rules/ --html sample/coverage_report.html --style report # 限定分析范围：仅 Execution + T1053，忽略 Reconnaissance attack-mapper rules/ --include T1059 TA0002 --ignore Reconnaissance # Portfolio artifacts：badge + JSON attack-mapper rules/ --badge sample/coverage_badge.svg --json sample/coverage.json ``` 针对内置的示例规则运行： ``` attack-mapper rules/ --html sample/coverage_matrix.html --badge sample/coverage_badge.svg ``` ## 为什么不用 sigma2attack 或 DeTT&CT？ 两者都非常优秀，你应该了解它们的存在。**sigma2attack**（来自 Sigma 工具集）将 Sigma 规则转换为 ATT&CK Navigator 热力图 layer —— 如果你只需要一个 layer 文件，它可以胜任。**DeTT&CT** 是 重量级的：它不仅对检测覆盖率进行评分，还对数据源 *可见性* 进行评分，对于进行正式能力评估的成熟 SOC 来说，它是正确的工具。 attack-mapper 介于两者之间，针对 Detection-as-Code 流水线进行了优化： 它使用内置数据集离线运行，生成可通过电子邮件发送或打印的独立 HTML 报告（加上 Navigator layer、徽章和 JSON），通过其退出码对 CI 进行门禁，并支持范围过滤器以 仅计算与你的环境相关的技术。它还是 **ATT&CK v19 原生版本**（Stealth + Defense Impairment），并带有定期的 工作流，可自动标记未来的 MITRE 更新。 ## 工作原理 ``` Sigma rules ──▶ sigma_parser ──▶ technique IDs │ ATT&CK DB ──▶ attack_loader │ ▼ coverage.build_report (with --include/--ignore) ──▶ CoverageReport │ renderers (terminal / HTML matrix|rows|heat) plugins (badge SVG / JSON) ``` ## 范围过滤器 `--include` 和 `--ignore` 接受技术 ID（如 `T1059`）、子技术 前缀（如 `T1059` 也涵盖 `T1059.001`）、战术简称 （如 `execution`）或战术 ID（如 `TA0002`）。已覆盖的技术始终会 被记录为已覆盖，即使它不在 `--include` 范围内也是如此，但只有 范围内的已覆盖技术才会计入覆盖率（分子 和分母都受限于此范围）。 ## 更新 ATT&CK 数据集 内置的 `attack_mapper/data/attack_db.json` 是一个快照（由每月的 GitHub Action 自动重新生成，当 MITRE 发布更新时会自动失败）。要从最新的 官方 STIX bundle 重新生成： ``` curl -L -o enterprise-attack.json \ https://raw.githubusercontent.com/mitre/cti/master/enterprise-attack/enterprise-attack.json ATTACK_MAPPER_STIX=enterprise-attack.json python -m attack_mapper.build_db ``` 你也可以通过设置 `ATTACK_MAPPER_STIX`，在运行时直接使用 STIX bundle。 ## 项目布局 ``` attack-mapper/ ├── attack_mapper/ │ ├── cli.py # argparse entry point │ ├── sigma_parser.py # Sigma → ATT&CK technique IDs │ ├── attack_loader.py # ATT&CK DB (compact JSON / STIX) │ ├── coverage.py # coverage + gaps + scope filters │ ├── renderers.py # terminal table + 4 HTML styles │ ├── plugins.py # badge SVG + JSON summary │ ├── build_db.py # regenerate the compact ATT&CK DB │ └── data/attack_db.json # real ATT&CK (compact, ships with the package) ├── rules/ # sample Sigma rules ├── sample/ # generated HTML / badge / JSON examples ├── tests/ # pytest suite └── pyproject.toml ``` ## 许可证 MIT

标签：ATT&CK框架, Sigma规则, 安全运营, 恶意代码分类, 扫描框架, 目标导入, 覆盖率分析, 逆向工具