Deploy a WAF managed ruleset via API (account)

Note

This feature requires an Enterprise plan with a paid add-on.

Use the Rulesets API to deploy a WAF managed ruleset to the http_request_firewall_managed phase at the account level.

The WAF Managed Rules page includes the IDs of the different WAF managed rulesets. You will need this information when deploying rulesets via API.

Example

The following example deploys a WAF managed ruleset to the http_request_firewall_managed phase of a given account ({account_id}) by creating a rule that executes the managed ruleset. The rules in the managed ruleset are executed when the zone name matches one of example.com or anotherexample.com.

1. Invoke the Get an account entry point ruleset operation to obtain the definition of the entry point ruleset for the http_request_firewall_managed phase. You will need the account ID for this task.

   curl "https://api.cloudflare.com/client/v4/accounts/{account_id}/rulesets/phases/http_request_firewall_managed/entrypoint" \
   --header "Authorization: Bearer <API_TOKEN>"

   {
     "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_managed",
       "rules": [
         // ...
       ],
       "source": "firewall_managed",
       "version": "10"
     },
     "success": true,
     "errors": [],
     "messages": []
   }

2. If the entry point ruleset already exists (that is, if you received a 200 OK status code and the ruleset definition), take note of the ruleset ID in the response. Then, invoke the Create an account ruleset rule operation to add an execute rule to the existing ruleset deploying the Cloudflare Managed Ruleset (with ID efb7b8c949ac4650a09736fc376e9aee). By default, the rule will be added at the end of the list of rules already in the ruleset.

   curl "https://api.cloudflare.com/client/v4/accounts/{account_id}/rulesets/{ruleset_id}/rules" \
   --header "Authorization: Bearer <API_TOKEN>" \
   --header "Content-Type: application/json" \
   --data '{
     "action": "execute",
     "action_parameters": {
       "id": "efb7b8c949ac4650a09736fc376e9aee"
     },
     "expression": "(cf.zone.name in {\"example.com\" \"anotherexample.com\"}) and cf.zone.plan eq \"ENT\"",
     "description": "Execute the Cloudflare Managed Ruleset"
   }'

   {
     "result": {
       "id": "<RULESET_ID>",
       "name": "Account-level phase entry point",
       "description": "",
       "kind": "root",
       "version": "11",
       "rules": [
         // ... any existing rules
         {
           "id": "<RULE_ID>",
           "version": "1",
           "action": "execute",
           "action_parameters": {
             "id": "efb7b8c949ac4650a09736fc376e9aee",
             "version": "latest"
           },
           "expression": "(cf.zone.name in {\"example.com\" \"anotherexample.com\"}) and cf.zone.plan eq \"ENT\"",
           "description": "Execute the Cloudflare Managed Ruleset",
           "last_updated": "2024-03-18T18:30:08.122758Z",
           "ref": "<RULE_REF>",
           "enabled": true
         }
       ],
       "last_updated": "2024-03-18T18:30:08.122758Z",
       "phase": "http_request_firewall_managed"
     },
     "success": true,
     "errors": [],
     "messages": []
   }

   Warning

   Managed rulesets deployed at the account level will only apply to incoming traffic of zones on an Enterprise plan. The expression of your execute rule must end with and cf.zone.plan eq "ENT" or else the API operation will fail.

3. If the entry point ruleset does not exist (that is, if you received a 404 Not Found status code in step 1), create it using the Create an account ruleset operation. Include a single rule in the rules array that executes the Cloudflare Managed Ruleset (with ID efb7b8c949ac4650a09736fc376e9aee) for all incoming requests where the zone name matches one of example.com or anotherexample.com.

   curl "https://api.cloudflare.com/client/v4/accounts/{account_id}/rulesets" \
   --header "Authorization: Bearer <API_TOKEN>" \
   --header "Content-Type: application/json" \
   --data '{
     "name": "My ruleset",
     "description": "Entry point ruleset for WAF managed rulesets",
     "kind": "root",
     "phase": "http_request_firewall_managed",
     "rules": [
       {
         "action": "execute",
         "action_parameters": {
           "id": "efb7b8c949ac4650a09736fc376e9aee"
         },
         "expression": "(cf.zone.name in {\"example.com\" \"anotherexample.com\"}) and cf.zone.plan eq \"ENT\"",
         "description": "Execute the Cloudflare Managed Ruleset"
       }
     ]
   }'

Next steps

To customize the behavior of the rules included in a managed ruleset, create an override.

To skip the execution of WAF managed rulesets or some of their rules, create an exception (also called a skip rule).

Exceptions have priority over overrides.

More resources

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