doctena-org/octorules-cloudflare
GitHub: doctena-org/octorules-cloudflare
这是一个通过 YAML 声明式配置来管理 Cloudflare 防火墙规则、列表及 Page Shield 策略的自动化工具。
Stars: 1 | Forks: 0
# octorules-cloudflare
[octorules](https://github.com/doctena-org/octorules) 的 Cloudflare 提供程序 — 以 YAML 格式管理 23 个 Cloudflare 规则阶段、自定义规则集、列表和 Page Shield 策略。
## 安装
```
pip install octorules-cloudflare
```
或通过 octorules 额外包安装：
```
pip install octorules[cloudflare]
```
这将安装 octorules（核心）、octorules-cloudflare 和
[octorules-wirefilter](https://github.com/doctena-org/octorules-wirefilter)
（Cloudflare wirefilter 引擎的 Rust FFI 桥接器，用于权威表达式解析和完整的 linter 覆盖）。
预构建的 wirefilter wheels 可用于 Linux（x86_64、aarch64；glibc 和 musl/Alpine）、macOS（x86_64、ARM64）和 Windows（x86_64）。
## 配置
```
providers:
cloudflare:
token: env/CLOUDFLARE_API_TOKEN
rules:
directory: ./rules
zones:
example.com:
sources:
- rules
```
`env/` 前缀在运行时从环境变量中解析值。
provider 部分下的所有键都作为关键字参数转发给 provider 构造函数
（octodns 风格的透传）。
### 身份验证
需要 [Cloudflare API token](https://developers.cloudflare.com/fundamentals/api/get-started/create-token/)
。该 token 需要以下权限：
- **Zone > Firewall Services > Edit** — 用于 ruleset 阶段操作
- **Account > Account Rulesets > Edit** — 用于账户级别规则和自定义规则集
- **Account > Account Filter Lists > Edit** — 用于列表管理
- **Zone > Page Shield > Edit** — 用于 Page Shield 策略管理
有关 API token 权限与 octorules 功能的详细映射，请参阅 [docs/permissions.md](docs/permissions.md)。
### Provider 设置
以下所有设置均位于 provider 部分下（例如 `providers.cloudflare`）。
| Key | 默认值 | 说明 |
|-----|---------|-------------|
| `token` | *(必填)* | Cloudflare API token（支持 `env/` 前缀） |
| `max_retries` | `2` | API 重试次数（0-10） |
| `timeout` | `30` | API 超时时间（秒），最大 300 |
安全阈值配置在 `safety:` 下（归框架所有，不转发给 provider）：
| Key | 默认值 | 说明 |
|-----|---------|-------------|
| `safety.delete_threshold` | `30.0` | 可删除的最大规则百分比 |
| `safety.update_threshold` | `30.0` | 可更新的最大规则百分比 |
| `safety.min_existing` | `3` | 阈值生效前的最少规则数 |
## 支持的功能
| 功能 | 状态 |
|---------|--------|
| Phase 规则（23 个阶段） | 已支持 |
| 自定义规则集（账户级别） | 已支持 |
| 列表（IP、ASN、主机名、重定向） | 已支持 |
| Page Shield 策略（Zone 级别） | 已支持 |
| Zone 发现 (`list_zones`) | 已支持 |
| 账户级别作用域 | 已支持 |
| 审计 IP 提取 (`octorules audit`) | 已支持 |
| Bot Management 设置 (`cloudflare_bot_management`) | 已支持 |
| URL normalization 设置 (`cloudflare_url_normalization`) | 已支持 |
| Zone security defaults (`cloudflare_zone_security`) | 已支持 |
| Leaked Credential Check (`cloudflare_leaked_credential_check`) | 已支持 |
| Content Scanning / 反恶意软件 (`cloudflare_content_scanning`) | 已支持 |
## 支持的阶段
23 个 Cloudflare 阶段 — 18 个 HTTP 请求/响应阶段和 5 个网络级别（Magic Transit）阶段。阶段按固定顺序执行：
```
Request -> url_normalization -> redirect_rules -> url_rewrite_rules -> request_header_rules
-> origin_rules -> config_rules -> cache_rules
-> waf_custom_rules -> waf_managed_rules -> rate_limiting_rules
-> bot_fight_rules -> http_ddos_rules
-> Origin fetch <-
-> custom_error_rules -> response_header_rules -> compression_rules
-> sensitive_data_detection -> log_custom_fields -> Response
```
具有默认操作的阶段（例如 `redirect_rules` -> `redirect`）不需要在 YAML 中指定 `action` — 它会自动注入。对于没有默认值的阶段（例如 `waf_custom_rules`），必须显式指定 `action`。
标记为同时适用于 Zone 和 Account 的阶段可在任一作用域下工作。仅限 Account 的阶段在 Zone 作用域下会被跳过，反之亦然，从而避免浪费 API 调用。
有关完整的阶段参考信息 — 执行顺序图、每个阶段的有效操作、字段/函数可用性以及关键行为 — 请参阅 [docs/lint/README.md](docs/lint/README.md)。
## 表达式语法
规则表达式使用 [Cloudflare 的 ruleset 表达式语言](https://developers.cloudflare.com/ruleset-engine/rules-language/expressions/)。当安装了 [octorules-wirefilter](https://github.com/doctena-org/octorules-wirefilter)（随 `octorules-cloudflare` 自动包含）时，表达式由 Cloudflare 实际的 wirefilter 引擎解析，提供权威的类型检查、字段验证和语法验证。如果没有它，基于正则的回退解析器会提取字段、函数、运算符和字面量，但无法执行类型检查。
Linter 会在启动时记录处于活动状态的解析器（`Expression parser: wirefilter` 或 `Expression parser: regex fallback`）。
## 自定义规则集（账户级别）
在账户级别，WAF 自定义规则和速率限制规则使用双层结构：阶段入口点包含 **部署规则**（`action: execute`），这些规则通过 ID 引用子级 **自定义规则集**。单独的阻止/日志记录规则位于这些子级规则集内部。
octorules 管理这两个层级。部署规则通过常规的阶段部分（`waf_custom_rules`、`rate_limiting_rules`）进行管理。每个自定义规则集内部的单独规则通过单独的 `custom_rulesets` 部分进行管理：
```
# Account rules file (e.g. rules/my-account.yaml)
# Deploy rules (phase entrypoint — references child rulesets by ID)
waf_custom_rules:
- ref: deploy-known-attackers
description: Deploy known attackers ruleset
action: execute
action_parameters:
id: abc12345def67890abc12345def67890
version: latest
enabled: true
expression: (http.host eq "api.example.com")
# Individual rules inside each custom ruleset
custom_rulesets:
- id: abc12345def67890abc12345def67890
name: Known attackers
phase: http_request_firewall_custom
rules:
- ref: block-bad-asn
description: Block by AS number
action: block
expression: (ip.geoip.asnum in {12345 67890})
- ref: block-bad-ua
description: Block by user-agent
action: block
expression: (http.user_agent contains "BadBot")
```
每个 `custom_rulesets` 条目中的 `id` 字段将其链接到部署规则的 `action_parameters.id`。内部规则使用 `ref` 进行标识（与阶段规则的模式相同）。每个规则必须显式指定 `action`。
使用 `octorules dump --scope account` 将现有的自定义规则集导出为 YAML。
## 列表（账户级别）
Cloudflare 账户级别的 [Lists](https://developers.cloudflare.com/waf/tools/lists/)（IP 列表、ASN 列表、主机名列表、重定向列表）可以通过 `$list_name` 语法在规则表达式中引用。octorules 以声明方式管理列表的完整生命周期：创建、删除、更新元数据以及管理项目。
在您的账户规则文件中添加顶级 `lists` 键：
```
# rules/my-account.yaml
lists:
- name: blocked_ips
kind: ip
description: "Known bad IPs"
items:
- ip: "1.2.3.4"
comment: "Scanner"
- ip: "5.6.7.0/24"
comment: "Botnet range"
- name: partner_asns
kind: asn
description: "Partner AS numbers"
items:
- asn: 12345
comment: "Partner A"
- asn: 67890
comment: "Partner B"
```
每个列表条目需要：
| 字段 | 说明 |
|-------|-------------|
| `name` | 列表名称 — 匹配 CF 列表名称和表达式中的 `$list_name` |
| `kind` | `ip`、`asn`、`hostname`、`redirect` 之一 |
| `description` | 可选 — 如果更改则更新 |
| `items` | 项目列表（可以为空 `[]` 以清除所有项目） |
**工作原理：**
- 存在 `lists:` 键意味着管理所有列表 — Cloudflare 中不在 YAML 中的列表计划删除（受安全阈值限制）。
- 如果缺少 `lists:` 键，则完全忽略列表。
- 项目更新是异步的 — octorules 轮询批量操作直到完成。
- 同步期间，列表在规则集和阶段**之前**应用，因此新创建的列表可供引用它们的规则表达式使用。
- 使用 `octorules dump --scope account` 将现有列表导出为 YAML。dump 会将列表项目外部化到单独的文件中（通过 `!include` 标签引用），位于 `providers.lists.directory` 下（默认：`{rules_dir}/custom_lists`）。
在规则表达式中引用列表：
```
waf_custom_rules:
- ref: block-bad-ips
description: Block IPs from blocklist
action: block
expression: (ip.src in $blocked_ips)
```
## Page Shield 策略（Zone 级别）
Cloudflare [Page Shield](https://developers.cloudflare.com/page-shield/) 在 Zone 级别管理内容安全策略（CSP）。octorules 以声明方式管理 Page Shield 策略的完整生命周期：创建、更新和删除。
在您的 Zone 规则文件中添加顶级 `page_shield_policies` 键：
```
# rules/example.com.yaml
page_shield_policies:
- description: "CSP on all example.com"
action: allow
expression: "true"
enabled: true
value: >-
script-src 'self' 'unsafe-inline' 'unsafe-eval' https:;
worker-src 'self' blob:
- description: "Log CSP on staging"
action: log
expression: '(http.host eq "staging.example.com")'
enabled: true
value: "default-src 'self'"
```
每个策略条目需要：
| 字段 | 说明 |
|-------|-------------|
| `description` | 策略描述 — 用作匹配的身份键 |
| `action` | `allow` 或 `log` |
| `expression` | Cloudflare 过滤器表达式 |
| `enabled` | 布尔值 |
| `value` | CSP 指令字符串 |
**工作原理：**
- `description` 字段是身份键（类似于规则的 `ref` 和列表的 `name`）。策略通过描述在 YAML 和 Cloudflare 之间进行匹配。
- 存在 `page_shield_policies:` 键意味着管理所有策略 — Cloudflare 中不在 YAML 中的策略计划删除。
- 如果缺少 `page_shield_policies:` 键，则完全忽略策略。
- 同步期间，策略在列表**之后**以及自定义规则集和阶段**之前**应用。
- 使用 `octorules dump` 将现有 Page Shield 策略导出为 YAML。
**CSP 源规范化：** CSP 指令中源的顺序并不重要 — `script-src 'self' example.com` 和 `script-src example.com 'self'` 在语义上是相同的。octorules 在比较 `value` 字段之前规范化源顺序（在每个指令内按字母顺序排序），因此在 YAML 中重新排序源不会触发 Cloudflare 上的上游更改。您可以为了可读性自由地重新组织源，而不会引起同步。
## Linting
141 条 Cloudflare 特定的 lint 规则（CF 前缀），跨越 6 个范围：
| 范围 | 类别 | 规则数 |
|-------|----------|-------|
| CF001–CF026 | 结构与解析 | 26 |
| CF100–CF104 | 跨规则排序 | 5 |
| CF200–CF222 | 操作验证 | 23 |
| CF300–CF309 | 表达式、函数与类型 | 10 |
| CF400–CF476 | 领域特定（速率限制、缓存、配置、重定向、转换、源、page shield、列表） | 42 |
| CF500–CF545 | 计划限制、样式与值约束 | 35 |
有关完整的规则参考，请参阅 [docs/lint/README.md](docs/lint/README.md)。
## 开发
```
git clone git@github.com:doctena-org/octorules-cloudflare.git
cd octorules-cloudflare
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
ln -sf ../../scripts/hooks/pre-commit .git/hooks/pre-commit
```
Pre-commit hook 会在 `overlay.toml` 或 `pyproject.toml`
更改时自动重新生成 `schemas.json`（针对没有 wirefilter 的用户的冻结模式回退）。
有关完整的模式架构，请参阅 [docs/schemas.md](docs/schemas.md)。
## 许可证
octorules-cloudflare 采用 [Apache License 2.0](LICENSE) 许可。
标签：API集成, Cloudflare, DNS管理, MITRE ATT&CK, Page Shield, Python, Rust FFI, WAF, YAML配置, 可观测性, 可视化界面, 安全策略, 提示词设计, 无后门, 网络安全, 自动化运维, 规则集管理, 逆向工具, 防火墙规则, 隐私保护