VulnHunter完全指南:Agentic AI安全扫描器如何像攻击者一样狩猎漏洞并用PoC证明
VulnHunter完全指南:Agentic AI安全扫描器如何像攻击者一样狩猎漏洞并用PoC证明
VulnHunter 是一款开源的 Agentic AI 安全扫描器,它不走传统 SAST 工具的"模式匹配"老路,而是像真实攻击者一样进行攻击者视角的前向分析——从入口点追踪数据流到危险汇聚点,识别哪些缺陷真正可利用,并用可执行的 PoC(Proof of Concept,概念验证)来证明每个漏洞,最后以测试驱动的方式修复它。本项目是 Capital One VulnHunter 的维护分支,核心改进是任意 Agent 框架可移植(harness portability)、容器化沙箱漏洞验证和可量化影响的 PoC。
⚠️ 双重用途提醒:VulnHunter 执行的是漏洞发现与利用这类双重用途工作。请只审计你拥有或明确获得授权的代码库,大多数商用模型对此类行为设有安全防护。
为什么 VulnHunter 不一样:从"报警"到"证明"
传统静态扫描器采用 sink-first(汇聚点优先) 分析:先找危险 API 调用,再反向猜测攻击路径,结果往往是满屏误报。VulnHunter 把这个模型彻底反转:
| 能力 | 传统 SAST 扫描器 | VulnHunter |
|---|---|---|
| 分析方向 | sink-first,反向猜测攻击者 | attacker-first,从攻击者可触达入口(API、网络消息、文件上传)正向推理能否真正突破 |
| 误报控制 | 大量可疑模式告警 | Falsification Engine(证伪引擎):专门设计一套流程来推翻自己的结论,寻找逻辑漏洞或会阻断攻击的安全控制,约 55% 的候选漏洞在到达你之前被排除或降级 |
| 结论标准 | "疑似漏洞" | PoC or It Didn't Happen:每个确认的漏洞必须附带 PoC(理想情况是实际执行过,且影响是测量出来的——泄露多少行数据、请求放大多少倍——而不是"讲述"出来的) |
| 修复建议 | 泛泛的加固建议 | 映射精确利用路径 + 结构性缺陷说明 + 针对性代码修改,修复要消除漏洞类别而不仅仅是封掉这个 PoC 载荷 |
🎯 一句话总结项目哲学:"Others scan. VulnHunter litigates."(别人只是扫描,VulnHunter 是举证。)
核心工作流:Hunt → Fix → Verify 三大技能闭环
VulnHunter 以三个可组合的 Agent 技能(skill)交付,形成完整的自动化"狩猎 → 修复 → 验证"闭环:
| 技能 | 阶段 | 核心职责 | 入口文件 |
|---|---|---|---|
/vulnhunt |
🕵️ Hunt(狩猎) | 把入口点映射到危险汇聚点,经过多阶段证伪流水线(Recon → 并行 Hunt → 对抗性证伪 → 能力过滤),只输出带可执行利用测试和修复建议的已验证问题 | vulnhunt/SKILL.md |
/vulnhunter-fix |
🔧 Fix(修复) | 开发者主导、测试驱动(TDD)的修复:先写利用演示,写一个失败的安全测试(RED),实现修复(GREEN),验证利用被阻断且无回归,最后交付可审查的 PR | vulnhunter-fix/README.md |
/vulnhunt-fix-verify |
✅ Verify(验证) | 一个完全独立、只读的 Agent(无 shell、无网络),独立验证漏洞是否真的被修复,输出逐条裁决,"修复是被证明的,而不是被信任的" | vulnhunt-fix-verify/SKILL.md |
💡 命名说明:套件叫 VulnHunter,但核心扫描命令是
/vulnhunt(验证器是/vulnhunt-fix-verify)——更短的形式是有意为之,不是拼写错误。
狩猎阶段(Hunt)的内部编排
核心扫描器 vulnhunt/ 是纯提示词技能(SKILL.md + phases/ 目录,无 Python 依赖)。SKILL.md 是编排器,自己不做安全分析,而是为每个阶段派发子代理(subagent):
| 阶段 | 文件 | 职责 |
|---|---|---|
| 1 · Recon | phases/phase1_recon.md | 建立攻击者可控输入清单,划分代码分区,标注生产可达性 |
| 2 · Hunt | phases/phase2_hunt.md | 三类并行代理(注入 / 导航与访问 / 逻辑与加密)按分区追踪输入到汇聚点 |
| 2b · Verify | phases/phase2b_verify.md | 对抗性证伪:尝试推翻每个候选,约一半在此被排除 |
| 3 · PoC & Impact | phases/phase3a_build_poc.md | 构建可工作的 PoC、测量影响、撰写修复策略 |
| 3d · Sweep | phases/phase3d_sweep.md | 在全代码库中 Grep 所有已确认的根因模式,防止漏网 |
| 4 · Report | phases/phase4_report.md | 编排器汇编最终报告 |
扫描产物统一写入 *_VULNHUNT_RESULTS_* 目录(报告 README.md、可执行 PoC、利用测试),且扫描器从不修改目标代码库——修复策略只记录、不落地。
一键安装步骤:5 分钟跑起 Agentic AI 安全扫描
前提条件
- 一个 Agent 框架(如 Claude Code、Codex 或类似工具),接入一个强推理能力模型(推荐开源权重模型)。模型访问由你自备——技能是纯提示词文件,不绑定特定厂商;
- Python 3.12+(仅 headless 运行时和基准测试需要);
- 确认你只扫描有授权分析的代码库。
安装命令
# 克隆仓库
git clone https://gitcode.com/gh_mirrors/vul/VulnHunter
cd VulnHunter
# 安装脚本不做任何猜测:缺失目录时会明确报错并给出精确指令
./install.sh
# Windows 下使用 .cmd 等价命令
# .\install.cmd
这个分支的**"零猜测"安装器是一个亮点:上游版本会无条件把技能复制进 ~/.claude/skills,在双框架机器上会静默装错位置;而这里的安装器通过环境变量显式指定目录,配置错误时大声失败**而不是静默装错:
VULNHUNT_SKILLS_DIR="$GROK_HOME/skills" \
VULNHUNT_AGENTS_DIR="$GROK_HOME/agents" \
./install.sh
安装脚本还会写入 vh 启动器到 VULNHUNT_BIN_DIR 或 ~/.local/bin(确保该目录在 PATH 中)。注意技能是直接复制而非符号链接(符号链接会破坏子代理内的 find/glob),更新后重新运行一次安装脚本即可刷新。
快速上手:运行你的第一次漏洞狩猎
1. 启动扫描器
在你的 Agent 框架会话中(建议用宿主最强大的推理模型),直接输入:
/vulnhunt
交互式调用时,技能会先做能力检查:如果发现当前模型不是宿主最强的推理模型,会先提醒你切换——因为证伪纪律依赖强推理。随后你可以选择两种模式:
| 模式 | 行为 | 适用场景 |
|---|---|---|
| Read-only(只读) | 静态分析,利用测试只写不跑 | 任何目标,最安全,默认推荐 |
| Bash-enabled | 安装依赖并实际运行利用测试 | 仅可信代码(会执行 npm install、pip install 等) |
2. 运行修复器
修复技能需要 git、已认证的 GitHub CLI(gh),以及安装 Python 辅助包(在 vulnhunter-fix/ 目录下执行 pip install -e ".[dev]")。然后输入 /vulnhunter-fix,它会在每个阶段边界暂停等待你批准,绝不擅自合并。
3. 运行修复验证器
验证器以严格只读、紧工具包(Read/Write/Edit/Glob/Grep/subagent,无 shell 执行、无网络)运行:
/vulnhunt-fix-verify repo=<绝对路径> report=<绝对路径> fixed=VULN-001,... out=<绝对路径>
自动化与规模化:让 AI 安全扫描跑在 CI 里
单次交互扫描之后,真正的价值在于无人值守的持续审计。项目为此提供了三层自动化:
Headless 运行时(vulnhunter-agent)
vulnhunter-agent/ 把扫描器包装成无交互工作流:克隆目标 → 执行 /vulnhunt → 发布结果 → 为每个确认漏洞在 GitHub 上开 issue。所有主机、凭据、路径都来自 TOML 配置或 VULNHUNT_* 环境变量,同一镜像可跨环境运行:
cd vulnhunter-agent
python -m pip install -e ".[dev]"
cp agent/config.example.toml agent/config.toml
python -m agent https://github.com/your-org/your-service --no-publish --no-issues
批量扫描与基准测试(harness)
harness/ 提供工作站规模的开发工具:在 harness/local_harness/batch/REPO_LIST.txt 中维护目标列表(每行一个仓库 URL),然后:
python -m local_harness.batch.run scan # 克隆并扫描列表中的每个仓库
python -m local_harness.batch.run scan --resume # 跳过已处理的仓库
python -m local_harness.batch.run status # 监控进度
python -m local_harness.batch.run collect # 汇集所有发现
基准测试模式(Clone → Scan → LLM-Judge → Tally)可对照已知漏洞语料库测量检测准确率,状态每步持久化、完全可续跑。
操作员 CLI(vh)
vh/ 是确定性的、不依赖模型的单次扫描伴侣:
vh clone <url> --dest <dir> # 浅克隆目标
vh find-results <checkout> # 定位结果目录
vh write-manifest <results-dir> --exit-code 4 # 写入并校验扫描清单
vh validate-manifest <results-dir> # 对照 schema 校验
配套的 vulnhunter-run/SKILL.md 是一个"操作员"技能:克隆 → 狩猎 → 定位结果 → 写清单,带明确的停止规则——某步失败就停下报告,绝不临场发挥。
关键数据:用数字回答"AI 扫安全靠不靠谱"
项目对同一生产 Go 服务的同一提交跑了 6 次完整扫描(5 种框架/模型组合),这些数字正是这个 fork 存在的原因:
| 指标 | 数字 | 含义 |
|---|---|---|
| 14× | 同一提交不同运行的确认漏洞数差异 | 自我度量流程本身就是第一个"漏洞"——弥合这个差距就是本分支的建设计划 |
| 42/42 | 确认漏洞全部附带可执行利用测试 | 每一个 PASS、每一个都有独立 PoC,"没有凭直觉交付的漏洞" |
| 55% | 候选漏洞在对抗性证伪环节被排除或降级 | 到你手里的才是高优先级、可操作的问题 |
| 315 | 单次扫描清点出的攻击者可控输入 | 每一个都被追踪、每一条处置都被记录——完整性是纪律,不是愿望 |
| 20/20 | 单轮对真实服务器执行的对抗载荷 | 影响是测量出来的,不是断言出来的 |
项目结构速览
| 路径 | 说明 |
|---|---|
| vulnhunt/ | 核心 /vulnhunt 扫描器技能(纯提示词:SKILL.md + phases) |
| vulnhunter-fix/ | /vulnhunter-fix 技能及配套 Python 辅助包、测试 |
| vulnhunt-fix-verify/ | /vulnhunt-fix-verify 独立验证技能(纯提示词) |
| vulnhunter-agent/ | 配置驱动的 headless 运行时,跑扫描并开 GitHub issue |
| harness/ | 批量扫描与基准测试工具(仅开发用) |
| vh/ | 确定性操作员 CLI:克隆、定位结果、写/校验扫描清单 |
| vulnhunter-run/ | 无人值守操作员技能 |
更多细节见 CONTRIBUTING.md 与 SECURITY.md。
常见问题 FAQ
Q1:必须用 Claude 吗?
不用。这正是这个 fork 的核心改进——技能是纯提示词文件,通过 VULNHUNT_SKILLS_DIR、VULNHUNT_MODEL 等环境变量契约接入任意有技能目录 + 子代理能力的 Agent 框架,并要求"你的框架中最强的推理模型"。只有 headless 运行时和 harness 仍基于 Claude Code。
Q2:扫描会改动我的代码吗? 不会。扫描器默认对目标检出只读,修复策略只记录不落地。
Q3:需要联网或联网调用 API 吗? 核心扫描技能本身无 Python、无网络依赖;模型访问由你的框架提供(自备密钥)。
Q4:开源协议是什么? Apache License 2.0,见 LICENSE。
写在最后
VulnHunter 代表 AI 安全工具的一个重要转向:从"发现可疑模式"到"证明漏洞可利用"。攻击者视角的前向分析、对抗性证伪流水线、强制 PoC 纪律,再加上 Hunt → Fix → Verify 的完整闭环和无人值守自动化,让它从"演示工具"变成了"可以排进每晚定时的审计能力"。如果你想在 CI 里为仓库加上持续安全审计,可以从安装一节开始,5 分钟跑起第一次狩猎。