Deploy a WAF managed ruleset via API

Use the Rulesets API to deploy a managed ruleset at the account level or at the zone level.

Deploy WAF managed rulesets to the http_request_firewall_managed phase. Other managed rulesets, like DDoS Attack Protection managed rulesets, must be deployed to a different phase. Refer to the specific managed ruleset documentation for details.

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

Example

The following example deploys a WAF managed ruleset to the http_request_firewall_managed phase of a given zone ({zone_id}) by creating a rule that executes the managed ruleset.

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

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

   {
     "result": {
       "description": "Zone-level phase entry point",
       "id": "<RULESET_ID>",
       "kind": "zone",
       "last_updated": "2024-03-16T15:40:08.202335Z",
       "name": "zone",
       "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 a zone 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/zones/{zone_id}/rulesets/{ruleset_id}/rules" \
   --header "Authorization: Bearer <API_TOKEN>" \
   --header "Content-Type: application/json" \
   --data '{
   "action": "execute",
   "action_parameters": {
   "id": "efb7b8c949ac4650a09736fc376e9aee"
   },
   "expression": "true",
   "description": "Execute the Cloudflare Managed Ruleset"
   }'

   {
     "result": {
       "id": "<RULESET_ID>",
       "name": "Zone-level phase entry point",
       "description": "",
       "kind": "zone",
       "version": "11",
       "rules": [
         // ... any existing rules
         {
           "id": "<RULE_ID>",
           "version": "1",
           "action": "execute",
           "action_parameters": {
             "id": "efb7b8c949ac4650a09736fc376e9aee",
             "version": "latest"
           },
           "expression": "true",
           "description": "Execute the Cloudflare Managed Ruleset",
           "last_updated": "2024-03-18T18:08:14.003361Z",
           "ref": "<RULE_REF>",
           "enabled": true
         }
       ],
       "last_updated": "2024-03-18T18:08:14.003361Z",
       "phase": "http_request_firewall_managed"
     },
     "success": true,
     "errors": [],
     "messages": []
   }

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 a zone ruleset operation. Include a single rule in the rules array that executes the Cloudflare Managed Ruleset (with ID efb7b8c949ac4650a09736fc376e9aee) for all incoming requests in the zone.

   curl "https://api.cloudflare.com/client/v4/zones/{zone_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": "zone",
     "phase": "http_request_firewall_managed",
     "rules": [
       {
         "action": "execute",
         "action_parameters": {
           "id": "efb7b8c949ac4650a09736fc376e9aee"
         },
         "expression": "true",
         "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.