fabianmossberg/cloudflare-block-and-challenge

# Cloudflare Block & Challenge 通过 git 仓库中的四个纯文本文件，集中管理所有 zone 的 Cloudflare IP/国家封锁。编辑文件，发起 PR，通过 PR 评论直观查看具体变更内容，合并后——变更即刻在所有配置好的 zone 上生效。 | 文件 | 内容 | Cloudflare 动作 | | ---- | --------------- | ----------------- | | `blocklist.txt` | IPs / CIDR 范围 | **Block** | | `block-countries.txt` | ISO 国家代码 | **Block** | | `challenge.txt` | IPs / CIDR 范围 | **Managed challenge** | | `challenge-countries.txt` | ISO 国家代码 | **Managed challenge** | Managed challenge 能够在快速校验后放行真实浏览器，并拦截大部分 bot —— 当你不确定时，建议优先使用它而非直接 block。 零依赖：仅需一个 Python 3.9+ 脚本 (`scripts/cfbc.py`)，只使用标准库。 ## 快速开始 1. 在 GitHub 上点击 **Use this template** 并克隆你的新仓库。 2. 获取一个 API token —— 你既可以让工具自动生成一个（它会要求输入你的 Global API Key 或 bootstrap token，仅使用一次且绝不存储）： python3 scripts/cfbc.py create-token 或者，前往 手动创建一个，需勾选 **Account Filter Lists: Edit**、**Zone WAF: Edit**、**Zone: Read** 权限（参见 `.env.example`），然后将其填入 `.env` 中。 3. 选择要管理的 zone： python3 scripts/cfbc.py setup 该命令会生成 `config.json` —— 请务必 **提交（commit）它**，因为它本就该纳入 git 管理。 4. 将 token 提供给 CI，这样 PR 就能获得 plan（计划）评论，并且合并时会触发部署： gh secret set CLOUDFLARE_API_TOKEN 5. 将一个 IP 添加到 `blocklist.txt` 中，然后执行： python3 scripts/cfbc.py check # 校验文件（离线执行） python3 scripts/cfbc.py plan # 只读：查看将要发生什么变更 python3 scripts/cfbc.py sync # 应用变更 ## 日常操作 在分支上编辑列表文件并打开 PR。CI 会校验文件，并将 `plan` 的输出作为评论发布在 PR 上，方便你在审查时直观查看具体的变更点。合并到 `master` 分支时会触发 `sync` —— 合并即部署。（你也可以在本地运行 `sync`；无论哪种方式，它都是幂等的。） ## 命令 | 命令 | 是否影响 Cloudflare？ | 功能描述 | | ------- | ------------------- | ------------ | | `setup` | 只读 | 交互式：选择账号和 zone，写入 `config.json`。随时可重新运行以添加/移除 zone。 | | `create-token` | 写入（生成 token） | 通过 Global API Key 或 bootstrap token 生成一个具备特定权限范围的 API token。 | | `check` | 否 | 校验列表文件和配置。用作 CI lint。 | | `list` | 只读 | 展示账号的 IP Lists 以及每个已配置 zone 的每条 WAF 自定义规则，并标记出受管理的规则。 | | `plan` | 只读 | 对比差异：展示 `sync` 将要创建/接管/更新的内容。 | | `sync` | **写入** | 执行应用。这是唯一会修改 Cloudflare 配置的命令。 | ## 工作原理 - 每个 IP 文件都会同步到一个名为 `_block` 或 `_challenge` 的 **账号级 IP List**（前缀在 `setup` 时指定，默认为 `cfbc`）。 - `config.json` 中的每个 zone 都会在 "custom rules" 阶段获得 **每份列表对应的一条 WAF 自定义规则**，例如： `(ip.src in $cfbc_challenge) or (ip.src.country in {"CN" "SG"})`。 国家代码会被整合进同一条规则的表达式中。 - Block 规则的创建优先于 challenge 规则，因此当某个 IP 或国家同时出现在两者中时，**Block 优先**。 - 该工具通过表达式中的 `$` 引用来识别“自身管理的”规则。其他的任何内容 —— 即你其余的自定义规则 —— **绝不会被动**。 - 同步（Sync）是幂等的：它会核对 action、表达式、启用状态以及描述，如果没有任何变化，则什么也不做。 - Cloudflare 仪表板中的规则描述会标明源文件的位置，以防有人手动修改规则后被系统静默覆盖。 ## 管理 zone 与前缀 - **添加/移除 zone**：重新运行 `setup`。当前已配置的 zone 会被预先选中。注意：取消选中某个 zone 仅会保留其原有规则 —— 本工具绝不会干预 `config.json` 之外的 zone。如果确实需要清除，请在仪表板中手动删除那两条规则。 - **在一个账号上进行多重部署**（例如，两个仓库管理不同的 zone 集合）：请在 `setup` 时为它们分别指定不同的前缀，否则它们会互相接管对方的规则。 - **更改前缀**：原有的 `_*` 列表和规则不会被删除；`setup` 会发出警告并将它们列出，方便你在仪表板中手动清理。 - **没有专门的卸载（teardown）命令。** 如果想彻底停止管理某个 zone：请删除该 zone 上的两条 WAF 自定义规则，并且（当不再有任何 zone 使用它们时）删除 Account → Configurations → Lists 下的那两个 IP Lists。 ## 进阶：接管已有规则 如果某个 zone 已经存在一条你希望交由此工具接管的手工配置规则（而不是创建一条重复的规则），请在 `config.json` 中设置其完全一致的描述： ``` "adopt": { "block": "Block bad actors", "challenge": null } ``` 在下一次执行 `sync` 时，描述相匹配的规则会被原地转换以引用受管理的 list（如果处于禁用状态，也会被重新启用）。`plan` 会在你应用变更之前展示此次接管操作。 ## 限制与故障排除 - **免费版计划 (Free plan)**：每个 zone 支持 5 条自定义规则；本工具最多使用 2 条。IP Lists 适用于所有计划版本（免费版为 1 个列表 / 1 万个 IP —— 本工具占用 2 个列表，因此纯免费版账号可能需要升级付费版或改用内联规则）。 - **403 错误**：token 缺少某项权限 —— 请对照 `.env.example` 进行检查。 - **空文件**：只有当对应的文件中包含至少一个 IP 或国家时，系统才会创建规则；如果两者皆为空则会跳过（而已存在的规则会被原样保留）。 - **token 归属权**：`create-token` 生成的是 *用户归属（user-owned）* 的 token —— 它会随着用户账号的注销而失效。重视此问题的团队应当在仪表板中创建一个具备同样三项权限范围的账号归属（account-owned）token。 - **在某个 zone 上执行 `plan` 或 `sync` 失败**：可能是该 zone 已被删除或转移到了其他账号下 —— 请重新运行 `setup`。 ## 仓库内容 ``` blocklist.txt # block these IPs/CIDRs block-countries.txt # block these countries challenge.txt # challenge these IPs/CIDRs challenge-countries.txt # challenge these countries config.json # written by setup, committed (account, zones, prefix) scripts/cfbc.py # the tool (stdlib-only Python) .github/workflows/sync.yml # check+plan on PR, sync on merge .env # your API token (gitignored; see .env.example) ```

标签：Cloudflare, GitOps, MITRE ATT&CK, Python, WAF, 无后门, 网络访问控制, 自动化运维, 逆向工具