farukbagci/anti-bot-field-guide

# 反机器人字段指南 **你被拦截了。是什么拦截了你，你该怎么做？** [](https://github.com/farukbagci/anti-bot-field-guide/actions/workflows/ci.yml)   🇨🇳 [简体中文 README](README.tr.md) 这是一份诊断实地指南，针对你在公共网络上遇到的 anti-bot 产品：如何将它们与你已经得到的响应区分开来，每个产品到底检查了什么，以及如何区分临时验证和永久封禁。 这不是一个绕过限制的代码库。大多数花在“通过”拦截上的时间都花在了错误的问题上——人们在登录墙处频繁更换代理，给 proof-of-work 挑战添加 sleep，或者因为一个实际上是格式错误请求导致的 `403` 而重写客户端。首先要进行识别。 ``` python detect.py https://example.com # fetch it and say what answered python detect.py --from-json response.json # or replay a response you logged ``` 无额外依赖。仅使用标准库，要求 Python 3.9+。 ## 60秒内识别你的拦截者 在修改你的客户端任何内容之前，请按照以下顺序进行： 1. **保存整个响应。** 状态码、每一个响应头、完整的响应体。如果你只保存了状态码，你就丢弃了诊断依据。 2. **查看 `Set-Cookie` 的名称。** 不是值——而是名称。`__cf_bm`、`datadome`、`_abck`、`_px3`、`visid_incap_*` 和 `aws-waf-token`，每一个都能一眼认出其供应商。 3. **扫描响应头以寻找供应商特征。** `cf-ray`、`x-iinfo`、`x-kpsdk-ct`、`x-amzn-waf-action`、`server: AkamaiGHost`。 4. **查看 `…"} ``` 每个字段都是可选的。一条只有 `status` 的记录仍然可以生成报告。 ## detect.py ``` $ python detect.py https://example.com URL https://example.com/ Status 403 Body 4812 bytes Title Just a moment... Vendor Cloudflare (confidence: high, score 26) State challenge Matched signals - header cf-ray: 0000000000000000-XXX - header cf-mitigated: challenge - header server: cloudflare - cookie __cf_bm - body contains "cdn-cgi/challenge-platform" - body contains "just a moment..." - status 403 Next step Separate 'challenge' from 'firewall rule' before doing anything else. ... ``` 选项： | 标志 | 效果 | |---|---| | `--from-json FILE` | 读取已保存的响应而不是发起请求——一个包含 `status`、`headers`、`body`、`url` 的 JSON 对象。`-` 读取 stdin。完全不使用网络 | | `--json` | 机器可读的输出 | | `--verbose` | 同时打印每一个响应头——在捕获新签名时使用此选项 | | `--timeout N` | 秒数，默认值为 15 | | `--user-agent UA` | 覆盖 User-Agent。将诚实的 UA 与浏览器的 UA 进行比较本身就是一种诊断 | | `--no-redirect` | 在第一个响应处停止，以便能够看到进入等待室的 `302` | 默认的 `User-Agent` 如实标识了该工具。这是故意的：这是一个诊断工具，真实的请求能告诉你运营者的规则会对真实的客户端做什么。 退出代码：`0` 成功运行，`1` 请求失败，`2` 用法错误。 ### 作为库使用 `detect(status, headers, body, url=None)` 是纯粹的——没有 I/O 操作，不修改全局变量——因此你可以将其应用于来自任何 HTTP 客户端的响应，或者应用于你几周前捕获的日志。 ``` from detect import detect result = detect(response.status_code, response.headers, response.text) if result["state"] == "block": log.warning("hard block by %s: %s", result["vendor"], result["signals"]) elif result["state"] == "challenge": ... ``` `headers` 接受 dict、列表 dict、`(name, value)` 对列表，或 `http.client.HTTPMessage`。名称匹配不区分大小写，并会读取所有重复的 `Set-Cookie` Header。`body` 接受 `str` 或 `bytes`。`status` 接受 `int` 或 JSON 日志返回的字符串。 同样导出的有：`fetch(url, timeout=15.0, user_agent=..., follow_redirects=True)` → `(status, headers, body, urls)`，`load_record(path_or_dash)`，`format_report(result, url=None, headers=None, verbose=False)`，`normalize_headers(headers)`，`FetchError`，以及 `STATE_*` 常量。 返回的字段： | 字段 | 含义 | |---|---| | `vendor` | 得分最高的供应商名称，或 `None`。结合 `confidence` 一起解读——这里的 `low` 意味着“只有一个微弱的标记”，而不是“已确认” | | `confidence` | `high` / `medium` / `low` / `none`，源自累加的信号权重 | | `score` | 匹配到的信号的累加权重 | | `state` | `clear` / `challenge` / `block` / `queue` / `unknown` —— 描述**此响应**，而不是站点。只有置信度为 `medium` 或以上的供应商才能设置它 | | `signals` | 匹配内容的人类可读列表 | | `candidates` | 匹配到任何内容的每一个供应商，按得分排序 | | `next_step` | 如何应对。一旦实际上确认了供应商，内容就是特定的；而在证据微弱时，则提供通用建议 | | `hints` | 适合该响应的非 anti-bot 解释，并在最佳匹配微弱时给出警告 | | `title`, `body_length`, `status` | 值得记录 | `vendor` / `state` 的拆分很重要：一个站点可能位于 Cloudflare 之后，但仍然会交给你一个完全正常的页面。“存在 Cloudflare”和“Cloudflare 正在拦截我”是不同的调查结果，而混淆它们经常会让人们误入歧途。 添加一个供应商只需要在模块级别的 `VENDORS` 列表中添加一个条目——不需要更改其他代码。详见 [CONTRIBUTING.md](CONTRIBUTING.md)。 ## 范围和意图 本代码库用于在你被允许收集的数据上进行**识别和理解**。了解你面前的是什么，能让你做出明智的决定：请求 API 访问权限、降低访问速率、修复格式错误的请求，或者停止访问。上面的大多数条目最终都以“联系运营者”或“减速”结束，因为这确实是当前情况所需要的。 以下是你自己的责任，而不是本代码库的： - **`robots.txt` 和站点的服务条款。** 阅读它们。你有义务遵守。 - **访问数据的权限。** 在技术上能够抓取某些内容并不代表获得了授权。 - **速率和负载。** 封禁通常是站点在告诉你，你的访问让它付出了成本。 这里故意不提供的内容，也不接受作为贡献提交的内容： - CAPTCHA 解决服务集成 - 凭据处理、撞库或账户接管技术 - 付费墙或访问控制绕过 - 针对任何供应商的逐步规避方案 这些产品的存在主要是为了阻止欺诈、撞库和库存滥用。一份帮助你识别并做出适当响应的指南对大家都有用；而一份用于击败它们的“操作手册”不仅没有用，也不是本项目的主旨。 ## 客观局限性 - **本指南只做识别；不负责解决。** 对于大多数供应商来说，不存在配置上的捷径，坦率地承认这一点比假装有招更有用。 - **签名会漂移。** Cookie 名称、脚本路径和状态码都会改变，其中很多都是针对单个客户的配置。表中任何标记为“因配置而异”的内容确实会因配置而异。请根据你自己的抓包进行验证。 - **没有签名并不能证明什么。** 供应商可能存在且保持沉默。`detect.py` 只报告它匹配到了什么，从不说“这个站点没有受到保护”。 - **低置信度的匹配并不是一种识别。** 单个微弱的标记会被列为候选项并被标记为微弱。它从不设置响应状态，也绝不提供特定于供应商的建议——普通页面文案中的“waiting room”并不代表是一个队列，而“just a moment”这几个词也不代表是 Cloudflare 挑战。 - **单个响应只是一个狭窄的视角。** 有些产品只会在第二次请求、POST 请求、或者 XHR（而不是文档加载）中显露身份。 - **这里不包含行为或 TLS。** 提到 JA3/JA4 和 HTTP/2 指纹是因为它们是这些产品检查的内容，但是测量你自己的指纹需要标准库脚本之外的工具。 - **深度参差不齐。** 有些部分来自持续的生产实践，有些则来自极少的接触。在我不太确定的地方，措辞都会如实表达——“因配置而异”、“通常”、“实地观察”。欢迎并会合并修正意见。 ## 相关工具 为了一个 pipeline 构建的五个代码库，它们依然可以作为一个整体被解读。本指南告诉你你面临的是什么，`cloudflare-bypass-toolkit` 处理最常见的应对方案，`scraper-skeleton` 执行任务，`proxy-pool` 提供地址，而 `jsonl-qc` 决定交付的结果是否合格。 | 代码库 | 功能 | |---|---| | [cloudflare-bypass-toolkit](https://github.com/farukbagci/cloudflare-bypass-toolkit) | 如果应对方案是针对 Cloudflare：用真实的浏览器通过一次挑战，然后在没有浏览器的情况下重放 | | [scraper-skeleton](https://github.com/farukbagci/scraper-skeleton) | 编排层：有限的并发、重试、崩溃后恢复、计数对账 | | [proxy-pool](https://github.com/farukbagci/proxy-pool) | 为运行器提供地址，并针对被禁用的地址提供每次失败后的冷却机制 | | [jsonl-qc](https://github.com/farukbagci/jsonl-qc) | 验证输出的结果：schema、填充率、重复项、基线漂移——告诉你如何捕获那 27% 被静默丢失的数据 | ## 贡献 添加一个供应商只需在 `VENDORS` 中添加一个 dict 和一个测试。这是主要的贡献途径，并在 [CONTRIBUTING.md](CONTRIBUTING.md) 中有逐步文档说明。同样欢迎对现有签名进行修正——准确性是本代码库的全部价值所在。 ``` python -m pytest tests/ -q ``` ## 许可证 MIT —— 详见 [LICENSE](LICENSE)。

标签：Python, WAF识别, Web诊断, 反爬虫, 文档结构分析, 无后门, 网络请求分析, 逆向工具