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.

Blocking a User-Agent

yield* Cloudflare.UaRule("BlockScraper", {
  zoneId: zone.zoneId,
  userAgent: "BadBot/1.2 (+http://badbot.example)",
  mode: "block",
  description: "aggressive scraper",
});

Challenging a User-Agent

yield* Cloudflare.UaRule("ChallengeOldClient", {
  zoneId: zone.zoneId,
  userAgent: "LegacyApp/0.9",
  mode: "managed_challenge",
});

Pausing a rule

yield* Cloudflare.UaRule("BlockScraper", {
  zoneId: zone.zoneId,
  userAgent: "BadBot/1.2 (+http://badbot.example)",
  mode: "block",
  paused: true,
});