[WAF] Custom rulesets at zone level (#26765)

---------

Co-authored-by: Kate Tungusova <70746074+deadlypants1973@users.noreply.github.com>

Author: pedrosousa

public/__redirects

@@ -2403,7 +2403,6 @@
 # WAF
 /waf/managed-rulesets/* /waf/managed-rules/:splat 301
 /waf/custom-rulesets/* /waf/account/custom-rulesets/:splat 301
-/waf/custom-rules/custom-rulesets/* /waf/account/custom-rulesets/:splat 301
 /waf/exposed-credentials-check/* /waf/managed-rules/check-for-exposed-credentials/:splat 301
 /waf/security-events/* /waf/analytics/security-events/:splat 301
 /waf/change-log/2019-* /waf/change-log/historical-2019/ 301

src/content/docs/bots/concepts/feedback-loop.mdx

@@ -41,7 +41,7 @@ If Cloudflare is unable to detect a portion of automated traffic on your site, s
 
 ## Submit a report
 
-<Tabs syncKey="dashNewNav"> 
+<Tabs syncKey="dashNewNav">
   <TabItem label="Old dashboard">
     <Steps>
       1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com/), and select your account and domain.
@@ -50,7 +50,7 @@ If Cloudflare is unable to detect a portion of automated traffic on your site, s
       4. Select **Report incorrect data** and fill out the form.
       5. Select **Submit**.
     </Steps>
-  </TabItem> 
+  </TabItem>
   <TabItem label="New dashboard" icon="rocket">
     <Steps>
       1. In the Cloudflare dashboard, go to the **Security Analytics** page.
@@ -61,7 +61,7 @@ If Cloudflare is unable to detect a portion of automated traffic on your site, s
       4. Select **Report incorrect data** and fill out the form.
       5. Select **Submit**.
     </Steps>
-  </TabItem> 
+  </TabItem>
 </Tabs>
 
 ## Via the API
@@ -224,17 +224,15 @@ We appreciate any comments you wish to leave in the description field that might
 ## Recommendations after submitting a false positive
 
 :::note
-
-The instructions below apply to Enterprise subscription with Bot Management only. 
+The instructions below apply to Enterprise subscription with Bot Management only.
 :::
 
-After submitting a false positive, you can explicitly allow the traffic if you are confident that this traffic source cannot be used for abuse in the future. To allow traffic, you can create a WAF custom rule with a [Skip the remaining custom rules](/waf/custom-rules/skip/options/) action that matches the characteristics of your false positive report. We recommend any skip rule that you create uses the most narrow possible scope, including restricting the request methods and URIs that the expected traffic has access to, to limit potential abuse.
+After submitting a false positive, you can explicitly allow the traffic if you are confident that this traffic source cannot be used for abuse in the future. To allow traffic, you can create a WAF custom rule with a [Skip the remaining custom rules](/waf/custom-rules/skip/options/#skip-the-remaining-custom-rules-current-ruleset) action that matches the characteristics of your false positive report. We recommend any skip rule that you create uses the most narrow possible scope, including restricting the request methods and URIs that the expected traffic has access to, to limit potential abuse.
 
 * Allowing a **[JA3/JA4 fingerprint](/bots/additional-configurations/ja3-ja4-fingerprint/)**:  If you want to allow access to a stable software client that does not come from a dedicated IP, you can do so by looking up the JA3 fingerprint(s) used by that client in the Bot Analytics dashboard, and creating a WAF custom rule to allow traffic based on that JA3 fingerprint. JA3 fingerprints will only match a client’s TLS library, so be cautious in looking for both overlap with other clients and with variation based on the operating system. <br/><br/>Cloudflare does not recommend relying on JA3 rules for mobile applications that may be abused. If you have questions about how to securely allow traffic from your mobile application, please contact your account team.
 
 :::note
-
-The instructions below apply to Enterprise subscription with Bot Management, Bot Fight Mode and Super Bot Fight Mode. 
+The instructions below apply to Enterprise subscription with Bot Management, Bot Fight Mode and Super Bot Fight Mode.
 :::
 
 * Allowing an **IP address**: Only use an IP address to allow traffic if the IP is a dedicated resource that belongs only to the traffic source you wish to allow. <br/>If the traffic you want to allow shares an IP with other traffic sources, or if the IP changes frequently, consider an alternative to allowing by IP address.

src/content/docs/ruleset-engine/about/phases.mdx

@@ -7,7 +7,12 @@ sidebar:
 
 A phase defines a stage in the life of a request where you can execute [rulesets](/ruleset-engine/about/rulesets/). Phases are defined by Cloudflare and cannot be modified.
 
-Phases exist at two levels: at the account level and at the zone level. For the same phase, rules defined at the account level are evaluated before the rules defined at the zone level.
+Phases exist at two levels:
+
+- At the [account](/fundamentals/concepts/accounts-and-zones/#accounts) level
+- At the [zone](/fundamentals/concepts/accounts-and-zones/#zones) level
+
+For the same phase, rules defined at the account level are evaluated before the rules defined at the zone level.
 
 Each phase has at most one [entry point ruleset](/ruleset-engine/about/rulesets/#entry-point-ruleset) at the account and zone level.
 

src/content/docs/ruleset-engine/basic-operations/add-rule-phase-rulesets.mdx

@@ -12,7 +12,7 @@ A [phase entry point ruleset](/ruleset-engine/about/rulesets/#entry-point-rulese
 
 To add one or more rules to a phase entry point ruleset, use one of the [ruleset update operations](/ruleset-engine/rulesets-api/update/) of the [Rulesets API](/ruleset-engine/rulesets-api/). When you add a rule to an entry point ruleset, the entry point ruleset is created automatically if it does not exist. This API method requires that you include in the request all rules you want to keep in the ruleset, or else they will be removed.
 
-If you are adding a **single** rule to a ruleset, consider using one of the [rule creation operations](/ruleset-engine/rulesets-api/add-rule/) instead. In this case, the request will only include the definition of the new rule.
+If you are adding a single rule to a ruleset, consider using one of the [rule creation operations](/ruleset-engine/rulesets-api/add-rule/) instead. In this case, the request only includes the definition of the new rule.
 
 :::note[Creating an entry point ruleset]
 Instead of relying on the automatic creation of an entry point ruleset, you can also create this ruleset explicitly using one of the [ruleset creation operations](/ruleset-engine/rulesets-api/create/).

src/content/docs/ruleset-engine/custom-rulesets/add-rules-ruleset.mdx

@@ -7,16 +7,16 @@ sidebar:
 
 import { APIRequest, Render } from "~/components";
 
-To add rules to an existing custom ruleset, use the [Update an account ruleset](/api/resources/rulesets/methods/update/) operation and pass the rules in an array. Each rule has an expression and an action.
+To add rules to an existing custom ruleset, use the [Update an account or zone ruleset](/api/resources/rulesets/methods/update/) operation and pass the rules in an array. Each rule has an expression and an action.
 
 :::note[Choosing the appropriate API method]
 
-When you add rules to a custom ruleset using the [Update an account ruleset](/api/resources/rulesets/methods/update/) operation, you replace all the rules in the ruleset with the rules in the request. Use this API method when adding or updating several rules at once. This method will update the ruleset version number only once.
+When you add rules to a custom ruleset using the [Update an account or zone ruleset](/api/resources/rulesets/methods/update/) operation, you replace all the rules in the ruleset with the rules in the request. Use this API method when adding or updating several rules at once. This method will update the ruleset version number only once.
 
 You can use other API operations depending on the type of operation:
 
-- Add a single rule to an existing custom ruleset: Use the [Create an account ruleset rule](/api/resources/rulesets/subresources/rules/methods/create/) operation.
-- Update a single rule in a custom ruleset: Use the [Update an account ruleset rule](/api/resources/rulesets/subresources/rules/methods/edit/) operation.
+- Add a single rule to an existing custom ruleset: Use the [Create an account or zone ruleset rule](/api/resources/rulesets/subresources/rules/methods/create/) operation.
+- Update a single rule in a custom ruleset: Use the [Update an account or zone ruleset rule](/api/resources/rulesets/subresources/rules/methods/edit/) operation.
 
 :::
 
@@ -26,7 +26,7 @@ You can use other API operations depending on the type of operation:
 
 ## Add rules
 
-The following request adds two rules to a custom ruleset with ID `$RULESET_ID`. These will be the only two rules in the ruleset.
+The following request adds two rules to a custom ruleset at the account level with ID `$RULESET_ID`. These will be the only two rules in the ruleset.
 
 The response will include the rule ID of the new rules in the `id` field.
 
@@ -90,9 +90,9 @@ The response will include the rule ID of the new rules in the `id` field.
 
 ## Update rules
 
-To update one or more rules in a custom ruleset, use the [Update an account ruleset](/api/resources/rulesets/methods/update/) operation. Include the ID of the rules you want to modify in the rules array and add the fields you wish to update. The request replaces the entire ruleset with a new version. Therefore, you must include the ID of all the rules you wish to keep.
+To update one or more rules in a custom ruleset, use the [Update an account or zone ruleset](/api/resources/rulesets/methods/update/) operation. Include the ID of the rules you want to modify in the rules array and add the fields you wish to update. The request replaces the entire ruleset with a new version. Therefore, you must include the ID of all the rules you wish to keep.
 
-The following `PUT` request edits one rule in a custom ruleset and updates the execution order of the rules.
+The following `PUT` request edits one rule in a custom ruleset at the account level and updates the execution order of the rules.
 
 The response will include the modified custom ruleset. Note that the updated rule and ruleset version number increment.
 

src/content/docs/ruleset-engine/custom-rulesets/create-custom-ruleset.mdx

@@ -7,7 +7,7 @@ sidebar:
 
 import { APIRequest, Render } from "~/components";
 
-Use the [Create an account ruleset](/api/resources/rulesets/methods/create/) operation to create a custom ruleset, making sure that you:
+Use the [Create an account or zone ruleset](/api/resources/rulesets/methods/create/) operation to create a custom ruleset, making sure that you:
 
 - Set the `kind` field to `custom`.
 - Specify the name of the [phase](/ruleset-engine/reference/phases-list/) where you want to create the custom ruleset in the `phase` field.
@@ -16,16 +16,53 @@ Use the [Create an account ruleset](/api/resources/rulesets/methods/create/) ope
 
 <Render file="custom-rulesets-dashboard" product="ruleset-engine" />
 
-## Example
+<Render file="custom-ruleset-zone-limitation" product="ruleset-engine" />
 
-The following request creates a new custom ruleset. The response will include the ID of the new custom ruleset in the `id` field.
+## Example A - Custom ruleset at the account level
+
+The following request creates a new custom ruleset at the account level. The response will include the ID of the new custom ruleset in the `id` field.
 
 <APIRequest
 	path="/accounts/{account_id}/rulesets"
 	method="POST"
 	json={{
 		name: "Custom Ruleset 1",
-		description: "My First Custom Ruleset",
+		description: "My First Custom Ruleset (account)",
+		kind: "custom",
+		phase: "http_request_firewall_custom",
+	}}
+/>
+
+```json output {3}
+{
+	"result": {
+		"id": "f82ccda3d21f4a02825d3fe45b5e1c10",
+		"name": "Custom Ruleset 1",
+		"description": "My First Custom Ruleset (account)",
+		"kind": "custom",
+		"version": "1",
+		"last_updated": "2025-08-09T10:27:30.636197Z",
+		"phase": "http_request_firewall_custom"
+	},
+	"success": true,
+	"errors": [],
+	"messages": []
+}
+```
+
+You can include a list of rules in the custom ruleset creation request. If you have not added any rules, refer to [Add rules to a custom ruleset](/ruleset-engine/custom-rulesets/add-rules-ruleset/) for more information.
+
+
+## Example B - Custom ruleset at the zone level
+
+The following request creates a new custom ruleset at the zone level. The response will include the ID of the new custom ruleset in the `id` field.
+
+<APIRequest
+	path="/zones/{zone_id}/rulesets"
+	method="POST"
+	json={{
+		name: "Custom Ruleset 1",
+		description: "My First Custom Ruleset (zone)",
 		kind: "custom",
 		phase: "http_request_firewall_custom",
 	}}
@@ -36,10 +73,10 @@ The following request creates a new custom ruleset. The response will include th
 	"result": {
 		"id": "f82ccda3d21f4a02825d3fe45b5e1c10",
 		"name": "Custom Ruleset 1",
-		"description": "My First Custom Ruleset",
+		"description": "My First Custom Ruleset (zone)",
 		"kind": "custom",
 		"version": "1",
-		"last_updated": "2021-03-09T10:27:30.636197Z",
+		"last_updated": "2025-08-09T10:27:30.636197Z",
 		"phase": "http_request_firewall_custom"
 	},
 	"success": true,
@@ -49,3 +86,6 @@ The following request creates a new custom ruleset. The response will include th
 ```
 
 You can include a list of rules in the custom ruleset creation request. If you have not added any rules, refer to [Add rules to a custom ruleset](/ruleset-engine/custom-rulesets/add-rules-ruleset/) for more information.
+
+<Render file="custom-ruleset-zone-limitation" product="ruleset-engine" />
+

src/content/docs/ruleset-engine/custom-rulesets/deploy-custom-ruleset.mdx

@@ -8,21 +8,27 @@ description: Learn how to deploy a custom ruleset to your Cloudflare account.
 
 import { APIRequest, Render } from "~/components";
 
-To deploy a custom ruleset, add a rule with `execute` action to the list of rules of a phase [entry point ruleset](/ruleset-engine/about/rulesets/#entry-point-ruleset) at the account level. The expression of the new rule will define when the custom ruleset will run.
+To deploy a custom ruleset, add a rule with `execute` action to the list of rules of a phase [entry point ruleset](/ruleset-engine/about/rulesets/#entry-point-ruleset) at the account or zone level. The expression of the new rule will define when the custom ruleset will run.
+
+You can only deploy custom rulesets in an entry point ruleset with the same scope. For example, a custom ruleset defined at the account level can only be deployed at the account level.
 
 <Render file="custom-rulesets-terraform" product="ruleset-engine" />
 
 <Render file="custom-rulesets-dashboard" product="ruleset-engine" />
 
+<Render file="custom-ruleset-zone-limitation" product="ruleset-engine" />
+
 ## Before you begin
 
 1. Obtain the name of the [phase](/ruleset-engine/reference/phases-list/) where you want to deploy the custom ruleset.
 2. [Create a custom ruleset](/ruleset-engine/custom-rulesets/create-custom-ruleset/) and keep the ID of the new custom ruleset.
 3. [Fetch the rules already present in the phase entry point ruleset](/ruleset-engine/basic-operations/view-rulesets/#view-the-rules-included-in-a-ruleset). You must include in the `PUT` request all existing rules you want to keep.
 
-## Example
+## Example A - Account-level deployment
 
-The following `PUT` request adds a rule that executes a custom ruleset when the zone name matches `example.com`. The response will include all the rules in the phase entry point ruleset.
+The following `PUT` request adds a rule that executes a custom ruleset when the zone name matches `example.com`.
+
+In the `PUT` request, you must include the IDs of all existing rules you want to keep. The response will include all the rules in the phase entry point ruleset after the update.
 
 <APIRequest
 	path="/accounts/{account_id}/rulesets/phases/{ruleset_phase}/entrypoint"
@@ -110,5 +116,78 @@ The following `PUT` request adds a rule that executes a custom ruleset when the
 ```
 
 :::caution
-Regarding the expression of the rule deploying the ruleset, you must use parentheses to enclose any custom conditions and end your expression with `and cf.zone.plan eq "ENT"` or else the API operation will fail.
+When deploying the custom ruleset at the account level, you must use parentheses to enclose any custom conditions and end your expression with `and cf.zone.plan eq "ENT"` like in the example above, or else the API operation will fail.
 :::
+
+## Example B - Zone-level deployment
+
+The following `PUT` request adds a rule to a zone-level entry point ruleset that executes a custom ruleset with ID `"<CUSTOM_RULESET_ID>"` for requests targeting the `/login` URI path.
+
+You must include in the `PUT` request the IDs of all existing rules you want to keep. The response will include all the rules in the phase entry point ruleset after the update.
+
+<APIRequest
+	path="/zones/{zone_id}/rulesets/phases/{ruleset_phase}/entrypoint"
+	method="PUT"
+	parameters={{
+		ruleset_phase: "http_request_firewall_custom",
+	}}
+	json={{
+		rules: [
+			{
+				action: "execute",
+				description: "Execute custom ruleset (zone)",
+				expression: '(http.request.uri.path eq "/login")',
+				action_parameters: {
+					id: "<CUSTOM_RULESET_ID>",
+				},
+			},
+			{
+				id: "<EXISTING_PHASE_RULE_ID_1>",
+			},
+		],
+	}}
+/>
+
+```json output
+{
+	"result": {
+		"id": "<ZONE_PHASE_RULESET_ID>",
+		"name": "http_request_firewall_custom phase entry point ruleset for my zone",
+		"description": "",
+		"kind": "zone",
+		"version": "3",
+		"rules": [
+			{
+				"id": "<PHASE_RULE_ID>",
+				"version": "1",
+				"action": "execute",
+				"description": "Execute custom ruleset (zone)",
+				"action_parameters": {
+					"id": "<CUSTOM_RULESET_ID>",
+					"version": "latest"
+				},
+				"expression": "(http.request.uri.path eq \"/login\")",
+				"last_updated": "2025-08-18T18:35:14.135697Z",
+				"ref": "<PHASE_RULE_REF>",
+				"enabled": true
+			},
+			{
+				"id": "<EXISTING_PHASE_RULE_ID_1>",
+				"version": "1",
+				"action": "managed_challenge",
+				"expression": "(cf.waf.score lt 20 and http.request.uri.path wildcard \"/admin/*\")",
+				"last_updated": "2025-08-16T15:51:49.180378Z",
+				"ref": "<EXISTING_PHASE_RULE_REF_1>",
+				"enabled": true
+			}
+		],
+		"last_updated": "2025-08-18T18:35:14.135697Z",
+		"phase": "http_request_firewall_custom"
+	},
+	"success": true,
+	"errors": [],
+	"messages": []
+}
+```
+
+<Render file="custom-ruleset-zone-limitation" product="ruleset-engine" />

src/content/docs/ruleset-engine/custom-rulesets/index.mdx

@@ -5,15 +5,15 @@ sidebar:
   order: 7
 ---
 
-Use the following workflow to deploy a custom ruleset at the account level:
+Use the following workflow to deploy a custom ruleset:
 
 1. [Create a custom ruleset](/ruleset-engine/custom-rulesets/create-custom-ruleset/).
 2. [Add rules to your custom ruleset](/ruleset-engine/custom-rulesets/add-rules-ruleset/).
-3. [Add a rule to an account-level phase entry point ruleset that executes the custom ruleset](/ruleset-engine/custom-rulesets/deploy-custom-ruleset/).
+3. [Add a rule to a phase entry point ruleset that executes the custom ruleset](/ruleset-engine/custom-rulesets/deploy-custom-ruleset/).
 
 You must create a rule with `execute` action in an entry point ruleset to execute the custom ruleset (step 3 in the previous procedure). If you skip this step, the rules of the custom ruleset will not run.
 
-Currently, custom rulesets are only supported by the [Cloudflare WAF](/waf/).
+Currently, custom rulesets are only supported by the [Cloudflare WAF](/waf/), both at the account and the zone level.
 
 :::note
 You cannot execute a custom ruleset from another custom ruleset, only from an entry point ruleset.

src/content/docs/ruleset-engine/rules-language/actions.mdx

@@ -116,6 +116,7 @@ The available actions depend on the [phase](/ruleset-engine/about/phases/) where
         <p>
           <ul>
             <li>Skip all remaining rules in the current ruleset</li>
+            <li>Skip all remaining rules in the current phase (zone-level only option)</li>
             <li>Skip rulesets</li>
             <li>Skip rules of a ruleset</li>
             <li>Skip phases</li>

src/content/docs/ruleset-engine/rulesets-api/create.mdx

@@ -39,7 +39,7 @@ Use the `rules` parameter to supply a list of rules for the ruleset. For an obje
 
 ## Example - Create a custom ruleset
 
-The following `POST` request creates a custom ruleset in the `http_request_firewall_custom` phase containing a single rule.
+The following `POST` request creates a custom ruleset in the `http_request_firewall_custom` phase at the account level containing a single rule.
 
 <APIRequest
 	path="/accounts/{account_id}/rulesets"