octorules-cloudflare

Cloudflare provider for octorules — manages 23 Cloudflare rule phases, custom rulesets, lists, and Page Shield policies as YAML.

Installation

pip install octorules-cloudflare

This installs octorules (core), octorules-cloudflare, and octorules-wirefilter (Rust FFI bridge to Cloudflare's wirefilter engine for authoritative expression parsing and full linter coverage).

Prebuilt wirefilter wheels are available for Linux (x86_64, aarch64; glibc and musl/Alpine), macOS (x86_64, ARM64), and Windows (x86_64).

Configuration

providers:
  cloudflare:
    token: env/CLOUDFLARE_API_TOKEN
  rules:
    directory: ./rules

zones:
  example.com:
    sources:
      - rules

The env/ prefix resolves values from environment variables at runtime. All keys under the provider section are forwarded to the provider constructor as keyword arguments (octodns-style passthrough).

Authentication

A Cloudflare API token is required. See docs/permissions.md for the full list of required permissions per phase and extension.

Provider settings

All settings below go under the provider section (e.g. providers.cloudflare).

Safety thresholds are configured under safety: (framework-owned, not forwarded to the provider):

Examples

The examples/ directory contains a working single-provider config.yaml plus rules files: rules/example.com.yaml (zone-level) and rules/example-account.yaml (account-level, including the five Magic Transit / Layer-4 phases, whose packet-level expressions are validated against octorules-wirefilter's L4 scheme). Together they exercise every supported phase and key. Copy them as a starting point.

All Cloudflare sections (phases, settings, lists, and policies) nest under a single cloudflare: block.

Supported features

Supported phases

23 Cloudflare phases — 18 HTTP request/response phases and 5 network-level (Magic Transit) phases. Phases execute in a fixed order:

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

Phases with a default action (e.g., redirect_rules -> redirect) don't need action in the YAML — it's injected automatically. For phases without a default (e.g., waf_custom_rules), you must specify action explicitly.

Phases marked as both Zone and Account work at either scope. Account-only phases are skipped for zone scopes and vice versa, eliminating wasted API calls.

For the full phase reference — execution order diagram, valid actions per phase, field/function availability, and key behaviors — see docs/lint/README.md.

Expression syntax

Rule expressions use Cloudflare's ruleset expression language. Expressions are parsed by Cloudflare's actual wirefilter engine via octorules-wirefilter — a required dependency, installed automatically with octorules-cloudflare — providing authoritative type checking, field validation, and syntax verification.

Rule-level metadata: All Cloudflare rules support the octorules: key for per-rule metadata — ignored: true to skip a rule during plan/sync, and included/excluded to restrict rules to specific providers. See octorules core docs for syntax and examples.

Custom rulesets (account-level)

At the account level, WAF custom rules and rate limiting rules use a two-tier structure: the phase entrypoint contains deploy rules (action: execute) that reference child custom rulesets by ID. The individual blocking/logging rules live inside those child rulesets.

octorules manages both tiers. Deploy rules are managed via the normal phase sections (waf_custom_rules, rate_limiting_rules). The individual rules inside each custom ruleset are managed via a separate custom_rulesets section:

# Account rules file (e.g. rules/my-account.yaml)
cloudflare:
  # 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")

The id field in each custom_rulesets entry links it to the deploy rule's action_parameters.id. Rules inside use ref for identification (same pattern as phase rules). Every rule must specify an action explicitly.

Use octorules dump --scope account to export existing custom rulesets to YAML.

Note: octorules manages rules within existing custom rulesets. Creating or deleting rulesets themselves must be done via the Cloudflare dashboard. Zone-level rulesets do not have kind=custom children — this is account-level only.

Lists (account-level)

Cloudflare account-level Lists (IP lists, ASN lists, hostname lists, redirect lists) can be referenced in rule expressions via $list_name syntax. octorules manages full lifecycle of lists declaratively: create, delete, update metadata, and manage items.

Add a lists key under the cloudflare: block of your account rules file:

# rules/my-account.yaml
cloudflare:
  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"

Each list entry requires:

How it works:

• The presence of a lists: key means ALL lists are managed — lists in Cloudflare not in YAML are planned for deletion (subject to safety thresholds).
• If the lists: key is absent, lists are ignored entirely.
• Item updates are asynchronous — octorules polls the bulk operation until completion.
• During sync, lists are applied before rulesets and phases, so newly created lists are available for rule expressions that reference them.
• Use octorules dump --scope account to export existing lists to YAML. The dump externalizes list items into separate files (referenced via !include tags) under providers.lists.directory (default: {rules_dir}/custom_lists).

Reference lists in rule expressions:

cloudflare:
  waf_custom_rules:
    - ref: block-bad-ips
      description: Block IPs from blocklist
      action: block
      expression: (ip.src in $blocked_ips)

Page Shield policies (zone-level)

Cloudflare Page Shield manages Content Security Policies (CSP) at the zone level. octorules manages full lifecycle of Page Shield policies declaratively: create, update, and delete.

Add a page_shield_policies key under the cloudflare: block of your zone rules file:

# rules/example.com.yaml
cloudflare:
  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'"

Each policy entry requires:

How it works:

• The description field is the identity key (like ref for rules and name for lists). Policies are matched between YAML and Cloudflare by description.
• The presence of a page_shield_policies: key means ALL policies are managed — policies in Cloudflare not in YAML are planned for deletion.
• If the page_shield_policies: key is absent, policies are ignored entirely.
• During sync, policies are applied after lists and before custom rulesets and phases.
• Use octorules dump to export existing Page Shield policies to YAML.

CSP source normalization: The order of sources within a CSP directive is not significant — script-src 'self' example.com and script-src example.com 'self' are semantically identical. octorules normalizes source order (sorted alphabetically within each directive) before comparing value fields, so reordering sources in your YAML will not trigger an upstream change on Cloudflare. You can freely reorganize sources for readability without causing a sync.

Linting

162 Cloudflare-specific lint rules (CF prefix) across 6 ranges:

See docs/lint/README.md for the full rule reference.

Development

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]"
pre-commit install

The pre-commit hook runs ruff (check + format) and yamllint. See docs/schemas.md for the schema architecture — octorules-wirefilter provides the field/function data and is a required dependency (there is no frozen fallback).

License

octorules-cloudflare is licensed under the Apache License 2.0.