SWolfSec/Threat-Hunting-As-Code

# Threat-Hunting-As-Code 本仓库将威胁狩猎视为可维护的工程资产：进行版本控制、可审查、可衡量且持续改进。 ## 为什么将威胁狩猎作为代码 传统的狩猎跟踪通常存在于电子表格、一次性的笔记或互不关联的工单中。这会导致偏差、复用性差以及可见性薄弱。 Threat-Hunting-As-Code 标准化了狩猎流程，使团队能够： - 复用经过验证的假设和查询逻辑 - 在适当的责任机制下执行彻底的审查 - 随着时间的推移衡量覆盖率、执行节奏和结果 - 跨团队和跨时区扩展分析师的知识 ## PEAK 威胁狩猎原则 使用 PEAK 模型来指导每一个狩猎工件： - **P - Prioritized (优先级排序)**：专注于具有最高风险的对手行为和资产。 - **E - Evidence-driven (证据驱动)**：在具体的遥测假设而非仅仅依靠直觉的基础上构建狩猎。 - **A - Actionable (可操作)**：确保发现能够触发遏制、检测或加固行动。 - **K - Knowledge-sharing (知识共享)**：捕获上下文和经验教训，以便改进未来的狩猎。 ## 狩猎类型 本项目支持多种狩猎类别，以便团队可以平衡主动和被动工作： - **假设驱动的狩猎**：从特定的对手技术或可疑行为开始并进行测试。 - **情报驱动的狩猎**：将外部威胁情报转化为内部遥测检查。 - **基线/异常狩猎**：建立正常模式并调查偏差。 - **检测盲区狩猎**：验证已知的攻击路径是否绕过了当前的检测。 - **验证/重新测试狩猎**：在控制或环境更改后重新运行以前的狩猎。 ## 仓库结构 - `.github/ISSUE_TEMPLATE/new-hunt.yml` - 通过 GitHub Issues 提交的标准狩猎表单。 - `.github/workflows/hunt-metrics.yml` - 生成狩猎指标/仪表板输入的工作流。 - `.github/workflows/suggest-hunt-ideas.yml` - 用于生成或提议狩猎想法的工作流。 - `templates/hunt-template.md` - 规范的狩猎内容模板。 - `templates/campaign-template.md` - 规范的高级活动总体模板。 - `campaigns/` - 活动 Markdown 工件（仅限总体）。 - `scripts/metrics/` - 解析和仪表板生成脚本。 - `docs/dashboard.md` - 仪表板文档和指标定义。 ## 快速开始（活动 + 狩猎） 1. 使用 GitHub 问题表单 **New Campaign** **创建一个活动**，然后使用 `templates/campaign-template.md` 将批准的总体方案添加到 `campaigns/.md` 下（将 `campaign_slug` 设置为唯一的 kebab-case 值）。 2. 在 `hunts/` 下**创建单独的狩猎**，并通过设置 **`campaign_slugs`**（首选）和/或在 **`campaigns`** 中设置一个与活动的 `campaign_slug` 完全匹配的 kebab-case 条目来将它们链接到总体方案。独立狩猎可以保留 `campaigns: ["none"]` 并省略 `campaign_slugs`。 之后，（手动）开启一个 PR：CI 会验证狩猎 + 活动的元数据；合并后，指标会刷新 `docs/dashboard.md` 并自动更新每个活动文件的 **Linked hunts** 和 **Aggregated outcomes** 部分。 ### 问题提交自动引导 当猎人提交 **New Threat Hunt** 或 **New Campaign** 收集问题时，`.github/workflows/bootstrap-from-issue.yml` 会自动： 1. 解析问题表单的回答 2. 从匹配的模板（`hunts/` 或 `campaigns/`）生成草稿文件 3. 创建一个带有包含已生成工件的提交的唯一分支，以便猎人可以在提交 PR 之前进行审查/完善 ## 问题指南 为了保持收集过程的安全性和可预测性，自动模板生成仅对具有 **write**（写入）权限（或更高级别）的仓库协作者运行。 - 如果问题作者具有 `write` 或 `admin` 权限，引导工作流将正常运行。 - 如果问题作者具有 `read`、`triage` 权限或没有协作者权限，工作流将成功退出并跳过生成。 如果您在开启收集问题之前有一般性问题、想法或需要帮助，请使用 GitHub Discussions 或联系维护者。 ### 第一次狩猎清单（在总体方案存在之后） 1. 打开 GitHub Issues 并选择 **New Threat Hunt**。 2. 填写所需的元数据（狩猎类型、MITRE ID、数据源/位置、查询语言、结果）。 3. 设置 **`campaign_slugs: ["your-campaign-slug"]`**（或使用匹配的 kebab-case `campaigns` 条目），以便将狩猎归入该活动下。 4. 将 `templates/hunt-template.md` 复制到 `hunts/.md` 中，并完成 PEAK 和至少一个 `threat-hunt-query` 块。 5. 审查后，从您生成/工作的分支开启一个到 `main` 的 PR；如果缺少必填字段或未知的 `campaign_slug` 引用，验证将失败。 6. 合并后，指标作业将重新生成仪表板并更新链接的活动部分。 ## 提交新狩猎（通过 Issues） 1. 在 GitHub Issues 中打开 **New Hunt** 问题表单。 2. 完成所有必填字段（假设、数据源、ATT&CK 映射、影响和所有者）。 3. 提交问题以进行分类和分配。 4. 使用 `templates/hunt-template.md` 将批准的问题转换为狩猎工件。 5. 审查生成或工作的分支，然后开启一个包含狩猎内容和支持逻辑/查询的拉取请求。 ### 狩猎提交期望 - 保持假设的可测试性和范围明确。 - 包含确切的遥测依赖项和数据盲区。 - 在适用时映射到 ATT&CK 技术。 - 记录如果狩猎触发时分析师应采取的预期行动。 - 捕获结果质量（真阳性、良性、无定论等）。 ## 自动仪表板如何工作 仪表板流水线旨在根据仓库活动不断总结狩猎项目的健康状况。 在宏观层面上： 1. 从 `hunts/` 和 `campaigns/` Markdown frontmatter 中读取狩猎和活动元数据。 2. `scripts/metrics/parse_hunts.py` 验证工件，通过 `campaign_slug` 将狩猎链接到活动，并刷新活动文件内的自动生成部分。 3. `.github/workflows/hunt-metrics.yml` 中的工作流在拉取请求（验证）和合并到 `main` 之后（重新生成 + 提交）运行。 4. `scripts/metrics/generate_dashboard.py` 发布 `docs/dashboard.md`（狩猎指标以及 **Active Campaigns** 汇总）。 常见指标包括： - 已提交、已批准和已完成的狩猎 - 按类型、ATT&CK 战术/技术和严重程度划分的狩猎 - 从提交到完成的平均时间 - 随时间推移的覆盖率和检测盲区趋势 ## 仪表板预览 `docs/dashboard.md` 中生成的仪表板是 Markdown 优先、对私有仓库友好且由 Mermaid 驱动的。 ### 示例视觉风格（Mermaid 预览） ``` pie showData title Hunt Types Distribution "Hypothesis-driven" : 7 "Baseline/EDA" : 3 "Model-Assisted/M-ATH" : 2 ``` ``` xychart-beta title "MITRE Known Tactic Coverage (%)" x-axis ["covered_known_tactics_%", "uncovered_%"] y-axis "Count" 0 --> 100 bar [64, 36] ``` ### 截图占位符 在您的第一次仪表板运行生成后，在此处添加截图：   ## 离线/私有化设计 + 可扩展性 - **无需外部 API**：指标和仪表板生成仅使用本地 Markdown + YAML 解析。 - **对私有仓库友好**：工作流在仓库内容上操作，无需调用第三方 SaaS。 - **确定性输出**：受控词汇字段减少了报告差异并提高了可重复性。 - **可扩展架构**：解析器和仪表板脚本是模块化的，因此可以在可选工作流之后添加未来的 AI 辅助丰富功能。 - **未来 AI 就绪**：`suggest-hunt-ideas.yml` 目前仅包含提示（无 API 调用），以后可升级为可选的提供商支持的运行。 ## 致谢与归属 本项目建立在成熟的社区和行业框架之上。在此致谢： - **PEAK 威胁狩猎框架**（`Prepare`、`Execute`、`Act with Knowledge`）和 **ABLE**（`Actor`、`Behavior`、`Location`、`Evidence`）归功于 **Splunk SURGe** 及相关的 Splunk Security 研究/出版物。 - **MITRE ATT&CK** 战术/技术分类法由 **MITRE** 创建和维护；本仓库使用 ATT&CK ID 进行标准化报告和分析。 - Markdown 仪表板渲染模式使用 **Mermaid** 语法和 GitHub 原生的 Markdown 功能。 主要参考资料： - [介绍 PEAK 威胁狩猎框架](https://www.splunk.com/en_us/blog/security/peak-threat-hunting-framework.html) - [使用 PEAK 框架进行假设驱动的狩猎](https://www.splunk.com/en_us/blog/security/peak-hypothesis-driven-threat-hunting.html) - [MITRE ATT&CK](https://attack.mitre.org/) - [Mermaid](https://mermaid.js.org/) ## 贡献模型 - 使用 issues 进行狩猎收集和讨论。 - 使用拉取请求进行所有狩猎内容的更改。 - 请求代码所有者进行审查，以确保质量和一致性。 - 保持狩猎工件简洁、可测试和可重用。 随着项目的成熟，请参阅 `CONTRIBUTING.md` 了解贡献约定。 ## 路线图 - 敲定问题模板字段和验证规则 - 实现指标脚本和输出 schema - 发布初始仪表板和趋势视图 - 添加用于狩猎工件质量和元数据完整性的 CI 检查

标签：GitHub Actions, PEAK模型, SecOps, Threat-Hunting-As-Code, 云安全架构, 假设驱动, 元数据管理, 响应行动, 基线检测, 威胁狩猎即代码, 安全可观测性, 安全团队协作, 安全工程, 安全度量, 安全运营, 工作流自动化, 异常检测, 情报驱动, 扫描框架, 指标分析, 检测差距, 版本控制, 知识共享, 网络安全, 自动化狩猎, 自动笔记, 逆向工具, 防御加固, 防御验证, 隐私保护