Claude-BugHunter 安全策略实践指南:授权边界、代码级 Scope 强制与安装供应链校验
Claude-BugHunter 安全策略实践指南:授权边界、代码级 Scope 强制与安装供应链校验
Claude-BugHunter 是一个以 SKILL.md 为载体的攻防知识包(仓库内共 83 个 skill、15 个 slash command),其安全策略并不是一份挂在角落的法律声明,而是一套可以直接落到代码与 CI 上的约束体系。本文以 SECURITY.md 为主线,逐条拆解它的授权使用基线、验证闸门、刻意排除的能力边界、安装供应链信任模型与漏洞披露流程,并结合 engine/scope.py、scripts/lint_skills.py、.github/workflows/skill-lint.yml 等实现,说明这些承诺在工程上是如何被强制执行的。读完后你应能准确判断:哪些目标可以测、哪些动作会被代码拦下、安装前应当校验什么、以及在发现仓库自身问题时该走哪条通道。
一、先把定位说清楚:这是知识包,不是武器库
SECURITY.md 开篇给出的定义非常关键:claude-bughunter 是一个 knowledge bundle,内容是方法论、payload、绕过对照表、检测模式与报告模板,素材来自公开披露的漏洞赏金报告和经过授权的评估项目。这一定义决定了后续所有条款的基调——它提供的是"知道怎么测"的知识,而不是"自动打穿"的工具链。
与之对应,仓库的自述也是同一口径:83 个 skill 全部是纯文本 SKILL.md(见 skills/ 目录结构),安装脚本只做本地文件复制(scripts/install.sh),不包含 C2、后渗透、免杀等模块。理解这一点很重要,因为安全策略中的"排除项"不是能力缺口,而是产品定位的一部分。
二、授权使用的基准线:五类可以测的目标
SECURITY.md 把"可以用在什么资产上"收窄为五类,并且要求"拥有"或"有书面授权":
| 类别 | 典型场景 | 授权凭据形态 |
|---|---|---|
| 漏洞赏金项目 | HackerOne、Bugcrowd、Intigriti、Immunefi、YesWeHack 等平台上明确在 scope 内的资产 | 项目 scope 页面 + 项目规则 |
| 授权渗透测试 | 签署 RoE(Rules of Engagement)的评估项目 | 签约文本、授权书 |
| CTF 竞赛 | 竞赛环境中的靶标 | 赛事规则 |
| 自有基础设施 | 自己公司/个人的域名、主机 | 所有权 |
| 合成/实验环境研究 | 本地靶场、实验室应用 | 自建环境 |
这五类之外没有"默认允许"的灰色地带。文档最后一句给了操作纪律:如果你不确定某个目标是否在 scope 内,或某个动作是否被授权,先停下来,拿到书面确认再继续。
值得注意的是,仓库为"实验环境研究"这一类提供了真实可用的落地物:例如 docs/verification/ 下的多个 lab(hardened-lab、phase2e-lab 至 phase2i-lab、phase3-playwright 等)以及 docs/verification/hardened-lab-discipline-rules.md,它们就是"在自有/合成目标上验证"这一条款的具体承载。
三、被写到代码里的 Scope:deny wins,默认拒绝
3.1 为什么不能交给 LLM 判断
engine/scope.py 的文件头注释直接说明了设计动机:引擎可能在无人值守的情况下运行,因此 scope 必须由确定性代码执行,而不是信任 LLM 的判断。这份实现给出两条硬规则:
- deny wins(拒绝优先):一个资产即使同时命中 in-scope 与 out-of-scope 规则,也判定为越界;
- default deny(默认拒绝):只要不匹配任何 in-scope 规则,一律视为越界。
对应实现见 engine/scope.py:in_scope_host() 先检查 out-of-scope,命中即 False;reject_reason() 则给出人类可读的拒绝原因(could not parse host、matches an out-of-scope rule、matches no in-scope rule (default deny)),便于审计日志。
3.2 支持的 Scope 模式语法
SECURITY.md 说的是"授权姿态",而 engine/scope.py 给出了可执行的匹配语法,两者是同一件事的两面:
| 模式写法 | 语义 | 容易踩的坑 |
|---|---|---|
example.com |
裸域(apex)及其任意子域 | 不只是 example.com 本身 |
*.example.com |
任意子域,不含裸域 | test.example.com 不会被 *.test.example.com 匹配 |
api.example.com |
精确主机 | 不带通配 |
10.0.0.0/8 |
CIDR 内的 IPv4 | 仅 IPv4 |
re:^staging[0-9]+\.example\.com$ |
显式正则(前缀 re:) |
正则有语法错误时返回不匹配(安全侧) |
实现里还有两处值得单独说明的防护:*. 分支使用 host.endswith("." + base) 而不是朴素的后缀比较,因此 notexample.com、example.com.evil.com 这类后缀混淆不会被误判为在范围内——这两条正是 engine/scope.py 自带自检用例的断言。
3.3 直接用 CLI 做门禁
engine/scope.py 既能读 hunt 脚手架生成的 scope.md,也能接收行内模式,并且提供了内置自检:
# 跑内置自检(deny-wins / 默认拒绝 / 后缀混淆等断言)
python3 engine/scope.py --selftest
# 对某个目标做确定性判定,读 engagement 的 scope.md
python3 engine/scope.py api.acme.com --md ~/Targets/acme/scope.md
# 用行内模式(每个模式一个 --in-scope / --out-of-scope)
python3 engine/scope.py api.acme.com evil.com \
--in-scope acme.com --in-scope '*.acme.io' --out-of-scope admin.acme.com
# 也可以读一份 JSON scope 文件(结构见 engine/engagement.example.json)
python3 engine/scope.py https://api.acme.com --scope-file engine/engagement.example.json
engine/engagement.example.json 给出了最小可用结构:
{
"name": "demo-local",
"in_scope": ["localhost", "127.0.0.1"],
"out_of_scope": ["admin.localhost"],
"seeds": ["http://localhost:3002"]
}
此外,engine/scope.py 里的 _scope_from_md() 能把脚手架生成的 scope.md 转成 Scope 对象:它只在 ## In scope / ## Out of scope 这类标题下收集 - / * 列表项,并取每项的第一个空白分隔 token,所以 - api.example.com — note 会得到 api.example.com;以 ( 或 [ 开头的占位符(例如 (paste ... here))会被跳过。这一点很实用:模板没填 = in-scope 列表为空 = 全部拒绝,这恰恰是文档所期望的安全默认值。
3.4 /scope:任何 HTTP 触碰之前的前置闸门
commands/scope.md 把上述判定封装成强制性前置步骤:
/scope api.acme.com
/scope api.acme.com staging.acme.io admin.acme.com
它的行为约定是:逐个资产输出 IN-SCOPE 或 OUT-OF-SCOPE <reason>,只要有任一资产越界就以非零码退出,因此可以直接拿来卡自动化流程。规则部分写明了两条:判定必须发生在任何 HTTP 请求之前,OUT-OF-SCOPE 是硬停止;scope.md 仍是空模板时必须先按项目页面填写。这与 SECURITY.md 中"若为证明影响必须越界,闸门默认给 DOWNGRADE 或 CHAIN REQUIRED,而不是'继续打深一点'"的立场完全一致。
四、自动触发的验证闸门:三处"越界即停"的机制
SECURITY.md 列举了三组在歧义出现时会自动触发的 skill 内闸门。它们不是口号,都有可查的实现文本。
4.1 7-Question Gate:Q2 管"是否在接受列表内",Q3 管"是否在 scope 内"
skills/triage-validation/SKILL.md 要求按顺序回答 7 个问题,任何一问答错即终止该 finding。其中与授权直接相关的是两问:
- Q2:影响是否落在项目接受的漏洞类型列表内?做法是回到项目页面的 "Vulnerability Types" / "Out of Scope" 逐条比对;命中明示排除项则放弃。
- Q3:根因资产是否在 scope 内?需要确认三件事——漏洞域名在 in-scope 列表(而不是
*.internal.target.com这类内部域)、是生产资产(除非 staging/dev 被明确纳入)、不是公司仅在使用的第三方服务(Stripe、Salesforce、Google Auth 之类)。
Q1 则要求把攻击链写成可复制的真实 HTTP 请求(方法、URL、头、体),写不出来就直接放弃——这从源头挡住了"读代码猜漏洞"式的提交。
同一份 skill 里还有一段对"误判授权绕过"的高价值提醒:验证错误不能证明你穿过了认证。许多栈会在认证中间件之前放置全局入参清洗/body parser,畸形请求体在认证被查询之前就被拒绝,返回的 400 与"认证通过但校验失败"在响应上无法区分。正确做法是用格式合法的最小 body 重放一次:
# 畸形 body —— 清洗器先触发,看起来像"越过了认证"
curl -s -X POST https://target/api/v1/resource -d '{'
# 同一端点、合法空对象 —— 这时才真正走到认证层
curl -s -X POST https://target/api/v1/resource -H 'Content-Type: application/json' -d '{}'
只有第二个响应才告诉你认证层的位置。这条纪律直接对应 SECURITY.md 的"越界不得用进一步利用来证明":错误的层级推断会产出针对生产基础设施的假 Critical。
4.2 evidence-hygiene:证据必须脱敏,凭据必须轮换
SECURITY.md 用 evidence-hygiene 的 redaction 协议来回应"不得伤害被测目标的用户"这一承诺。对应 skills/evidence-hygiene/SKILL.md 的章节结构,覆盖范围包括:敏感数据的两类划分、Cookie 脱敏协议(含"什么必须遮、什么可保留、脱敏方法按实用性排序、截图前检查清单")、他人 PII 黑条协议(含 IDOR PoC 正文的示例处理)、HAR 文件清洗与附件前复核、Burp 截图卫生(Repeater/Intruder/Proxy history/Scanner)、DevTools Console 的干净 PoC 写法、截图捕获顺序纪律(5 步状态变更型 PoC 模式、文件命名、时序),以及第 8 节提交后卫生(轮换测试账号凭据、私存未脱敏原件、不要公开发帖、审计本地遗留物)。
其中第 8 节正是 SECURITY.md 中"提交后轮换 PoC 中出现的凭据、token、session cookie"这条承诺的技术落点。
4.3 bugcrowd-reporting:研究者侧卫生,向反欺诈团队发出"授权测试"信号
SECURITY.md 提到该 skill 包含研究者侧的合规动作:使用 Bugcrowdninja 邮箱别名、恢复账号状态、保持"friendly tester"姿态。这些做法的目的不是绕过检测,而是让目标的反欺诈团队能够把测试流量与被判为攻击的流量区分开来——本质上仍是授权证明的一部分。
五、明确的排除项:不是缺口,而是刻意的边界(内部攻击面不在覆盖内)
SECURITY.md 用了一整节界定"外部攻击面":即互联网与已认证生产系统之间的边界。一旦边界被突破,内部网络攻击不在覆盖范围内。 文档特别强调这些是"out-of-scope-by-design",并逐项列出:
| 排除类别 | 具体内容 |
|---|---|
| 内部 Active Directory 攻击 | BloodHound、Kerberoasting、ASREProast、DCSync、DCShadow、Pass-the-Hash、Pass-the-Ticket、AD CS 滥用、ntlmrelayx、Responder、mitm6、PetitPotam、PrinterBug |
| C2 框架战术 | Cobalt Strike、Sliver、Mythic、Havoc、BRC4 |
| 后渗透 / 持久化 | LSASS dump、golden/silver ticket、注册表持久化、计划任务、WMI 事件订阅、COM 劫持、token 窃取、命名管道冒充 |
| 免杀 | AMSI bypass、ETW patching、Sysmon 感知、AV/EDR 绕过、syscall 直接/间接调用 |
| L2 内部网络协议 | LLMNR/NBT-NS 投毒、IPv6 SLAAC 滥用、ARP 欺骗 |
文档给出的理由是运营风险画像不同:针对被监控的企业内网做 AD 攻击,其防御者感知度、蓝队检测能力与特定授权条款下的法律暴露都与外网测试有本质差别。因此 skill 内容与操作纪律都是按外网边界校准的,文档明确写道:针对内部 AD 与后渗透的覆盖可能出现在未来版本;不要把当前的缺失当作可以即兴补齐的空白。
这带来一条很具体的工作约定:如果在评估中抵达域管级别的目标,本包的外网攻击链止步于"发现凭据 + 验证访问",之后要交接给专门的内网工具(文档点名 Impacket、NetExec、CrackMapExec、Rubeus、Certify、BloodHound),而这个交接本身被有意留在包外。同一口径也写在 README.md 的 in/out of scope 小节里,两处表述一致,可以交叉验证。
六、安装供应链信任:你往 Agent 上下文里装的是第三方代码
SECURITY.md 的供应链一节是全文最具工程价值的部分。它先给出一个容易被忽略的事实:安装这个包,等于把 83 个 SKILL.md 以及若干 shell/Python 辅助脚本放进 AI Agent 的上下文;Agent Skills 属于第三方代码,应当像对待任何依赖一样对待。文档还引用了 Snyk 于 2026 年发布的 "ToxicSkills" 独立研究结论——在相当比例的公开 skill 中发现过 prompt injection——以此说明校验的必要性。这是文档引用的外部研究结论,不是本仓库的测试结果,阅读时应保持这一区分。
6.1 仓库侧做了什么
| 措施 | 落地文件 | 具体行为 |
|---|---|---|
| 每次 skill 变更跑 CI 门禁 | .github/workflows/skill-lint.yml | 调用 scripts/lint_skills.py 校验结构,并扫描泄露的密钥与客户/项目标识;随后跑 engine/skill_map.py 的路由自检 |
| 可固定的来源 | .claude-plugin/marketplace.json、git tag/commit |
通过插件市场安装会把每个版本固定到具体 commit SHA 并过 Anthropic 的自动筛查;从 clone 安装可自行 git checkout <tag-or-commit> |
| 安装期无网络调用 | scripts/install.sh | 只复制本地文件;除非 --no-shell,否则只向 shell rc 追加一行 source,并把该行打印回显给你 |
6.2 lint_skills.py 到底检查什么
读了 scripts/lint_skills.py 就能把"结构校验 + 密钥扫描"这句话拆成可核对的清单:
- 结构项:
SKILL.md必须存在(否则报missing SKILL.md);必须有 frontmatter 块;name必须匹配^[a-z0-9-]+$且等于目录名;description必填且 ≤ 1024 字符;正文 ≤ 500 行(超出为 warning,提示改用references/子目录)。 - 严格 YAML 安全:
yaml_safety_errors()(scripts/lint_skills.py)专门捕获公式化的 YAML 陷阱——未加引号却含": "的值,严格解析器(如 Codex)会把它读成嵌套映射。 - 来源标注(grounding):每个 skill 必须声明
sources:;hunt-*还必须声明整数report_count:(允许 0,但需sources:说明理由)。当前GROUNDING_STRICT = True,即已从 warning 升级为 error。 - 客户标识 denylist:对文件做 1-word 与 2-word shingle 归一化后逐一 sha256,与
scripts/.identifier-denylist.sha256比对;命中即 error。设计上明文名称从不进入仓库,可选scripts/.identifier-denylist.local在运行时哈希。 - 真实密钥扫描:
SECRET_PATTERNS覆盖 AWS access key、私钥块、JWT、Slack token、Google API key、GitHub PAT;同时用SECRET_ALLOW(含EXAMPLE、\.\.\.、<...>等)放行文档里的示例与正则字面量,避免密钥目录类 skill 被误报。 - 退出码语义:0 = 干净,1 = 至少一个错误;warning 不会让构建失败。
6.3 比 lint 更严的 leak-guard:全仓库扫描且 fail closed
skill-lint 只看 skills/**,而一次真实的泄露发生在 README.md 与 tests/ 里——这是 .github/workflows/leak-guard.yml 注释中记录的动因。因此 leak-guard 的特征是:
- 无 path filter:每次 push 与 PR 全跑;
- 先自测扫描器:执行
scripts/test_scan_identifiers.py再扫; - 失败关闭:
scripts/scan_identifiers.py在 denylist 缺失/为空时以 exit 2 退出,而不是像lint_skills.py那样打印 NOTE 后返回 0。
扫描范围是 git ls-files 出来的全部受跟踪文本文件,二进制扩展名(图片、字体、压缩包、可执行文件等)在 BINARY_EXT 中被排除。哈希机制与 lint_skills.py 完全一致(相同的 shingle 规则、相同的 denylist 文件),保证两道门禁不会对同一个标识给出不同结论。
6.4 本地前置防线与 denylist 维护
想把问题拦在 git push 之前,只需在 clone 里启用一次钩子(见 CONTRIBUTING.md 与 .githooks/pre-commit):
git config core.hooksPath .githooks
钩子执行 python3 scripts/scan_identifiers.py,失败即阻断提交,并提示改用 scripts/.identifier-denylist.local(已 gitignore,运行时哈希)添加新的禁用词。要封禁一个新标识而不提交明文,可以提交它的哈希:
printf '%s' "the name" | tr '[:upper:]' '[:lower:]' | shasum -a 256 # 粘贴输出的哈希
注意这两条路径的区别:.sha256 文件里放的是哈希,.local 文件里放的是明文但永不入库。
6.5 安装脚本的可审计性
scripts/install.sh 的行为边界写得相当克制,值得逐条核对:
- 选项集合:
--agents、--hermes、--antigravity、--all、--burp-mcp、--normalize-frontmatter、--no-shell、--uninstall、-h|--help,未知参数直接exit 2。 - 幂等与备份:同内容跳过;不同内容则移动旧目录到加载路径之外的
~/.claude/install-backups/<ts>/,避免备份被当作重复 skill 加载。 - 足迹清单:安装后写
~/.claude/.skill-manifests/claude-bughunter.txt;--uninstall逐条读取清单,若某条目仍被兄弟包(例如 Claude-OSINT)的清单声明,则保留不删,从而"卸载一个不会打断另一个"。 - rc 修改最小化:只追加
source ~/.claude/scripts/hunt.sh一行(带一行注释),并在卸载时用sed精确删除该行;加--no-shell则完全不碰 rc,只打印需要你自己添加的那一行。 - Codex 兼容处理:向
~/.agents/skills复制时会自动截断超过 1024 字符的description(Codex 硬性限制),且只改这一份拷贝,~/.claude与~/.hermes保留完整描述;--normalize-frontmatter额外剥离sources/report_count等非标准键。 --burp-mcp是显式 opt-in:先用python3调用scripts/setup_harness_mcp.py,并且会先备份各自的配置文件。
如果安装路径回归(例如 --antigravity 落到了错误的目录),.github/workflows/install-smoke.yml 会在临时 HOME 里做 dry-run 断言:默认安装后 skill 目录数 >= 80;--antigravity 必须落到 ~/.gemini/config/skills 且不得出现在 ~/.gemini/antigravity/skills;--uninstall 后足迹清空。同时 CI 对三个 installer 跑 shellcheck -S warning 与 bash -n,并在 Windows runner 上只做 PowerShell 语法解析而不执行。
6.6 必须承认的边界:lint 不等于安全
SECURITY.md 用了一个独立小节"What this does NOT prove — read this",态度值得照抄到任何 skill 供应链讨论里:
- lint 是结构性 + 密钥/标识检查,不是恶意代码或 prompt injection 检测器,也不声称能发现恶意 skill。一次干净的 lint 只意味着"格式良好、没有明显泄露的密钥",仅此而已。
- 信任前先审阅:
SKILL.md与随包脚本(skills/*/scripts/、scripts/)都是纯文本,安装前浏览一遍,重点关注任何发起网络请求或执行 shell 的地方。 - 固定到已审阅的 tag/commit,而不是跟随
main,这样上游改动无法在你不知情时改变 Agent 里实际运行的内容。
七、发现本仓库自身的问题:走哪条通道
SECURITY.md 把"针对本仓库的问题"与"被测目标的漏洞"明确区分开。针对本仓库,按问题类型分三条路径:
| 问题类型 | 处理通道 |
|---|---|
| 你认为可能被滥用于未授权目标的 skill 内容,且缺乏对等的防御价值 | 开带 security 标签的 GitHub issue,或按 GitHub 个人资料页列出的地址联系作者 |
安装脚本漏洞(macOS/Linux 的 scripts/install.sh、scripts/install-community-skills.sh、scripts/hunt.sh,以及 Windows 的 scripts/*.ps1 对应脚本) |
同上 |
| 误随仓库发布的敏感内容(项目特定数据、真实账号 UID、真实赏金金额) | 立即标记,作者会在后续提交中清洗 |
同时有一条硬性禁止:不要在 issue 中附带针对第三方目标的未授权利用证据。
八、用本包发现漏洞后的披露流程(5 步)
SECURITY.md 给出的流程是可执行的,而不是原则性表态:
- 先验证——跑
/triage或/validate(即 7-Question Gate)。对应命令文件见 commands/triage.md 与 commands/validate.md。 - 带卫生地取证——由
evidence-hygiene负责 Cookie 脱敏、他人 PII 黑条、HAR 清洗。 - 走官方渠道提交——HackerOne / Bugcrowd / Intigriti / Immunefi 的报告表单,或项目自己的
security@/vdp@邮箱。 - 协调披露——遵守项目的保密条款;在项目公开披露前不要发推或写博客。
- 轮换测试账号凭据——
evidence-hygiene第 8 节覆盖提交后卫生。
产出物方面,文档点名 report-writing 与 bugcrowd-reporting 能生成平台可用的提交模板,包含 CVSS 3.1 评分、影响陈述与复现步骤。相关文件为 skills/report-writing/SKILL.md 与 skills/bugcrowd-reporting/SKILL.md。
九、使用者承诺清单:五条你需要自己承担的
SECURITY.md 用"By using claude-bughunter, you acknowledge"列出五条,原文逐条对应如下(可直接当自查表用):
- 你有责任确保对任何交给 Claude 的目标都具备授权;
- 你会尊重项目 scope、RoE 以及漏洞赏金规则的精神(而不仅是字面);
- 你不会伤害被测目标的用户——不做超出证明影响所必需范围的真实 PII 外带、不造成服务降级、不做 DoS;
- 取证与提交时遵循
evidence-hygiene的脱敏协议; - 提交后会轮换任何出现在 PoC 产物中的凭据、token 或 session cookie。
十、许可与责任:MIT 代码 + CC BY 4.0 内容
SECURITY.md 明确软件按 MIT License 以 "as is" 提供,不附带任何担保;作者不对误用、未授权测试、使用方式导致的法律后果或由此产生的任何损害负责。
更细的许可边界在 README.md 中给出,属于双许可:
README 特意把边界写死:*.py、*.sh 等源文件是 MIT;*.md 文档、字典、正则目录与评分表是 CC BY 4.0。 复用内容(含商用)需署名 Sachin Sharma / Claude-BugHunter 并链回本仓库;上游 skill 的归属见 NOTICE。这一点对想在企业内部二次分发的团队尤其重要——"代码能怎么用"和"知识内容能怎么用"是两套条件。
十一、一页式核对清单
把上述条款压成一张执行表,按顺序过一遍即可:
| 阶段 | 动作 | 依据 |
|---|---|---|
| 目标确认 | 五类授权目标之一?否则停 | SECURITY.md |
| 填 scope | 把项目页面内容填进 scope.md,不要留占位符 |
commands/scope.md |
| 前置检查 | /scope <asset> 或 python3 engine/scope.py,非零码即硬停 |
engine/scope.py |
| 测试中 | 只用外部攻击面方法;不自行补内部 AD/C2/后渗透/免杀 | SECURITY.md |
| 发现候选 | 过 Q1–Q7;层级推断用"合法最小 body"复核 | skills/triage-validation/SKILL.md |
| 越界诱惑 | 默认 DOWNGRADE 或 CHAIN REQUIRED,不"再打深一点" | SECURITY.md |
| 取证 | Cookie/PII/HAR 脱敏后再出图 | skills/evidence-hygiene/SKILL.md |
| 提交 | /triage 或 /validate → 官方渠道 → 协调披露 → 轮换凭据 |
SECURITY.md |
| 安装前 | git checkout <tag>、读 SKILL.md 与 scripts/、--no-shell 或核对 rc 那一行 |
scripts/install.sh |
| 贡献前 | git config core.hooksPath .githooks,新增禁用词只提交哈希 |
.githooks/pre-commit |
这份安全策略的价值在于它的"可执行性":scope 判定是代码、拒绝优先且默认拒绝;验证闸门写在 skill 里并配有真实反例;供应链侧有 lint、全仓 leak-guard、installer smoke test 与可固定的安装来源;同时它坦率承认 lint 不是恶意代码检测器,并明确内部攻击面是设计上的排除项。按这张清单走,可以把"我在做授权测试"从一句自我陈述,变成一串可被他人复核的工程证据。