← Ruleset Engine / ruleset-engine / managed-rulesets

Override a managed ruleset

To customize the behavior of a managed ruleset via API, override the ruleset at deployment. When you override a ruleset you specify changes to be executed on top of the default configuration. These changes take precedence over the ruleset's default behavior.

For example, to test a managed ruleset before enforcing it, consider executing the ruleset with all rules set to log instead of their default actions. To do this, override the configured behavior of the managed ruleset at the ruleset level, so that each rule uses the log action.

If you are using Terraform, refer to the following pages:

To define overrides in the Cloudflare dashboard, refer to the following resources:

Work with overrides

You can override a ruleset at three levels:

Ruleset overrides apply to all rules in the executed ruleset.
Tag overrides apply to all rules with a specific tag. For example, use a tag override to customize the Cloudflare Managed Ruleset so all rules with the wordpress tag are set to Block. If multiple tags have overrides and if a given rule has more than one of these tags, the tag overrides order determines the behavior. For rules tagged with multiple overridden tags, the last tag's overrides apply.
Rule overrides apply to specific rules in a managed ruleset, referenced by their Rule ID.

Specific overrides take precedence over more general ones, and rule overrides take precedence over tag overrides, which take precedence over ruleset overrides.

To apply an override for a managed ruleset:

Use one of the update ruleset operations to update your phase entry point ruleset.
Specify the overrides in the action_parameters of the rule that executes your managed ruleset.

"action_parameters": {
  "id": "<RULESET_ID>",
  "overrides": {
    // ruleset overrides
    "property-to-modify": "value",
    "property-to-modify": "value",
    // tag overrides
    "categories": [
      {
        "category": "<TAG_NAME>",
        "property-to-modify": "value",
        "property-to-modify": "value"
      }
    ],
    // rule overrides
    "rules": [
      {
        "id": "<RULE_ID>",
        "property-to-modify": "value",
        "property-to-modify": "value"
      }
    ]
  }
}

You can override the following rule properties:

"action"
"enabled"

Some managed rulesets may have additional override requirements, or they may allow you to override other rule properties. Check each Cloudflare product’s documentation for details.

Examples

Rule override example

The following PUT request adds a rule that executes a managed ruleset in the http_request_firewall_managed phase at the zone level, and defines a rule override to enable rule <RULE_ID> and set its action to log.

Required API token permissions

At least one of the following token permissions is required:

Response Compression Write
Config Settings Write
Dynamic URL Redirects Write
Cache Settings Write
Custom Errors Write
Origin Write
Managed headers Write
Zone Transform Rules Write
Mass URL Redirects Write
Magic Firewall Write
L4 DDoS Managed Ruleset Write
HTTP DDoS Managed Ruleset Write
Sanitize Write
Transform Rules Write
Select Configuration Write
Bot Management Write
Zone WAF Write
Account WAF Write
Account Rulesets Write
Logs Write
Logs Write

Update a zone entry point ruleset

curl "https://api.cloudflare.com/client/v4/zones/$ZONE_ID/rulesets/phases/http_request_firewall_managed/entrypoint" \
	--request PUT \
	--header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
	--json '{
		"description": "Deploy managed ruleset, enabling a specific rule with log action",
		"rules": [
				{
						"action": "execute",
						"expression": "true",
						"action_parameters": {
								"id": "<MANAGED_RULESET_ID>",
								"overrides": {
										"rules": [
												{
														"id": "<RULE_ID>",
														"enabled": true,
														"action": "log"
												}
										]
								}
						}
				}
		]
	}'

Ruleset override example

The following PUT request adds a rule that executes a managed ruleset in the http_request_firewall_managed phase at the account level, and defines a ruleset override that sets the action to log for all (enabled) rules.

Required API token permissions

At least one of the following token permissions is required:

Mass URL Redirects Write
Magic Firewall Write
L4 DDoS Managed Ruleset Write
Transform Rules Write
Select Configuration Write
Account WAF Write
Account Rulesets Write
Logs Write

Update an account entry point ruleset

curl "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/rulesets/phases/http_request_firewall_managed/entrypoint" \
	--request PUT \
	--header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
	--json '{
		"description": "Deploy managed ruleset for example.com, overriding the rules action to log",
		"rules": [
				{
						"action": "execute",
						"expression": "(cf.zone.name eq \"example.com\") and cf.zone.plan eq \"ENT\"",
						"action_parameters": {
								"id": "<MANAGED_RULESET_ID>",
								"overrides": {
										"action": "log"
								}
						}
				}
		]
	}'

More resources

For additional examples of configuring overrides via API, refer to Override examples.