VulnHunter完全指南:Agentic AI安全扫描器如何像攻击者一样狩猎漏洞并用PoC证明

原创2026-10-26 09:34:401,915 阅读

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 分钟跑起第一次狩猎。

登录后查看全文
VulnHunter