JSON object

Firewall rule object structure and properties

A fully populated firewall rule JSON object has the following structure:

{
  "id": "772bf1026a72c400ea576db1ffa16407",
  "filter": {
    "id": "6f58318e7fa2477a23112e8118c66f61",
    "expression": "http.request.uri.path ~ \"^.*/wp-login.php$\" or http.request.uri.path ~ \"^.*/xmlrpc.php$\""
    "paused": false,
    "description": "Wordpress login paths",
    "ref": ""
  },
  "action": "challenge",
  "priority": 1000,
  "paused": false,
  "description": "Protect blog login page",
  "ref": ""
}

The table below summarizes the JSON object properties. See also, Avoiding priority conflicts.

Property Description Value Notes
id - ID generated by Cloudflare 32-char UUIDv4 identifier - Unique
- Read-only
filter - An existing Cloudflare filter See the Cloudflare Filters guide - Required
action - The firewall action to perform log
allow
challenge
js_challenge
block
- Required
priority - The rule's priority
- Gets lowest priority if omitted

1 (highest)

2147483647 (lowest)

- Optional
- Read Avoiding priority conflicts
paused - Indicates if the rule is active

true

false

- Optional
- Default is false
description - To briefly describe the rule
- Omitted from object if empty
text

- Optional
- Default is empty

ref - Unique, user-supplied identifier or reference At user's discretion - Useful for identifying a rule if Cloudflare ID is unknown

Avoiding priority conflicts

Priority plays a key role in configuring firewall rules because of the power of Cloudflare Filters in contrast to previous Cloudflare Firewall functionality.

With Cloudflare Filters, it is possible to construct conflicting rules such as:

  • allow requests from the office IP range, and
  • block requests with a specific user agent.

Requests from the office IP range using the user agent to block would trigger both rules, but we cannot both allow and block the request. To solve this problem, the Firewall Rules follow a strict ordering depending on action and priority.

Cloudflare prioritizes rules in descending order, such that priority 1 is first and rules with no priority are last. For rules of equal priority, Cloudflare orders them by action using the following order of precedence:

  1. log
  2. allow
  3. challenge
  4. js_challenge
  5. block

In the example above if no priority is set, the allow request from the office IP range would apply because the allow action has a higher precedence than block.

To reduce the risk of unintended behavior, it’s best to explicitly specify the desired priority for potentially conflicting rules.