Skip to content

Cloudflare.Firewall reference

AccessRule

Section titled “AccessRule”

Source: src/Cloudflare/Firewall/AccessRule.ts

A Cloudflare IP Access rule — block, challenge, or whitelist requests by IP, CIDR range, ASN, or country, either on a single zone or across the whole account.

A rule’s identity is its configuration (target + value) within a scope: Cloudflare rejects a second rule for the same configuration with a duplicate error, and the configuration cannot be changed after creation — only mode and notes are mutable. Changing configuration or moving the rule between zone and account scope triggers a replacement.

Safety: IP Access rules carry no ownership markers. When there is no prior state, read scans the scope for an existing rule with the same configuration and reports it as Unowned, so the engine refuses to take it over unless --adopt (or adopt(true)) is set.

AccessRule: Blocking an IP

Section titled “AccessRule: Blocking an IP”

Block a single IPv4 address on a zone

yield* Cloudflare.Firewall.AccessRule("BlockBadActor", {
  zoneId: zone.zoneId,
  configuration: { target: "ip", value: "198.51.100.4" },
  mode: "block",
  notes: "repeated credential stuffing",
});

Block a CIDR range account-wide

// No zoneId — the rule applies to every zone in the account.
yield* Cloudflare.Firewall.AccessRule("BlockScannerRange", {
  configuration: { target: "ip_range", value: "203.0.113.0/24" },
  mode: "block",
});

AccessRule: Challenging traffic

Section titled “AccessRule: Challenging traffic”
// `block` for country targets is Enterprise-only; challenges work on
// all plans.
yield* Cloudflare.Firewall.AccessRule("ChallengeCountry", {
  zoneId: zone.zoneId,
  configuration: { target: "country", value: "KP" },
  mode: "managed_challenge",
});

AccessRule: Whitelisting

Section titled “AccessRule: Whitelisting”
yield* Cloudflare.Firewall.AccessRule("AllowOffice", {
  zoneId: zone.zoneId,
  configuration: { target: "ip", value: "192.0.2.10" },
  mode: "whitelist",
  notes: "office egress IP",
});

Lockdown

Section titled “Lockdown”

Source: src/Cloudflare/Firewall/Lockdown.ts

A Cloudflare Zone Lockdown rule — restrict one or more URL patterns on a zone so that only an allow-list of IP addresses and CIDR ranges can access them. Every other visitor receives an “Access Denied” page.

Everything about a lockdown rule is mutable in place: urls, configurations, description, paused, and priority are all updated via PUT without replacing the rule. Only moving the rule to a different zone triggers a replacement.

Zone Lockdown is available on Pro plans and above, with per-plan rule quotas (Pro: 3, Business: 10, Enterprise: 200). Cloudflare rejects a second rule covering the same URLs with a duplicate error, so a rule’s URL set acts as its identity within a zone.

Safety: lockdown rules carry no ownership markers. When there is no prior state, read scans the zone for an existing rule with the same URL set and reports it as Unowned, so the engine refuses to take it over unless --adopt (or adopt(true)) is set.

Lockdown: Locking down a URL

Section titled “Lockdown: Locking down a URL”

Allow a single office IP to reach an admin panel

yield* Cloudflare.Firewall.Lockdown("AdminLockdown", {
  zoneId: zone.zoneId,
  urls: ["shop.example.com/admin*"],
  configurations: [{ target: "ip", value: "198.51.100.4" }],
  description: "only the office can reach /admin",
});

Allow a CIDR range across multiple URLs

yield* Cloudflare.Firewall.Lockdown("StaffOnly", {
  zoneId: zone.zoneId,
  urls: ["example.com/internal*", "example.com/staging*"],
  configurations: [
    { target: "ip_range", value: "203.0.113.0/24" },
    { target: "ip", value: "198.51.100.4" },
  ],
});

Lockdown: Pausing a rule

Section titled “Lockdown: Pausing a rule”
yield* Cloudflare.Firewall.Lockdown("AdminLockdown", {
  zoneId: zone.zoneId,
  urls: ["shop.example.com/admin*"],
  configurations: [{ target: "ip", value: "198.51.100.4" }],
  paused: true,
});

UaRule

Section titled “UaRule”

Source: src/Cloudflare/Firewall/UaRule.ts

A Cloudflare User Agent Blocking rule — block or challenge every request to a zone whose User-Agent header exactly matches a given string.

Everything about a UA rule is mutable in place: userAgent, mode, description, and paused are all updated via PUT without replacing the rule. Only moving the rule to a different zone triggers a replacement.

Cloudflare rejects a second rule for the same User-Agent string in a zone with a duplicate error, so the UA string acts as a rule’s identity. Plan quotas: Free 10, Pro 50, Business 250, Enterprise 1000 rules.

Safety: UA rules carry no ownership markers. When there is no prior state, read scans the zone for an existing rule with the same User-Agent string and reports it as Unowned, so the engine refuses to take it over unless --adopt (or adopt(true)) is set.

UaRule: Blocking a User-Agent

Section titled “UaRule: Blocking a User-Agent”
yield* Cloudflare.Firewall.UaRule("BlockScraper", {
  zoneId: zone.zoneId,
  userAgent: "BadBot/1.2 (+http://badbot.example)",
  mode: "block",
  description: "aggressive scraper",
});

UaRule: Challenging a User-Agent

Section titled “UaRule: Challenging a User-Agent”
yield* Cloudflare.Firewall.UaRule("ChallengeOldClient", {
  zoneId: zone.zoneId,
  userAgent: "LegacyApp/0.9",
  mode: "managed_challenge",
});

UaRule: Pausing a rule

Section titled “UaRule: Pausing a rule”
yield* Cloudflare.Firewall.UaRule("BlockScraper", {
  zoneId: zone.zoneId,
  userAgent: "BadBot/1.2 (+http://badbot.example)",
  mode: "block",
  paused: true,
});