
最近在研究 AI 辅助安全审计的工作流,发现一个热度很高的开源项目 Claude-BugHunter。它在 GitHub 上已经拿到 13.7k Star、1.7k Fork,定位非常明确:把 Claude Code 从一个通用聊天助手,改造成一台懂方法论、懂验证纪律、懂报告规范的 AI 安全研究工作台。本文完整记录它的安装与上手过程,包括插件安装、脚本安装、首次实战流程与常见问题排查。
下载地址(仓库完整源码打包快照,国内直连 GitHub 较慢,解压后按文中步骤安装即可):https://pan.quark.cn/s/eb56aad0cf9c
一、项目概览:83 个技能的 AI 安全工作台
Claude-BugHunter 是一个面向 Claude Code 技能体系的开源技能包,作者是 GenAI 安全研究者 Sachin Sharma。整个项目的数据相当扎实:
- 83 个技能(SKILL.md),按主题自动加载
- 15 个斜杠命令,覆盖侦察、验证、报告全流程
- 681 份 HackerOne 公开披露报告提炼出的模式库,其中 433 条做了可溯源引用
- 覆盖 24 类核心漏洞研究模式(XSS、SQL 注入、IDOR、SSRF、OAuth 等)
- 支持 5 种运行环境:Claude Code、OpenCode、OpenAI Codex CLI、Hermes Agent、Google AntiGravity
- 采用 MIT + CC BY 4.0 双许可,19 位贡献者,代码以 Python(87.1%)为主,另有 PowerShell 与 Shell

它还有一个姊妹项目 Claude-OSINT,负责情报侦察阶段;Claude-BugHunter 则接手后续的验证与报告环节。两者可以配合使用。
二、四层技能体系是怎么设计的
项目不是简单堆砌提示词,而是把安全研究的最佳实践拆成了四层,层层递进。
2.1 思维层:方法论先行
bb-methodology 与 redteam-mindset 两个技能负责"怎么想":五阶段非线性工作流、批判性思维框架、异常检测模式。这一层解决的是新手最常见的痛点——拿到目标不知道从哪里下手。
2.2 检测层:58 个 hunt-* 专项技能
这是项目的主体。每个漏洞类别对应一个技能文件夹,内置检测模式、测试载荷、绕过对照表和链式模板,全部来自 681 份真实披露报告。比如 hunt-xss(174 份报告支撑)、hunt-idor(26 份)、hunt-oauth(10 份)。技能内容本身是知识库,不调用任何外部服务。
2.3 平台层:企业级平台研究链路
针对 M365/Entra ID、Okta、VMware vCenter、主流 SSL VPN 设备、SharePoint、云 IAM 的 2024—2026 年 CVE 研究链路,附 AADSTS 错误码参考与版本指纹矩阵。这一层主要服务于授权范围内的企业环境评估。
2.4 交付层:验证门与报告规范
triage-validation 提供 7 问验证门,evidence-hygiene 负责 Cookie 打码、PII 黑条、HAR 脱敏,报告技能内置 HackerOne/Bugcrowd 等平台模板与 CVSS 评分参考。

三、两个关键机制:自动加载与 7 问验证门
3.1 技能自动触发,不用背命令
技能描述里埋了关键词,当你用自然语言描述任务时(比如"我在测试一个回显在 HTML 里的输入参数"),Claude Code 会自动加载对应的 hunt-xss 技能。不需要手动指定技能名,这是它比传统提示词集合好用得多的地方。
整个自动加载链路可以概括为下面这张图:

图中每个节点对应链路中的一步:用户自然语言描述任务是入口,你只需像平时说话一样讲清在测什么;提取任务中的类别关键词由 Claude Code 从描述里识别出 XSS、IDOR、SSRF 等类别信号;关键词匹配技能描述把信号与各 hunt-* 技能描述中预埋的关键词做比对,命中则自动加载对应 hunt-* 技能,未命中则回退到通用方法论技能兜底;最后由加载到的技能输出该类漏洞的检测思路,包括检测模式、测试载荷与绕过对照表。
3.2 7 问验证门:先验证,再报告
所有候选发现都要过 7 个问题:
- 验证者能否用一个真实 HTTP 请求立刻复现?
- 影响是否在项目方声明的影响清单内?
- 资产是否在授权范围内?
- 是否依赖测试者拿不到的特权?
- 是否是已知或文档化行为?
- 影响能否超越"理论上可能"被证实?
- 是否不在"永不提交"清单内?
任何一问为否就判 KILL,继续下一项。四种判定结果:PASS(可写报告)、DOWNGRADE(降级)、KILL(放弃)、CHAIN REQUIRED(需要与其他原语组合才能成立)。官方称这一步是使用者反馈中"最有用的一步"——它把大量会被平台判为 N/A(无效)的报告挡在了提交之前。
3.3 15 个斜杠命令速览
| 命令 | 作用 |
|---|---|
/recon |
全量侦察:子域枚举、存活探测、指纹识别 |
/hunt |
对目标开始审计,自动加载对应技能 |
/triage |
快速 7 问验证 |
/validate |
完整验证 + 四门检查清单 |
/chain |
构建多原语组合判定 |
/report |
按平台模板生成报告 |
/scope |
核对资产是否在范围内 |
/surface |
汇总侦察结果,输出优先级排序 |
/autopilot |
带检查点的自动循环 |
/pickup |
恢复上一次会话 |
/remember |
记录发现到本地记忆文件 |
/intel |
查询 CVE 与披露报告情报 |
/memory-gc |
清理会话记忆文件 |
/token-scan |
代币合约安全检查 |
/web3-audit |
智能合约十类检查清单 |
四、安装前的环境准备
| 项目 | 要求 | 说明 |
|---|---|---|
| 操作系统 | macOS / Linux / Windows | Windows 已提供原生 PowerShell 安装脚本,不再强制 WSL2 |
| Claude Code CLI | 必需 | 从 claude.ai/download 获取,或选用 OpenCode、Codex CLI 等环境 |
| Python | 3.9+ | 用于 cbh 命令行工具 |
| git | 必需 | 克隆仓库用 |
| Claude 账号 | 必需 | 订阅计划或 API Key 均可 |
| Burp Suite | 可选 | 不装也能用,curl-only 模式功能完整 |
| subfinder | 可选 | 增强被动子域枚举,没有则回退 crt.sh |
| HackerOne 账号 | 可选 | 仅用于 MCP 读取自己的私有项目与报告,留空不影响功能 |
五、两种安装方式
5.1 方式一:插件市场安装(推荐)
在 Claude Code 会话里直接输入两条命令:
/plugin marketplace add elementalsouls/Claude-BugHunter
/plugin install claude-bughunter@elementalsouls
83 个技能 + 15 个命令会以 claude-bughunter: 命名空间加载,不往 ~/.claude/ 里复制文件,升级时跟随插件版本走,干净且好管理。
5.2 方式二:脚本复制安装
适合想锁定某个版本、或不用插件系统的场景:
git clone https://github.com/elementalsouls/Claude-BugHunter.git
cd Claude-BugHunter
# macOS / Linux
bash scripts/install.sh
# Windows(PowerShell)
pwsh ./scripts/install.ps1
脚本会把技能复制到 ~/.claude/skills/(Windows 为 %USERPROFILE%\.claude\skills\),命令复制到 ~/.claude/commands/,并配置 hunt 演练文件夹生成器。同名旧技能会自动备份到 ~/.claude/install-backups/<时间戳>/,重复执行不会破坏已有配置。

5.3 装到其他运行环境
技能文件就是标准 Agent Skills 格式,OpenCode、Codex CLI、Hermes、AntiGravity 也能加载:
bash scripts/install.sh --all # 一次装到全部 5 种环境
bash scripts/install.sh --agents # 仅 Codex + OpenCode
bash scripts/install.sh --hermes # 仅 Hermes
bash scripts/install.sh --antigravity # 仅 Google AntiGravity
Windows 对应 pwsh ./scripts/install.ps1 -All 等。注意:斜杠命令与插件市场仅 Claude Code 支持,其他环境拿到的是技能知识与 Burp MCP 集成。
5.4 单独安装 cbh 命令行
cbh 是不依赖大模型的确定性运行器(纯 Python 标准库实现),适合批量侦察与 CI 集成:
pipx install git+https://github.com/elementalsouls/Claude-BugHunter
cbh recon example.com
5.5 安装验证:三个冒烟测试
装完后开一个新的 claude 会话,依次验证:
1. 技能触发:输入「我有一个回显进页面 HTML 的用户输入,在测试 XSS,该试哪些载荷?」
预期:Claude 自动加载 hunt-xss 并给出检测思路
2. 验证门:输入 /triage,然后描述一个假设发现
预期:走完 7 问验证流程并给出四种判定之一
3. 演练脚手架:终端执行 hunt acme-test,再 ls ~/Targets/acme-test/
预期:出现 CLAUDE.md、scope.md、findings/、evidence/ 等完整目录
三项都通过,环境就绪。
六、第一次上手:完整流程演示
6.1 建立演练文件夹
hunt h1-vdp
cd ~/Targets/h1-vdp
claude
hunt 会生成标准化目录:CLAUDE.md(项目上下文)、scope.md(范围声明)、findings/(发现)、evidence/(证据)、submissions.txt(提交记录)。
6.2 用自然语言开工
直接告诉 Claude 你要做什么:
我要对一个已授权的漏洞赏金项目做安全研究,程序地址是(官方程序页)。
请从头带我走一遍流程,先做侦察。
Claude 会依次加载 bb-methodology、triage-validation、web2-recon 等技能,先确认范围与模式,再输出具体可执行的侦察命令。
6.3 有发现先验证
/triage
我发现密码重置接口在给定有效用户 ID 时,响应里回显了用户邮箱,
看起来像账号枚举问题。
7 问门跑完后给出判定。如果判 KILL,直接换下一个思路,不要浪费时间写报告——这正是这个工具最有价值的行为约束。
6.4 生成报告
判定 PASS 后输入 /report,选择目标平台(HackerOne / Bugcrowd 等),Claude 按对应模板输出可直接提交的报告正文,证据部分会按 evidence-hygiene 规范自动脱敏。
七、合规使用边界(务必阅读)
这一节是官方文档反复强调、也是每个使用者必须遵守的:
- 只能测试你拥有的资产,或持有书面授权的资产:漏洞赏金项目范围内的资产、企业授权评估、CTF 题目、自建环境。
- 零风险练手靶场:DVWA、OWASP Juice Shop、Hacker101、testphp.vulnweb.com 都是官方推荐、专门供练习的合法环境。
- 内置验证门会主动拦截越界行为:7 问中的第 2、3 问会强制核对授权状态,指向未验证的第三方目标时会触发授权确认。
- 官方明确排除的场景:内部域环境研究、C2 框架集成、后渗透持久化、终端防护对抗、二进制利用等均不在项目范围内。
- 请遵守当地法律法规与各平台规则,技术学习务必在授权边界内进行。
八、常见问题排查
| 症状 | 原因 | 解决 |
|---|---|---|
hunt: command not found |
终端没加载配置 | 重新打开终端,或 source ~/.zshrc |
Windows 下 hunt 未识别 |
PowerShell 配置未生效 | 新开 PowerShell 窗口,或 . $PROFILE;确认执行策略为 RemoteSigned 及以上 |
| 技能不自动触发 | 描述里缺少类别关键词 | 在提示里明确说出类别,如"我在测 IDOR" |
脚本报 syntax error |
旧克隆被 CRLF 行尾污染 | 重新 clone 一次即可 |
/mcp 看不到 burp |
Burp 未运行或扩展未加载 | 打开 Burp,确认 MCP Server 扩展显示 Loaded |
| 想彻底卸载 | — | bash scripts/install.sh --uninstall,或插件方式 /plugin uninstall claude-bughunter@elementalsouls |
九、FAQ
Q1:必须有 Claude 订阅吗?API Key 行不行?
Claude Code 支持订阅计划或 API Key 两种接入方式,任选其一即可。注意订阅与 API 是两套计费,API 按 token 计费。
Q2:Windows 能直接用吗?
能。项目现在提供原生 PowerShell 安装脚本 install.ps1,hunt 生成器也改成了 hunt.ps1 挂在 PowerShell 配置里,不再强制 WSL2。
Q3:不装 Burp Suite 能用吗?
能。默认 curl-only 模式功能完整,Burp 属于可选增强(流量留痕、一键转 Repeater)。MCP 对话式集成需要 Burp Pro 才有意义。
Q4:和直接问 Claude"帮我找问题"有什么区别?
核心区别是纪律与沉淀:裸问得到的是通用建议;Claude-BugHunter 把 681 份真实披露报告的模式、每类漏洞的检测清单、验证门与报告模板都固化成了可复用技能,而且强制"先验证再报告",大幅减少无效提交。
十、总结
Claude-BugHunter 的价值不在于"让 AI 更聪明",而在于把成熟安全研究者的工作习惯——范围确认、模式匹配、验证纪律、证据脱敏、报告规范——固化成了 Claude Code 可复用的技能包。83 个技能覆盖 24 类漏洞研究模式,两种安装方式加起来不超过五条命令,五分钟就能跑通第一个冒烟测试。
适合三类读者:想系统学习安全审计的新手(建议从 Juice Shop 练习环境开始)、在做授权评估但苦于流程散乱的研究者、以及想把 AI 编排进安全工作流的工程师。再次提醒:所有测试请在授权范围内进行,合规是这项技术能走远的前提。