wallcheck

wallcheck

让 Agent 面对一个 URL，看看究竟是什么在阻挡它：证据确凿。

0.5.0：在发布就绪检查阶段盖章定稿（Wave 9 的发布候选版本）。尚未发布；发布暂停仍然有效。哪些已得到验证、哪些尚未验证，以及发布决策仍需哪些内容：campaign/LAUNCH-READINESS.md。

Agent 会在机器人拦截墙前悄无声息地失败。一次抓取返回 403，浏览器会话在一个又一个环境中反复折腾，上传始终无法开始：却没有任何东西能说明究竟是什么阻止了它、这是谁设下的拦截墙，或展示证据。wallcheck 会如实探测一次 URL，并对 Agent 实际遇到的情况进行分类：OPEN、CHALLENGED、WALLED、LOGIN_GATED、RATE_LIMITED 或 UNREACHABLE；同时指出供应商（Cloudflare、PerimeterX、DataDome、Akamai、Imperva、AWS WAF、Microsoft Azure WAF、Kasada、AWS CloudFront），以及能够证明这一点的具体信号。

判定过程完全不使用大模型：分类器是 (status, headers, body) 的确定性纯函数。相同的响应输入，相同的判定输出：因此结果可安全用于 CI、事件报告或公开的机器人拦截墙索引。

**v0.2 新增：**签名 Agent 身份。wallcheck keygen 会生成一个 RFC 9421 签名密钥，wallcheck probe <url> --sign key.json 会为探测附加真实的 HTTP 消息签名（hmac-sha256、tag="web-bot-auth"）：让 Agent 拥有名称，而不再是匿名机器人。wallcheck verify-server --key key.json 会运行一个小型服务端，只接受签名正确的请求，让网站所有者测试自己一侧的情况。hmac-sha256 变体适用于 Agent 与所有者双边协作的场景；Ed25519（v0.4）适用于公开目录场景：详见validation/wave2/SIGNING.md。

**v0.5.0 新增：**所有者侧审计以 audit 工具的形式加入 MCP 服务（每次调用最多执行 10 次如实的 GET，与 probe_url 遵循相同的有界抓取原则）；Wave 9 的文档检查依据实测情况修正了所有过时计数；在 Wave 9 盖章时，测试套件共有 120 项测试。Wave 10-17 将测试数提升至 428 项（Wave 17 审计记录的 423 项未计入 W17-007 实时修复新增的 5 个测试夹具：详见validation/wave17/STABILITY-12.md）；Wave 18 的 battery v10 加上 W18-007 实时修复后，测试数达到 481 项。Wave 19 的 battery v11 将测试数提升至 532 项；Wave 20 的 battery v12 提升至 571 项；Wave 21 的 battery v13 提升至 608 项；Wave 22 的 battery v14 提升至 638 项；Wave 23 的 battery v15 提升至 674 项；Wave 24 的 battery v16 提升至 710 项；Wave 25 的 battery v17 提升至 747 项；Wave 26 的 battery v18 提升至 788 项；Wave 27 的 battery v19 提升至 831 项。

**v0.5 新增：**分类器学会识别 Wave 5 扩展测得的情况：Microsoft Azure WAF、Kasada 和 AWS CloudFront 检测；Akamai 参考令牌拒绝页面；针对状态码 444 的判定规则（请求被丢弃即表示拒绝，绝不会是 OPEN）；以及一种误判挑战的情况：页面正常提供服务，只是嵌入了供自身表单使用的 reCAPTCHA/hCaptcha 加载器。Wave 5 发现的五个缺陷均已通过基于实时捕获数据的测试优先方式修复（PROBLEMS.md）。索引现覆盖 500 个站点（Wave 6-7 扩展，Wave 18 达到第 500 行）；Wave 5 使用已发布的签名器首次进行了有签名与无签名对比实验（SIGNED-EXPERIMENT.md）：未注册密钥没有改变任何判定结果；这就是身份方案必须推动改变的实测基线。对于所有者，修复套件会将审计发现转化为经过供应商验证的修复步骤。 v0.4 新增： Ed25519 签名身份。签名器现在使用纯 Python 标准库按 RFC 8032 实现 Ed25519（已通过官方 RFC 8032 §7.1 测试向量验证），因此 wallcheck keygen --alg ed25519 会生成兼容目录的 Web Bot Auth 密钥：公钥部分会发布在 /.well-known/http-message-signatures-directory 文档中，且 probe --sign 会自动检测密钥算法。 Wave 4 还为索引新增了第三个数据点，并对全部 154 个索引域名进行了首次签名 Agent 目录普查 （DIRECTORY.md）。

**v0.3 新增：**站点所有者侧审计。wallcheck audit <domain> 会从六项检查评估网站的 Agent 访问情况：robots.txt 中的 AI Agent 指令、llms.txt 合规性（HTML 软 404 判定为失败）、 站点地图、Feed 发现、API 发现，以及 Web Bot Auth 签名 Agent 就绪情况：每项均给出 PASS/WARN/FAIL、证据 和具体修复建议，最终汇总为 A-F 等级。首次实测审计 （validation/wave3/AUDITS.md）：我们自己的站点评级为 D/F：审计在其他人之前， 就在我们自己的站点发现了实际需要处理的问题。v0.3 还为分类器增加了 AWS WAF 检测，并将普查结果合并到 Bot Wall Index 工作表中（Wave 6-7 扩展后共 499 个站点）。

非目标

wallcheck 绝不会解决 CAPTCHA、伪造指纹或用户 代理，也不会绕过或规避墙、速率限制或访问控制。探测器会标明自身身份（user agent 为 wallcheck/<version>）。应对方式是检测 + 证据 + 标准：Agent 能够指出名称的墙就是一份 Bug 报告；签名 Agent 身份（Web Bot Auth，RFC 9421：原型已在 v0.2 发布，参见 SPEC.md）则是让 Agent 不再匿名的根本方式。

用法

CLI

# No install needed beyond Python 3.11+ (standard library only):
PYTHONPATH=src python3 -m wallcheck probe https://www.upwork.com

# Or install the package:
pip install .   # then: wallcheck probe <url> [--json]

输出示例（实际运行结果：完整列表见 DOGFOOD.md）：

https://example.com -> OPEN
  status: 200
  vendor: none detected
  elapsed: 87ms
  evidence:
    - STATUS_200

退出代码：OPEN 时为 0，其他任何判定时为 1，用法错误时为 2：可用于 CI。--json 会输出一个稳定的对象： {url, final_url, status, verdict, vendor, evidence[], elapsed_ms, redirect_chain[]}。

签名探测与站点所有者侧验证：

PYTHONPATH=src python3 -m wallcheck keygen --out wallcheck-key.json
PYTHONPATH=src python3 -m wallcheck probe https://example.com --sign wallcheck-key.json
PYTHONPATH=src python3 -m wallcheck verify-server --key wallcheck-key.json --port 8799

审计自己网站的 Agent 访问情况：

PYTHONPATH=src python3 -m wallcheck audit example.com [--json]

七项检查（robots.txt、llms.txt、站点地图、Feed、API、签名 Agent 就绪情况、安全联系信息）→ 每项给出 PASS/WARN/FAIL + 证据 + 修复清单，并给出评级（新增安全联系信息检查后，满分为 14；更早的评级满分为 12）。评级为 A/B 时退出代码为 0， 否则为 1。

扫描网站提供的页面是否暴露信息（需主动选择，同一次单独抓取）：

PYTHONPATH=src python3 -m wallcheck probe https://example.com --exposure [--json]

对页面本身向匿名访客提供的类似密钥材料进行分类——CANDIDATE_EXPOSURE（绝不应公开的服务器机密类别）、PUBLIC_BY_DESIGN（前端密钥、应用 ID）、 VISITOR_TOKEN（短期 JWT）。发现结果仅包含指纹：模式、类别、长度和 SHA-256 前缀，绝不包含实际值。方法及其披露规则见 campaign/EXPOSURE-LAYER.md。

判定结果

判定结果	含义
OPEN	页面已提供。Agent 可以读取。
CHALLENGED	出现了交互式人工验证挑战（Cloudflare 的 “Just a moment”、CAPTCHA 页面）。非交互式 Agent 会在此处停止。
WALLED	出现了硬拦截页面（“Sorry, you have been blocked”、拒绝页面、单纯的 403）。甚至没有提供挑战。
LOGIN_GATED	重定向到登录页面 / 提供了登录拦截页。内容存在，但需要通过身份验证才能访问。
RATE_LIMITED	HTTP 429，且没有更强的拦截信号。这是限流，不是拦截墙。
UNREACHABLE	抓取失败（DNS/TLS/超时）或返回 5xx。不作出拦截判定。

MCP 服务

通过 npm 使用（无需安装，PATH 中需要 Node 20+ 和 Python 3.11+； 该软件包是基于同一份 Python 标准库代码的轻量启动器）：

npx -y @reneturcios/wallcheck mcp
# the same shim also forwards the CLI:
npx -y @reneturcios/wallcheck probe https://example.com

或从此仓库使用：

PYTHONPATH=src python3 -m wallcheck mcp
# or, installed: wallcheck-mcp

工具：

• probe_url(url, timeout?)：实时获取 → 分类对象。
• classify(status, headers, body)：对你自行捕获的响应进行离线分类。不联网。
• scan_exposure(url, timeout?)：实时获取 → 分类对象，以及一个暴露内容部分（页面提供的类似密钥材料，经过分类且仅显示指纹）。执行一次真实 GET，遵循与 probe_url 相同的限制；涵盖探测器的 64 KB 响应体样本。
• audit(domain, timeout?)：所有者侧 Agent 访问审计：给出评级和逐项检查的 PASS/WARN/FAIL。对单个域名最多执行 11 次真实 GET，遵循与 probe_url 相同的有界获取规则。

将其添加到 MCP 客户端配置中，作为通过任一命令运行的 stdio 服务，或通过 Docker 使用 GHCR 镜像 ghcr.io/cloudcorprecords/wallcheck:0.5.0（参见 Dockerfile）。

测试

完全离线：使用记录的夹具测试纯分类器：

python3 -m unittest discover -s tests -v

贡献证据

validation/ 下捕获的响应属于证据，发布前会对证据进行清理：每次新增一批捕获数据后，先运行 python3 scripts/scrub_captures.py。 页面提供的内容中嵌入了其他站点的密钥材料；清理工具的脱敏表就是暴露扫描器使用的模式表，因此扫描器能找到的内容都会被清理工具移除。私密披露材料（validation/monster-finding/）和未发布的候选发现（validation/exposure-wave*/）永不发布——这两个路径特意加入了 gitignore。

同系列项目

作者：Rene Turcios。它与 greenlight（在认定问题之前先核实：基于证据作出 GO/NO-GO）和 mcpaudit（对任意 MCP 服务进行评分审计）是同系列项目。遵循相同的基本原则：核心逻辑确定性、问题有明确名称、证据胜过主观感受；在认定任何问题之前，先用真实目标进行实测。

完整的产品规范、路线图（Web Bot Auth 签名作为 v0.2 原型推出；所有者侧审计在 v0.3 推出）以及 Bot Wall Index 计划：参见 SPEC.md。验证轮次记录在 validation/ 中：第 2 轮增加了对 77 个平台路径的深度探测（PATHS.md）和签名原型（SIGNING.md）；第 3 轮增加了稳定性复测、包含 154 个站点的索引，以及审计的首次实测（AUDITS.md）。第 4 轮增加了第三个稳定性数据点（STABILITY-2.md）、签名 Agent 目录普查（DIRECTORY.md）和 Ed25519。第 5 轮扩展了覆盖范围，增加了签名与未签名的对比实验，以及所有者修复工具包；第 6 轮针对 25 种对抗性形态强化了分类器；第 7 轮将索引扩展到 499 个站点，进行了第二次目录普查（4 个采用者）和一次审计扫描；第 8 轮在另外 46 个平台上探测了路径，并将 front-doors 文件扩展到 65 个平台。第 9 轮发布了 0.5.0-rc，并添加了审计 MCP 工具；第 10 至第 28 轮又进行了 19 轮稳定性测试（第 6 至第 24 轮）和 v2 至 v20 对抗性测试组，将测试套件扩展到 885 项测试，并继续暂缓发布。

许可证

MIT：参见 LICENSE。