确定性Scope引擎:Claude-BugHunter 的 scope.py 如何用四种规则实现默认拒绝硬护栏(完整指南)
确定性Scope引擎:Claude-BugHunter 的 scope.py 如何用四种规则实现默认拒绝硬护栏(完整指南)
Claude-BugHunter 是一个面向漏洞赏金与外部红队工作的 Claude Code 技能包,其中的 engine/scope.py 是它的"安全护栏"核心:用一段确定性的代码判断任何主机是否在你的授权范围内——apex 域名、*. 通配、CIDR 网段、正则四种规则全部支持,拒绝优先、默认拒绝,不依赖任何大模型的"自觉"。
对新手来说,理解这个文件是理解整个项目安全设计的关键:当 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本身被拒。
另外两个细节也值得一提:
- URL 归一化:engine/scope.py 的
_host_of会先提取 hostname、转小写、去掉末尾点,所以HTTPS://Api.Example.COM./x和api.example.com是同一个判定对象; - 可解释的拒绝:
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 三层确定性检查,全部落在代码里:
- 入口闸:recon 阶段,每个候选目标先过
in_scope_host(),范围外的直接丢弃并记录; - 派发闸:
--hunt开启后,每个 hunt 任务在派发前再检查一次目标 URL("belt-and-suspenders",双重保险),越界即REFUSING; - 出口闸: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 种形态,写得清、判得准;
- 拒绝优先 + 默认拒绝,两条铁律消除一切"模糊地带";
- 入口、派发、出口三道闸门全部由确定性代码执行,日志里每条拒绝都有可读原因。
对新手而言,这套"护栏先行"的思路比任何单个漏洞技巧都更值得先学会——它决定了你的自动化到底是可靠的助手,还是失控的脚本。
