nebulock-inc/agentic-threat-hunting-frameworkATHF是一个用于自主威胁狩猎的框架——构建能够记忆、学习并以更高自主性行动的系统。
# 智能体威胁狩猎框架（ATHF）
[](https://pypi.org/project/agentic-threat-hunting-framework/)
[](https://pypi.org/project/agentic-threat-hunting-framework/)
[](https://www.python.org/downloads/)
[](https://github.com/Nebulock-Inc/agentic-threat-hunting-framework/blob/main/LICENSE)
[](https://github.com/Nebulock-Inc/agentic-threat-hunting-framework/stargazers)
**[快速开始](#-quick-start)** • **[安装](#installation)** • **[文档](#documentation)** • **[示例](https://github.com/Nebulock-Inc/agentic-threat-hunting-framework/blob/main/SHOWCASE.md)**
*为你的威胁狩猎项目赋予记忆与自主能力。*
**智能体威胁狩猎框架（ATHF）** 是你的威胁狩猎项目的记忆与自动化层。它为你的狩猎提供结构、持久性和上下文——让每一次过往调查都能被人类和 AI 访问。
ATHF 可与任何狩猎方法论配合使用（PEAK、TaHiTI 或你自己的流程）。它不是替代品；它是让你的现有流程具备 AI 就绪能力的层。
## 什么是 ATHF？
ATHF 为威胁狩猎项目提供结构和持久性。它是一个基于 Markdown 的框架，能够：
- 使用 LOCK 模式（Learn → Observe → Check → Keep）记录狩猎过程
- 维护一个可搜索的过往调查仓库
- 使 AI 助手能够引用你的环境和先前工作
- 与任何 SIEM/EDR 平台配合使用
- **新增：** 包含 AI 驱动的研究和假设生成智能体（v0.3.0+）
## 问题所在
大多数威胁狩猎项目在狩猎结束后会丢失宝贵的上下文。笔记散落在 Slack 或工单中，查询写一次就被遗忘，经验教训只存在于分析师的头脑中。
即使是 AI 工具，每次也都从零开始，无法访问你的环境、数据或过往狩猎记录。
ATHF 通过为你的狩猎提供结构、持久性和上下文来改变这一现状。
**阅读更多：** [docs/why-athf.md](https://github.com/Nebulock-Inc/agentic-threat-hunting-framework/blob/main/docs/why-athf.md)
## LOCK 模式
每一次威胁狩猎都遵循相同的基本循环：**Learn → Observe → Check → Keep**。
- **Learn（学习）：** 从威胁情报、告警或异常中收集上下文
- **Observe（观察）：** 形成关于对手行为的假设
- **Check（检查）：** 使用针对性查询检验假设
- **Keep（保留）：** 记录发现和经验教训
**为什么是 LOCK？** 它足够小以便使用，又足够严格以便智能体解读。通过以这种格式记录每一次狩猎，ATHF 使 AI 助手能够回忆先前工作，并基于过往结果建议改进的查询。
**阅读更多：** [docs/lock-pattern.md](https://github.com/Nebulock-Inc/agentic-threat-hunting-framework/blob/main/docs/lock-pattern.md)
## GATES 方法：狩猎到检测的晋升验证
在完成狩猎的 **KEEP** 阶段后，**GATES 方法** 会验证你的发现是否应晋升为生产检测、周期性狩猎或公告。
**G**eneralizable（可泛化）、**A**dditive（可叠加）、**T**unable（可调优）、**E**xposure-tested（经暴露测试）、**S**ustainable（可持续）
> **注意：** GATES 设计为与 ATHF 框架配合使用，并已在该上下文中经过广泛测试。虽然该方法论（5 项 BASE 标准、判定类型）在概念上可移植，但我们建议将其作为完整 ATHF 工作流的一部分使用以获得最佳效果。完整集成请参见 `.claude/skills/gates/`。
> **安装：** GATES 目前仅可通过 `git clone` 获取。通过 `pip install` 安装的用户应克隆仓库以访问 GATES。我们正在努力将 GATES 纳入 pip 发行版（跟踪为 Issue #21）。
GATES 使用两层框架评估源自狩猎的检测：5 项 BASE 标准（从狩猎数据评估）识别部署候选，而 5 项 ADVANCED 标准（在生产中验证）确保 **具有低误报率和低漏报率的弹性检测**：
| 关卡 | 问题 | 捕获内容 |
|------|----------|---------|
| **G** - 可泛化 | 这是可重复的吗？ | 快速失效的基于 IOC 的规则 |
| **A** - 可叠加 | 它是否填补了覆盖缺口？ | 重复或冗余的检测 |
| **T** - 可调优 | 我们能区分攻击与正常吗？ | 基线噪声不匹配（误报的首要原因） |
| **E** - 经暴露测试 | 我们覆盖了规避手段吗？ | 单维度检测 |
| **S** - 可持续 | 我们能维护它吗？ | 高量、低真阳性的规则 |
判定基于 BASE 分数（/5）。ADVANCED 验证方法请参见 `.claude/skills/gates/`。
**快速开始** — 向你的助手输入以下内容；`/gates` 是一项技能，而非 shell 命令：
```text
/gates --hunt H-0001
```
**判定类型：**
- ✅ **PROMOTE**（4.0-5.0）- 部署为常驻检测
- ⚠️ **CONDITIONAL**（3.0-3.9）- 满足前提条件后部署
- ❌ **HOLD**（0.0-2.9）- 保留逻辑，不部署
- ⏱️ **TIME_BOX** - 针对特定战役，90 天刷新
- 🔄 **RECURRING_HUNT** - 每季度执行，而非 24/7
- 🚫 **DROP** - 不值得检测；记录在案以免被重新提议
**门禁 FAIL 会覆盖评分区间**，当两个门禁失败时，按以下顺序首个匹配者胜出：A→DROP，G→TIME_BOX，E→HOLD，S→RECURRING_HUNT，T→CONDITIONAL。上述区间仅在无门禁 FAIL 时适用。完整规则：
`.claude/skills/gates/SKILL.md` 第 4 步。
**注意：** GATES 的 "PROMOTE" 判定意味着部署检测规则。这与 `athf hunt promote` 不同，后者在目录之间移动 hunt 文件。
**与 ADEF（检测工程框架）的集成：**
在 GATES 验证之后，继续进行 ADEF 以进行生产检测工程：
```
ATHF Workspace ADEF Workspace
────────────── ──────────────
Hunt (LOCK)
↓
GATES Validate
↓
H-XXXX_GATES.yaml ────────────→ FORGE (F-O-R-G-E)
↓
Production Rule
```
**完整工作流程：**
1. 在 ATHF 工作区中，验证狩猎——助手输入，而非 shell 命令：
```text
/gates --hunt H-0903
```
→ 写入 `hunt-promotion-analysis/H-0903_GATES.yaml`（每个 hunt 一个文件，内部包含 N
个候选）。判定为归档（`HOLD`、`DROP`、`TIME_BOX`、
`RECURRING_HUNT`）的 hunt 则改为输出一个 `.md` 叙述文件——因为没有规则需要构建，
所以第 2 步仅适用于 `.yaml` 输出。
2. 将该文档导入 ADEF：
```bash
adef hunt-promote --gates ~/athf-workspace/hunt-promotion-analysis/H-0903_GATES.yaml
# --dry-run first to preview what it would mint
```
可部署的候选对象各自以 `D-XXXX`、一条目录记录和一份日志进入 Find 阶段；归档对象则报告为已跳过。无需 `cd` —— ADEF 从 `ADEF_WORKSPACE` 解析其工作区（默认 `~/work/adef-workspace/`）。使用 `adef hunt-promote --help` 确认你的 ADEF 具有此模式。
**ADEF 仓库：** https://github.com/Nebulock-Inc/agentic-detection-engineering-framework
GATES 确保你以正确的方式部署正确的检测规则，避免告警疲劳和运营摩擦。
**阅读更多：** [.claude/skills/gates/README.md](https://github.com/Nebulock-Inc/agentic-threat-hunting-framework/blob/main/.claude/skills/gates/README.md)
## 智能体狩猎的五个级别
ATHF 定义了一个简单的成熟度模型。每个级别都建立在前一个级别之上。
**大多数团队将停留在级别 1–2。除此之外的一切都是可选的成熟度。**
| 级别 | 能力 | 你将获得 |
|-------|-----------|--------------|
| **0** | 临时性 | 狩猎存在于 Slack、工单或分析师笔记中 |
| **1** | 已记录 | 使用 LOCK 的持久化狩猎记录 |
| **2** | 可搜索 | AI 读取并回忆你的狩猎 |
| **3** | 生成式 | AI 通过 MCP 工具执行查询，开展研究 |
| **4** | 智能体式 | 自主智能体监控并行动，生成假设 |
**级别 1：** 一天内可投入运行
**级别 2：** 一周内可投入运行
**级别 3：** 2-4 周（可选）
**级别 4：** 1-3 个月（可选）
**阅读更多：** [docs/maturity-model.md](https://github.com/Nebulock-Inc/agentic-threat-hunting-framework/blob/main/docs/maturity-model.md)
## 🚀 快速开始
### 选项 1：从 PyPI 安装（推荐）
```bash
# Install ATHF
pip install agentic-threat-hunting-framework
# Initialize your hunt program
athf init
# NEW: Conduct research before hunting (5-skill methodology)
athf research new --topic "LSASS dumping" --technique T1003.001
# Create your first hunt (link to research)
athf hunt new --technique T1003.001 --title "LSASS Credential Dumping" --research R-0001
```
### 选项 2：从源码安装（开发）
```bash
# Clone and install from source
git clone https://github.com/Nebulock-Inc/agentic-threat-hunting-framework
cd agentic-threat-hunting-framework
pip install -e .
# Initialize and start hunting
athf init
athf hunt new --technique T1003.001
```
### 选项 3：纯 Markdown（无需安装）
```bash
# Clone the repository
git clone https://github.com/Nebulock-Inc/agentic-threat-hunting-framework
cd agentic-threat-hunting-framework
# Copy a template and start documenting
mkdir -p hunts
cp athf/data/templates/HUNT_LOCK.md hunts/H-0001.md
# Customize AGENTS.md with your environment
# Add your SIEM, EDR, and data sources
```
**选择你的 AI 助手：** Claude Code、GitHub Copilot 或 Cursor——任何能够读取你仓库文件的工具。
**完整指南：** [docs/getting-started.md](https://github.com/Nebulock-Inc/agentic-threat-hunting-framework/blob/main/docs/getting-started.md)
## 🔧 CLI 命令
ATHF 包含一个功能齐全的 CLI，用于管理你的狩猎。以下是快速参考：
### 初始化工作区
```bash
athf init # Interactive setup
athf init --non-interactive # Use defaults
```
### 研究与假设生成（v0.3.0 新增）
```bash
# Conduct thorough pre-hunt research (15-20 min)
athf research new --topic "LSASS dumping" --technique T1003.001
# Quick research for urgent hunts (5 min)
athf research new --topic "Pass-the-Hash" --depth basic
# Generate AI-powered hypothesis from threat intel
athf agent run hypothesis-generator --threat-intel "APT29 targeting SaaS"
# List research and agents
athf research list
athf agent list
```
### 创建狩猎
```bash
athf hunt new # Interactive mode
athf hunt new \
--technique T1003.001 \
--title "LSASS Dumping Detection" \
--platform windows \
--hunt-type baseline \
--research R-0001 # Link to research document
# --hunt-type: hypothesis (default) | baseline | model-assisted
```
### 列表与搜索
```bash
athf hunt list # Show all hunts
athf hunt list --status completed # Filter by status
athf hunt list --directory test # Filter by environment (test/production)
athf hunt list --hunt-type baseline # Filter by hunt category
athf hunt list --output json # JSON output
athf hunt search "kerberoasting" # Full-text search
athf hunt search "credential" --directory production # Search with directory filter
athf research search "credential" # Search research docs
```
### 验证与统计
```bash
athf hunt validate # Validate all hunts
athf hunt validate H-0001 # Validate specific hunt
athf hunt stats # Show statistics (incl. hunts by type)
athf hunt stats --by hunt_type --status completed --output json # Category breakdown
athf hunt coverage # MITRE ATT&CK coverage
athf research stats # Research metrics
```
检测质量由 GATES **skill** 评分，该 skill 由你的助手调用——
它不属于 `athf` CLI 的一部分，因此不应出现在上面的 shell 代码块中：
```text
/gates --hunt H-0001
```
### ATT&CK 数据管理（v0.11.0 新增）
```bash
# Install STIX support (optional)
pip install 'agentic-threat-hunting-framework[attack]'
# Download live ATT&CK data (835+ techniques with full metadata)
athf attack update
# Check provider status
athf attack status
# Look up technique metadata
athf attack lookup T1003.001
# List techniques for a tactic
athf attack techniques credential-access
```
如果没有 `mitreattack-python`，ATHF 会使用硬编码的 v14 回退方案（14 种战术，近似计数）。有了它，你就能获得完整的技术元数据：平台、数据源、子技术以及准确的计数。
### MCP 服务器（v0.11.0 新增）
```bash
# Install MCP dependencies
pip install 'agentic-threat-hunting-framework[mcp]'
# Start MCP server (for Claude Code, Copilot, Cursor, etc.)
athf mcp serve --workspace /path/to/hunts
```
在 `~/.claude/mcp-servers.json` 中配置：
```json
{
"athf": {
"command": "athf-mcp",
"env": { "ATHF_WORKSPACE": "/path/to/your/hunts" }
}
}
```
独立的 `athf-mcp` 入口点会根据 cwd 或 `ATHF_WORKSPACE` 环境变量自动检测你的工作区。使用 `athf mcp serve --workspace /path` 来指定显式路径。
> **安全提示：** `sse` 和 `streamable-http` 传输绑定到 `127.0.0.1`，并且**未经身份验证**。每个工具都会读取你的整个工作区，有些还会以你的费用调用 LLM 代理。只有在需要绑定可路由接口时才传入 `--host`，并且在这种情况下要在前面放置一个身份验证代理。默认的 `stdio` 传输完全不打开任何套接字。
暴露 17 个工具：狩猎管理、语义搜索、ATT&CK 覆盖、研究、调查以及 AI 驱动的假设生成——全部可直接从你的 AI 编码助手中访问。
**完整文档：** [CLI 参考](https://github.com/Nebulock-Inc/agentic-threat-hunting-framework/blob/main/docs/CLI_REFERENCE.md)
## 📺 实际效果
观看 ATHF 的实际运行：初始化工作区、创建狩猎，并在 60 秒内探索你的威胁狩猎目录。
**[查看示例狩猎 →](https://github.com/Nebulock-Inc/agentic-threat-hunting-framework/blob/main/SHOWCASE.md)**
## 安装
请参阅上方的[快速开始](#-quick-start)部分了解安装选项（PyPI、源码或纯 Markdown）。
**先决条件：**
- Python 3.11 或更高版本（用于 CLI 选项）
- 你最喜欢的 AI 编码助手
## 文档
### 核心概念
- [ATHF 为何存在](https://github.com/Nebulock-Inc/agentic-threat-hunting-framework/blob/main/docs/why-athf.md) - 问题与解决方案
- [LOCK 模式](https://github.com/Nebulock-Inc/agentic-threat-hunting-framework/blob/main/docs/lock-pattern.md) - 所有狩猎的结构
- [成熟度模型](https://github.com/Nebulock-Inc/agentic-threat-hunting-framework/blob/main/docs/maturity-model.md) - 五个级别的解释
- [入门指南](https://github.com/Nebulock-Inc/agentic-threat-hunting-framework/blob/main/docs/getting-started.md) - 分步入职指导
### 各级别指南
- [级别 1：已记录的狩猎](https://github.com/Nebulock-Inc/agentic-threat-hunting-framework/blob/main/docs/maturity-model.md#level-1-documented-hunts)
- [级别 2：可搜索的记忆](https://github.com/Nebulock-Inc/agentic-threat-hunting-framework/blob/main/docs/maturity-model.md#level-2-searchable-memory)
- [级别 3：生成能力](https://github.com/Nebulock-Inc/agentic-threat-hunting-framework/blob/main/docs/level4-agentic-workflows.md)
- [级别 4：代理工作流](https://github.com/Nebulock-Inc/agentic-threat-hunting-framework/blob/main/docs/level4-agentic-workflows.md)
### 集成与定制
- [安装与开发](https://github.com/Nebulock-Inc/agentic-threat-hunting-framework/blob/main/docs/INSTALL.md) - 设置、分支定制、测试
- [GATES 方法](https://github.com/nebulock-inc/agentic-threat-hunting-framework/blob/main/.claude/skills/gates/README.md) - 检测验证技能（连接 LOCK → ADEF）
- [MCP 目录](https://github.com/Nebulock-Inc/agentic-threat-hunting-framework/blob/main/integrations/MCP_CATALOG.md) - 可用的工具集成
- [快速开始指南](https://github.com/Nebulock-Inc/agentic-threat-hunting-framework/tree/main/integrations/quickstart/) - 特定工具的设置
- [使用 ATHF](https://github.com/Nebulock-Inc/agentic-threat-hunting-framework/blob/main/USING_ATHF.md) - 采用与定制
## 🎖️ 精选狩猎
### H-0001：macOS 信息窃取程序检测
检测到 Atomic Stealer 通过 AppleScript 收集 Safari cookie。
**结果：** 1 个真阳性，主机在数据外泄前被隔离。
**关键洞察：** 基于行为的检测优于基于签名的检测方法。进程签名验证识别出试图收集数据的未签名恶意软件。
[查看完整狩猎 →](https://github.com/Nebulock-Inc/agentic-threat-hunting-framework/blob/main/hunts/H-0001.md) | [查看更多示例 →](https://github.com/Nebulock-Inc/agentic-threat-hunting-framework/blob/main/SHOWCASE.md)
## 为何这很重要
你可能会想，这与 [PEAK](https://www.splunk.com/en_us/blog/security/peak-threat-hunting-framework.html) 等框架如何交互。PEAK 为你提供了如何进行狩猎的可靠方法。ATHF 在此基础上构建，为你提供结构、记忆和连续性。PEAK 指导工作。ATHF 确保你捕获工作、组织工作，并在未来的狩猎中复用。
代理式威胁狩猎不是要取代分析师。而是要构建能够：
- 记住以前做过什么的系统
- 从过去的成功和错误中学习
- 通过上下文回忆支持人类判断
当你的框架拥有记忆时，你就不会再因人员流动或被遗忘的笔记而丢失知识。当你的 AI 助手能够引用这些记忆时，它就会成为力量倍增器。
## 💬 社区与采用
- **GitHub 讨论：** [提问、分享狩猎](https://github.com/Nebulock-Inc/agentic-threat-hunting-framework/discussions)
- **问题反馈：** [报告错误或请求功能](https://github.com/Nebulock-Inc/agentic-threat-hunting-framework/issues)
- **LinkedIn：** [Nebulock Inc.](https://www.linkedin.com/company/nebulock-inc) - 关注以获取更新
**在你的组织中使用 ATHF：** ATHF 是一个需要内化的框架，而不是一个需要扩展的平台。分叉它、定制它、让它成为你自己的。请参阅 [USING_ATHF.md](https://github.com/Nebulock-Inc/agentic-threat-hunting-framework/blob/main/USING_ATHF.md) 获取采用指导。你的狩猎始终属于你——回馈分享是可选的，但值得赞赏。
**仓库：** [https://github.com/Nebulock-Inc/agentic-threat-hunting-framework](https://github.com/Nebulock-Inc/agentic-threat-hunting-framework)
目标是帮助每个威胁狩猎团队从临时的记忆转向结构化的、代理式的能力。
---
## 🛠️ 开发与定制
ATHF 旨在被分叉并针对你的组织进行定制。
**请参阅 [docs/INSTALL.md#development--customization](https://github.com/Nebulock-Inc/agentic-threat-hunting-framework/blob/main/docs/INSTALL.md#development--customization) 了解：**
- 为开发设置你的分叉
- 用于代码质量的预提交钩子
- 测试与类型检查
- 定制示例
- CI/CD 集成
快速开始：
```bash
pip install -e ".[dev]" # Install dev dependencies
pre-commit install # Set up quality checks
pytest tests/ -v # Run tests
```
---
## 👤 作者
由 **Sydney Marrone** 创建 © 2025
---
**从小处着手。记录一次狩猎。添加结构。构建记忆。**
记忆是倍增器。能动性是力量。
一旦你的程序能够记忆，一切皆有可能。
狩猎愉快！