Create a custom ruleset using the API

import { Render, APIRequest } from "~/components";

:::note This feature requires an Enterprise plan. :::

Quota limits

Account-level custom rulesets have the following quota limits:

• Maximum rulesets: 10
• Maximum rules per ruleset: 100
• Total rule quota: 1,000 rules across all rulesets on the request path

The total rule quota of 1,000 rules is a hard limit that applies to all plans and cannot be increased. This limit applies across all rulesets that a request traverses, not just account-level custom rulesets.

Redistribute rules across rulesets

If you need to change the distribution of rules across your rulesets (for example, to create fewer rulesets with more rules per ruleset), contact Cloudflare Support. Only Cloudflare Support can update account-level entitlements to change the ruleset and rule distribution.

Before contacting Support, consider the following optimizations:

• Consolidate rules: Combine rules with similar conditions or actions into a single rule with broader matching criteria.
• Remove unused rules: Audit your rulesets and remove rules that are no longer triggering or are duplicating functionality.
• Use IP lists: Instead of creating multiple rules for individual IP addresses, use IP lists to group IPs and reference them in a single rule.

To deploy custom rules at the account level:

1. Create a custom ruleset with one or more rules. Alternatively, identify the existing custom ruleset you want to deploy using the List account rulesets API operation.
2. Deploy the custom ruleset so that it gets executed. To deploy a custom ruleset, create a rule with the execute action.

Use the Rulesets API to work with custom rulesets using the API.

If you are using Terraform, refer to WAF custom rules configuration using Terraform.

Procedure

To deploy a custom ruleset, follow these general steps:

1. Create a custom ruleset in the http_request_firewall_custom phase with one or more rules.
2. Deploy the ruleset to the entry point ruleset of the http_request_firewall_custom phase.

1. Create a custom ruleset

The following example creates a custom ruleset at the account level with a single rule in the rules array.

<APIRequest path="/accounts/{account_id}/rulesets" method="POST" json={{ description: "", kind: "custom", name: "My custom ruleset", rules: [ { description: "Challenge web traffic (not /api)", expression: 'not starts_with(http.request.uri.path, "/api/")', action: "managed_challenge", }, ], phase: "http_request_firewall_custom", }} roles="account" />

Save the ruleset ID in the response for the next step.

2. Deploy the custom ruleset

To deploy the custom ruleset, add a rule with "action": "execute" to the http_request_firewall_custom phase entry point ruleset.

1. <Render file="rulesets/api-account/step1-get-entrypoint" product="waf" params={{ phaseName: "http_request_firewall_custom" }} />

   <APIRequest path="/accounts/{account_id}/rulesets/phases/{ruleset_phase}/entrypoint" method="GET" parameters={{ ruleset_phase: "http_request_firewall_custom", }} roles="account" />

   {
   	"result": {
   		"description": "Account-level phase entry point",
   		"id": "<RULESET_ID>",
   		"kind": "root",
   		"last_updated": "2024-03-16T15:40:08.202335Z",
   		"name": "root",
   		"phase": "http_request_firewall_custom",
   		"rules": [
   			// ...
   		],
   		"version": "9"
   	},
   	"success": true,
   	"errors": [],
   	"messages": []
   }
   

2. <Render file="rulesets/api-account/step2-create-rule" product="waf" params={{ deploymentItem: "custom ruleset", }} />

   The following request creates a rule that executes the custom ruleset with ID <CUSTOM_RULESET_ID> for all Enterprise zones in the account:

   <APIRequest path="/accounts/{account_id}/rulesets/{ruleset_id}/rules" method="POST" json={{ description: "Execute custom ruleset", expression: '(cf.zone.plan eq "ENT")', action: "execute", action_parameters: { id: "<CUSTOM_RULESET_ID>", }, enabled: true, }} roles="account" />

   :::caution At the account level, you can only apply custom rulesets to incoming traffic of zones on an Enterprise plan. To enforce this requirement, you must include cf.zone.plan eq "ENT" in the expression of the execute rule deploying the custom ruleset. :::

3. <Render file="rulesets/api-account/step3-create-ruleset" product="waf" params={{ deploymentItem: "custom ruleset", scope: "all incoming requests of Enterprise zones in your account", }} />

   <APIRequest path="/accounts/{account_id}/rulesets" method="POST" json={{ description: "", kind: "root", name: "Account-level phase entry point", rules: [ { action: "execute", expression: '(cf.zone.plan eq "ENT")', action_parameters: { id: "<CUSTOM_RULESET_ID>", }, }, ], phase: "http_request_firewall_custom", }} roles="account" />

Next steps

Use the different operations in the Rulesets API to work with the custom ruleset you created and deployed. The following table has a list of common tasks for working with custom rulesets at the account level:

More resources

For instructions on creating a custom ruleset at the zone level via API, refer to Custom rulesets (zone level).

For more information on working with custom rulesets, refer to Work with custom rulesets in the Ruleset Engine documentation.