确定性Scope引擎:Claude-BugHunter 的 scope.py 如何用四种规则实现默认拒绝硬护栏(完整指南)

原创2026-11-16 13:18:332,135 阅读
文章标签:网络安全渗透测试AI 技能红蓝对抗漏洞扫描MCP Clients

确定性Scope引擎:Claude-BugHunter 的 scope.py 如何用四种规则实现默认拒绝硬护栏(完整指南)

Claude-BugHunter 是一个面向漏洞赏金与外部红队工作的 Claude Code 技能包,其中的 engine/scope.py 是它的"安全护栏"核心:用一段确定性的代码判断任何主机是否在你的授权范围内——apex 域名、*. 通配、CIDR 网段、正则四种规则全部支持,拒绝优先、默认拒绝,不依赖任何大模型的"自觉"。

Claude-BugHunter 确定性Scope引擎与漏洞猎护项目横幅

对新手来说,理解这个文件是理解整个项目安全设计的关键:当 AI 可能无人值守地自动测试目标时,"哪些资产能动、哪些绝对不能碰"这件事,必须写在代码里,而不是写在提示词里。

为什么硬护栏必须写在代码里,而不是提示词里?

engine/README.md 里把项目设计成"决策支持引擎,而非自主机器人"。它的默认流程是:

recon ──▶ rank ──▶ map ──▶ (交回给你)──▶ [可选] hunt ──▶ validate ──▶ report

在这条流水线的每一步,engine/engine.py 都会调用 Scope 做两件事:

  • 事前拦截:派发任何探测任务前,先过一遍 scope 检查,范围外的主机直接 REFUSING out-of-scope;
  • 事后审计:每个已确认的漏洞报告(PoC)会被再扫一遍,只要涉及了范围外主机,就在报告里打上 ⚠ 标记供人工复核。

scope.py 文件头写得很直白:

The engine may run unattended, so scope is enforced in CODE, not by trusting an LLM.

翻译成大白话:提示词可能失守,代码不会。 这就是"默认拒绝硬护栏"的含义——宁可错杀一个范围内的目标(你只需补一条规则),也绝不放过一个范围外的目标。

四种范围规则语法:一张表看懂

scope.py 只支持四种模式(对 URL 的 host 部分做匹配),刻意保持简单,新手一眼就能写对:

规则写法 含义 示例命中 / 不命中
example.com(apex) 该 apex 及其所有子域名 ✅ example.com、api.example.com
*.example.com(通配) 任意子域,不含裸 apex ✅ a.test.example.com;❌ test.example.com
api.example.com(精确) 只匹配这一个主机 ✅ api.example.com
10.0.0.0/8(CIDR) 网段内任意 IPv4 ✅ 10.1.2.3;❌ 11.0.0.1
re:^lab[0-9]+\.acme\.io$(正则) 显式正则,前缀 re: ✅ lab42.acme.io

两种列表叠加出完整逻辑:

  • in_scope(允许列表):匹配任意一条 → 进入范围;
  • out_of_scope(拒绝列表):匹配任意一条 → 立即拒绝,即使它同时也匹配了允许列表(deny wins,拒绝优先)。

而核心的一条铁律是:既不在允许列表、也不在拒绝列表的主机,一律视为范围外(default deny)。 换句话说,不写规则 = 全部拒绝——这对新手是好事:一个空的 in-scope 列表意味着什么都不能测,这正是安全默认值。

两个容易踩的坑:后缀混淆与通配深度

scope.py 的内置自测(python3 engine/scope.py --selftest,实测输出 scope.py self-test: PASS)里专门针对两类经典误判做了断言:

  • 后缀混淆防护:example.com 规则不会误伤 notexample.com,也不会放行 example.com.evil.com——匹配永远基于完整的域名标签,而不是简单的字符串"结尾包含";
  • 通配深度防护:*.test.example.com 要求 host 必须比 test.example.com 深一层,所以 a.test.example.com 通过,但 test.example.com 本身被拒。

另外两个细节也值得一提:

  1. URL 归一化:engine/scope.py 的 _host_of 会先提取 hostname、转小写、去掉末尾点,所以 HTTPS://Api.Example.COM./x 和 api.example.com 是同一个判定对象;
  2. 可解释的拒绝:reject_reason() 不只返回"是/否",还会给出人类可读的原因(如 matches an out-of-scope rule 或 matches no in-scope rule (default deny)),方便写进日志和报告。

scope 从哪里来:scope.md 与 scope.json 两种载体

Scope 类支持两种加载方式,对应项目里的两种工作流:

① 斜杠命令工作流 —— 用 scripts/hunt.sh 脚手架会为新目标创建 scope.md,commands/scope.md 定义了强制的预检流程:在任何 HTTP 请求发出前,先跑一次

python3 engine/scope.py api.acme.com --md ~/Targets/acme/scope.md

它会解析 scope.md 里 ## In scope / ## Out of scope 两个小节下的列表项,逐条判定并打印 IN-SCOPE / OUT-SCOPE (原因)。只要有一个资产越界,进程就以非零码退出——这意味着它可以直接作为自动化脚本的前置开关(gate)使用。

② 引擎工作流 —— engine/engine.py 通过 --scope 参数读取 JSON(结构见 engine/engagement.example.json):

{
  "name": "demo-local",
  "in_scope": ["localhost", "127.0.0.1"],
  "out_of_scope": ["admin.localhost"],
  "seeds": ["http://localhost:3002"]
}

seeds 是初始种子目标,in_scope / out_of_scope 交给 Scope.load() 解析,之后所有 recon 发现的主机(包括 OSINT 扩展出来的子域)都必须再次通过 in_scope_host() 才能进入 recon 队列——recon 阶段发现的越界主机会被记录下来(out-of-scope host(s) seen, NOT tested),只记录、不测试。

硬护栏在完整流程中的三道闸门 🛡️

把上面拼起来,Claude-BugHunter 实际上给了 scope 三层确定性检查,全部落在代码里:

  1. 入口闸:recon 阶段,每个候选目标先过 in_scope_host(),范围外的直接丢弃并记录;
  2. 派发闸:--hunt 开启后,每个 hunt 任务在派发前再检查一次目标 URL("belt-and-suspenders",双重保险),越界即 REFUSING;
  3. 出口闸:validate 后的每条确认发现都会做 scope 审计,PoC 中若出现范围外主机,报告自动附加 ⚠ SCOPE WARNING 区块,提醒人工确认"去掉越界动作后结论是否仍成立"。

配合 hunt/validate agent 默认的只读约束(不发邮件、不写库、不删数据),整个系统在"默认最安全"的设定下运行:--allow-intrusive 这类放宽开关是显式可选的,而非默认行为。

上手体验:30 秒验证一次判定

不用安装任何东西,在项目目录里直接跑自测:

python3 engine/scope.py --selftest

或者用自己的目标做一次真实判定(内联模式,--in-scope 可重复传入):

python3 engine/scope.py api.acme.com evil.com \
  --in-scope acme.com \
  --out-of-scope admin.acme.com

预期输出:

IN-SCOPE   api.acme.com
OUT-SCOPE  evil.com  (evil.com matches no in-scope rule (default deny))

如果想理解项目更大的图景,可以继续读 docs/architecture.md 中 /scope 在 6 阶段工作流里的位置,以及 engine/README.md 对"确定性优先"设计原则的完整阐述。

小结

scope.py 只有 100 多行,却是 Claude-BugHunter 里最有教育意义的一块:它示范了如何让 AI 自动化在无人值守下仍然守规矩——

  • 规则只有 4 种形态,写得清、判得准;
  • 拒绝优先 + 默认拒绝,两条铁律消除一切"模糊地带";
  • 入口、派发、出口三道闸门全部由确定性代码执行,日志里每条拒绝都有可读原因。

对新手而言,这套"护栏先行"的思路比任何单个漏洞技巧都更值得先学会——它决定了你的自动化到底是可靠的助手,还是失控的脚本。

登录后查看全文
Claude-BugHunter