capitalone/VulnHunter
GitHub: capitalone/VulnHunter
VulnHunter 是一款基于 Claude Opus 的智能体 AI 源码安全工具，通过攻击者优先的正向推理和证伪引擎实现低误报率的自动化漏洞发现与修复闭环。
Stars: 603 | Forks: 76
# VulnHunter
VulnHunter 是一款开源的**智能体 AI 安全工具**，可将主动式、攻击者优先的分析直接应用于源代码。
与传统的被动式 SAST 扫描器不同，后者通常只是标记可疑模式并经常导致误报，而 VulnHunter 能够像对手一样进行推理。它会**识别**出哪些缺陷是真正可被利用的，规划出潜在的攻击路径，并提出有针对性的、有证据支持的修复方案。
现代软件供应链相互之间的关联极其紧密。在一个被广泛使用的开源组件中，单个漏洞可能会同时波及成千上万家企业。
VulnHunter 在 Capital One 内部开发，现已向社区发布，因为没有任何一家组织能够单独解决这一挑战.
## 为什么 VulnHunter 与众不同
* **攻击者优先的正向分析：** 传统工具通常采用“汇聚点优先”分析，即查看潜在的危险代码模式并向后搜索假想的攻击者，从而使团队陷入大量误报。VulnHunter 颠覆了这一模型，模拟恶意行为者的确切路径。它从潜在的攻击者可访问的入口点（API、网络消息、文件上传）开始，并*向前*推理以评估攻击者是否能够真正实现突破。
* **证伪引擎：** 在发现潜在漏洞后，VulnHunter 会运行专门设计用于*反驳*自身结论的结构化推理工作流。它会寻找有缺陷的假设、逻辑漏洞或可能阻断攻击的安全控制措施。它被设计为会立即丢弃那些依赖于无根据假设的发现。最终呈现给您的是高优先级、可操作的缺陷。
* **有证据支持的修复方案：** 当某个缺陷通过了证伪引擎的检验后，VulnHunter 会规划出确切的利用路径，解释结构性缺陷，详细说明攻击者将获得的具体能力或访问权限，并生成专一的、有针对性的代码更改以供审查。
## 闭环：追踪 → 修复 → 验证
VulnHunter 作为三个可组合的 [Claude Code](https://docs.claude.com/en/docs/claude-code) 技能发布，它们共同构成了一个完整的自动化修复闭环：
| 技能 | 阶段 | 核心职责 |
| :--- | :--- | :--- |
| **`/vulnhunt`** | **追踪** | 将入口点映射到危险的汇聚点。通过多阶段证伪流水线（侦察 → 并行追踪 → 对抗性证伪 → 能力过滤器）筛选发现结果。仅输出带有可执行漏洞利用和拟定修复方案且经验证的问题。 |
| **`/vulnhunter-fix`** | **修复** | 由开发者主导、测试驱动的修复过程。它会编写漏洞利用演示，创建失败的安全测试 (**RED**)，实现代码修复 (**GREEN**)，验证漏洞利用已被阻断且未产生回归问题，并提交可供审查的 PR。 |
| **`/vulnhunt-fix-verify`** | **验证** | 一个完全独立的只读 agent，用于独立验证某个发现是否已被成功修复。它会针对每个发现输出裁决结果，从而证明修复的有效性，而不是仅凭盲目信任。 |
## 仓库结构
每个组件都被组织成一个独立的子树：
| 路径 | 描述 |
| :--- | :--- |
| `vulnhunt/` | 核心的 `/vulnhunt` 扫描技能（仅包含 Prompt：`SKILL.md` + 各个阶段）。请参阅 [`vulnhunt/README.md`](vulnhunt/README.md)。 |
| `vulnhunter-fix/` | `/vulnhunter-fix` 技能、其配套的 Python 辅助包以及测试。请参阅 [`vulnhunter-fix/README.md`](vulnhunter-fix/README.md)。 |
| `vulnhunt-fix-verify/` | 独立的 `/vulnhunt-fix-verify` 验证技能（仅包含 Prompt）。请参阅 [`vulnhunt-fix-verify/README.md`](vulnhunt-fix-verify/README.md)。 |
| `vulnhunter-agent/` | 配置驱动的无头运行时封装器，用于运行扫描并提交 GitHub issue。请参阅 [`vulnhunter-agent/README.md`](vulnhunter-agent/README.md)。 |
| `harness/` | 用于运行大规模批量扫描和对检测准确率进行基准测试的开发者工具。请参阅 [`harness/README.md`](harness/README.md)。 |
## 要求与设置
### 前置条件
* [Claude Code CLI](https://docs.claude.com/en/docs/claude-code)，已完成身份验证并可访问 **Claude Opus**。
* Python 3.12+（仅运行时 agent 和基准测试工具需要）。
* *责任检查：* 确保您仅扫描已获得明确授权进行分析的代码库。
### 安装
```
# Clone 仓库
git clone https://github.com/capitalone/vulnhunter.git
cd vulnhunter
# 将 skills 复制到 ~/.claude/skills/
./install.sh
# （可选）清理或移除已安装的 skills
# ./uninstall.sh
```
## 使用指南
### 1. 运行扫描器
```
claude --model opus --add-dir ~/.claude/skills/vulnhunt --add-dir ~/.claude/skills/vulnhunt/phases
# 在 Claude Code 会话内，调用：
/vulnhunt
```
### 2. 运行修复器
修复器需要 `git`、已对目标仓库完成身份验证的 GitHub CLI (`gh`)，并需安装其 Python 辅助工具（在 `vulnhunter-fix/` 目录下执行 `pip install -e ".[dev]"`）。
```
claude --model opus --add-dir ~/.claude/skills/vulnhunter-fix
# 在 Claude Code 会话内，调用：
/vulnhunter-fix
```
*有关高级操作模式和配置设置，请参阅 [`vulnhunter-fix/README.md`](vulnhunter-fix/README.md)。*
### 3. 运行修复验证器
验证器在严格的工具限制范围内（读/写/编辑/Glob/Grep/Agent——**不执行 Bash，无网络访问**），对受信任的根目录严格进行只读操作。调用者必须预先创建输出 (`out`) 目录。
```
claude --model opus --add-dir ~/.claude/skills/vulnhunt-fix-verify \
--add-dir ~/.claude/skills/vulnhunt-fix-verify/phases
# 在 Claude Code 会话内，调用：
/vulnhunt-fix-verify repo= report= fixed=VULN-001,... out= [comments=] [additional_repos=,]
```
## 自动化与规模化
### 无头运行时 Agent (`vulnhunter-agent/`)
对于非交互式或 CI/CD 流水线，`vulnhunter-agent/` 将扫描器封装成一个无头工作流。它会克隆目标，执行 `/vulnhunt`，发布结果，并为已确认的 bug 创建 GitHub issue。它通过 Anthropic API 进行原生连接。
请查阅 [`vulnhunter-agent/README.md`](vulnhunter-agent/README.md) 获取部署蓝图。
### 本地测试框架 (`harness/`)
`harness/` 目录提供了工作站级别的开发者工具。要进行初始化，请运行 `cd harness && pip install -e ".[dev]"`。
#### 批量扫描
在 `harness/local_harness/batch/REPO_LIST.txt` 中管理您的目标列表（每行一个 GitHub URL，以 `#` 开头的行将被忽略）：
```
cd harness
python -m local_harness.batch.run scan # Clone and scan every repo in the list
python -m local_harness.batch.run scan --resume # Skip repositories already processed
python -m local_harness.batch.run status # Monitor progress across your batch
python -m local_harness.batch.run collect # Gather all findings for centralized review
```
#### 基准测试模式
针对已知存在漏洞的漏洞语料库评估扫描器的准确率（克隆 → 扫描 → LLM 评判 → 统计指标）：
```
python -m local_harness.benchmark.run # Execute full benchmark run
python -m local_harness.benchmark.run --repos "name" # Benchmark a single target repository
python -m local_harness.benchmark.run --tally-only # Re-generate the analytical report only
```
## 运行测试
每个 Python 组件都维护着自己独立的测试套件。请使用 `pytest` 运行它们：
```
cd harness && pip install -e ".[dev]" && python -m pytest tests/ --cov=local_harness
cd vulnhunter-fix && pip install -e ".[dev]" && python -m pytest -q
cd vulnhunter-agent && pip install -e ".[dev]" && python -m pytest -q
```
## 贡献、安全与许可
* **关于模型的说明：** VulnHunter 是针对 **Claude Opus** 和 **Claude Code** 进行了精准调优的。其低误报的原则严重依赖前沿级别的推理能力，尽管底层的编排模式也可以适配其他高级基础模型。
* **贡献：** 请参阅 [CONTRIBUTING.md](CONTRIBUTING.md) 以提出核心框架改进、Prompt 更新或更广泛的模型支持配置建议。
* **安全：** 请查阅 [SECURITY.md](SECURITY.md) 了解如何安全地报告在 VulnHunter 本身中发现的的安全漏洞。
* **许可：** 在 Apache License, Version 2.0 条款下分发。详情请参阅 [LICENSE](LICENSE)。
标签：人工智能, 代码安全, 安全规则引擎, 漏洞枚举, 用户模式Hook绕过, 自动化安全审计, 逆向工具, 静态应用安全测试