From da57e3cccd297579dc543c579fa49026d646e1a3 Mon Sep 17 00:00:00 2001
From: Pedro Sousa <680496+pedrosousa@users.noreply.github.com>
Date: Wed, 16 Apr 2025 18:45:25 +0100
Subject: [PATCH] [Ruleset Engine] Improve linking
---
.../basic-operations/deploy-rulesets.mdx | 10 ++++++---
.../custom-rulesets/add-rules-ruleset.mdx | 6 ++++-
.../custom-rulesets/create-custom-ruleset.mdx | 8 +++++--
.../custom-rulesets/deploy-custom-ruleset.mdx | 22 +++++++++++--------
.../ruleset-engine/custom-rulesets/index.mdx | 2 +-
.../managed-rulesets/create-exception.mdx | 6 ++++-
.../deploy-managed-ruleset.mdx | 15 ++++++++-----
.../override-managed-ruleset.mdx | 17 +++++++++++---
.../waf-managed-rulesets.mdx | 10 ++++-----
.../docs/waf/custom-rules/skip/options.mdx | 2 +-
.../custom-rulesets-dashboard.mdx | 5 +++++
.../custom-rulesets-terraform.mdx | 5 +++++
.../managed-rulesets/api-account-example.mdx | 2 +-
.../waf/managed-rulesets/api-zone-example.mdx | 2 +-
14 files changed, 79 insertions(+), 33 deletions(-)
create mode 100644 src/content/partials/ruleset-engine/custom-rulesets-dashboard.mdx
create mode 100644 src/content/partials/ruleset-engine/custom-rulesets-terraform.mdx
diff --git a/src/content/docs/ruleset-engine/basic-operations/deploy-rulesets.mdx b/src/content/docs/ruleset-engine/basic-operations/deploy-rulesets.mdx
index f07138ba45efbff..7ed59a475fdf662 100644
--- a/src/content/docs/ruleset-engine/basic-operations/deploy-rulesets.mdx
+++ b/src/content/docs/ruleset-engine/basic-operations/deploy-rulesets.mdx
@@ -24,7 +24,7 @@ To apply a rule to every request in a phase at the **zone** level, set the rule
## Example
-The following example deploys a managed ruleset to the `http_request_firewall_managed` phase of a given zone (`$ZONE_ID`) by adding a rule that executes the managed ruleset.
+The following example deploys a [managed ruleset](/ruleset-engine/about/rulesets/#managed-rulesets) to the `http_request_firewall_managed` phase of a given zone (`$ZONE_ID`) by adding a rule that executes the managed ruleset.
+
+
+
## 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.
diff --git a/src/content/docs/ruleset-engine/custom-rulesets/create-custom-ruleset.mdx b/src/content/docs/ruleset-engine/custom-rulesets/create-custom-ruleset.mdx
index b12e010bd3d403d..d089d3d92797573 100644
--- a/src/content/docs/ruleset-engine/custom-rulesets/create-custom-ruleset.mdx
+++ b/src/content/docs/ruleset-engine/custom-rulesets/create-custom-ruleset.mdx
@@ -5,12 +5,16 @@ sidebar:
order: 2
---
-import { APIRequest } from "~/components";
+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:
- Set the `kind` field to `custom`.
-- Specify the name of the phase where you want to create the custom ruleset in the `phase` field.
+- Specify the name of the [phase](/ruleset-engine/reference/phases-list/) where you want to create the custom ruleset in the `phase` field.
+
+
+
+
## Example
diff --git a/src/content/docs/ruleset-engine/custom-rulesets/deploy-custom-ruleset.mdx b/src/content/docs/ruleset-engine/custom-rulesets/deploy-custom-ruleset.mdx
index 3f54ece12e1f0a1..0c075a216fd89ef 100644
--- a/src/content/docs/ruleset-engine/custom-rulesets/deploy-custom-ruleset.mdx
+++ b/src/content/docs/ruleset-engine/custom-rulesets/deploy-custom-ruleset.mdx
@@ -6,19 +6,19 @@ sidebar:
description: Learn how to deploy a custom ruleset to your Cloudflare account.
---
-import { APIRequest } from "~/components";
+import { APIRequest, Render } from "~/components";
-Before you begin:
+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.
-1. Obtain the name of the phase 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.
+
-To deploy a custom ruleset, add a rule that executes the custom ruleset. Define the rule scope in the rule expression.
+
-:::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.
-:::
+## 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
@@ -108,3 +108,7 @@ The following `PUT` request adds a rule that executes a custom ruleset when the
"messages": []
}
```
+
+:::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.
+:::
diff --git a/src/content/docs/ruleset-engine/custom-rulesets/index.mdx b/src/content/docs/ruleset-engine/custom-rulesets/index.mdx
index 05670c37d47f4a8..d42ec089b8e1673 100644
--- a/src/content/docs/ruleset-engine/custom-rulesets/index.mdx
+++ b/src/content/docs/ruleset-engine/custom-rulesets/index.mdx
@@ -15,7 +15,7 @@ You must create a rule with `execute` action in an entry point ruleset to execut
Currently, custom rulesets are only supported by the [Cloudflare WAF](/waf/).
-:::caution
+:::note
You cannot execute a custom ruleset from another custom ruleset, only from an entry point ruleset.
:::
diff --git a/src/content/docs/ruleset-engine/managed-rulesets/create-exception.mdx b/src/content/docs/ruleset-engine/managed-rulesets/create-exception.mdx
index a9fb17524aad09b..845aa052a82ca58 100644
--- a/src/content/docs/ruleset-engine/managed-rulesets/create-exception.mdx
+++ b/src/content/docs/ruleset-engine/managed-rulesets/create-exception.mdx
@@ -5,10 +5,14 @@ sidebar:
order: 5
---
-Use exceptions to skip the execution of a managed ruleset of some of its rules. Exceptions are also known as skip rules, since the rule action is `skip`.
+Use [exceptions](/waf/managed-rules/waf-exceptions/) to skip the execution of a managed ruleset of some of its rules.
The exception configuration includes an [expression](/ruleset-engine/rules-language/expressions/) that defines the skip conditions, and the rules or managed rulesets to skip under those conditions.
+If you are using Terraform, refer to [Configure exceptions](/terraform/additional-configurations/waf-managed-rulesets/#configure-exceptions) in the Terraform documentation.
+
+If you are using the Cloudflare dashboard, refer to [Add an exception in the dashboard](/waf/managed-rules/waf-exceptions/define-dashboard/).
+
:::note
Currently, only the [Cloudflare Web Application Firewall (WAF)](/waf/managed-rules/waf-exceptions/) supports managed rules exceptions.
:::
diff --git a/src/content/docs/ruleset-engine/managed-rulesets/deploy-managed-ruleset.mdx b/src/content/docs/ruleset-engine/managed-rulesets/deploy-managed-ruleset.mdx
index c0fdf2ad60c15e1..90eda358e1ddcbc 100644
--- a/src/content/docs/ruleset-engine/managed-rulesets/deploy-managed-ruleset.mdx
+++ b/src/content/docs/ruleset-engine/managed-rulesets/deploy-managed-ruleset.mdx
@@ -7,9 +7,14 @@ sidebar:
import { RuleID, Render } from "~/components";
-You can deploy a managed ruleset at the zone level or at the account level.
+You can deploy a managed ruleset at the zone level or at the account level. To deploy a managed ruleset to a phase, use the [Rulesets API](/ruleset-engine/rulesets-api/).
-To deploy a managed ruleset to a phase, use the [Rulesets API](/ruleset-engine/rulesets-api/).
+If you are using Terraform, refer to [WAF Managed Rules configuration using Terraform](/terraform/additional-configurations/waf-managed-rulesets/) for more information.
+
+If you are using the Cloudflare dashboard, refer to the following pages:
+
+- [Deploy a WAF managed ruleset in the dashboard (zone)](/waf/managed-rules/deploy-zone-dashboard/)
+- [Deploy a WAF managed ruleset in the dashboard (account)](/waf/account/managed-rulesets/deploy-dashboard/)
## Deploy a managed ruleset to a phase at the zone level
@@ -17,7 +22,7 @@ Use the following workflow to deploy a managed ruleset to a phase at the zone le
1. Get your [zone ID](/fundamentals/setup/find-account-and-zone-ids/).
2. Invoke the [List account rulesets](/api/resources/rulesets/methods/list/) operation to obtain the available managed rulesets. Managed rulesets exist at the account level, but you can deploy them to a zone. Find the ruleset ID of the managed ruleset you want to deploy.
-3. Identify the [phase](/ruleset-engine/about/phases/) where you want to deploy the managed ruleset. Ensure that the managed ruleset belongs to the same phase where you want to deploy it. To learn more about the available phases supported by each Cloudflare product, refer to the specific documentation for that product, or the [Phases list](/ruleset-engine/reference/phases-list/).
+3. Identify the [phase](/ruleset-engine/reference/phases-list/) where you want to deploy the managed ruleset. Ensure that the managed ruleset belongs to the same phase where you want to deploy it.
4. Add a rule to the zone-level phase [entry point ruleset](/ruleset-engine/about/rulesets/#entry-point-ruleset) that executes the managed ruleset. Refer to the following example for details on this step.
### Example
@@ -32,11 +37,11 @@ Use the following workflow to deploy a managed ruleset to a phase at the account
1. Get your [account ID](/fundamentals/setup/find-account-and-zone-ids/).
2. Invoke the [List account rulesets](/api/resources/rulesets/methods/list/) operation to obtain the available managed rulesets. Find the ruleset ID of the managed ruleset you want to deploy.
-3. Identify the [phase](/ruleset-engine/about/phases/) where you want to deploy the managed ruleset. Ensure that the managed ruleset belongs to the same phase where you want to deploy it. To learn more about the available phases supported by each Cloudflare product, refer to the specific documentation for that product, or the [Phases list](/ruleset-engine/reference/phases-list/).
+3. Identify the [phase](/ruleset-engine/reference/phases-list/) where you want to deploy the managed ruleset. Ensure that the managed ruleset belongs to the same phase where you want to deploy it.
4. Add a rule to the account-level phase [entry point ruleset](/ruleset-engine/about/rulesets/#entry-point-ruleset) that executes the managed ruleset. Use parentheses to enclose any custom conditions in the rule expression and end your expression with `and cf.zone.plan eq "ENT"` so that it only applies to zones on an Enterprise plan. Refer to the following example for details on this step.
### Example
-In this example, the managed ruleset executes the behavior configured by Cloudflare. To customize the behavior of managed rulesets, refer to [Override a managed ruleset](/ruleset-engine/managed-rulesets/override-managed-ruleset/).
+In this example, the managed ruleset executes the behavior configured by Cloudflare. To learn how to customize the behavior of managed rulesets, refer to [Override a managed ruleset](/ruleset-engine/managed-rulesets/override-managed-ruleset/).
diff --git a/src/content/docs/ruleset-engine/managed-rulesets/override-managed-ruleset.mdx b/src/content/docs/ruleset-engine/managed-rulesets/override-managed-ruleset.mdx
index 88a28b48ab0c9cd..9f968ad371f546c 100644
--- a/src/content/docs/ruleset-engine/managed-rulesets/override-managed-ruleset.mdx
+++ b/src/content/docs/ruleset-engine/managed-rulesets/override-managed-ruleset.mdx
@@ -7,11 +7,20 @@ sidebar:
import { Render, Details, APIRequest } from "~/components";
-To customize the behavior of a managed ruleset, 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.
+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.
-To define overrides in the Cloudflare dashboard, edit the configuration of the managed ruleset you previously deployed to a zone or to an account.
+If you are using Terraform, refer to the following pages:
+
+- [WAF Managed Rules configuration using Terraform](/terraform/additional-configurations/waf-managed-rulesets/#configure-overrides)
+- [DDoS managed rulesets configuration using Terraform](/terraform/additional-configurations/ddos-managed-rulesets/)
+
+To define overrides in the Cloudflare dashboard, refer to the following resources:
+
+- [Configure a WAF managed ruleset in the dashboard](/waf/managed-rules/deploy-zone-dashboard/#configure-a-managed-ruleset)
+- [Configure HTTP DDoS Attack Protection in the dashboard](/ddos-protection/managed-rulesets/http/configure-dashboard/)
+- [Configure Network-layer DDoS Attack Protection in the dashboard](/ddos-protection/managed-rulesets/network/configure-dashboard/)
## Working with overrides
@@ -132,4 +141,6 @@ The following `PUT` request adds a rule that executes a managed ruleset in the `
}}
/>
-For additional examples of configuring overrides, refer to [Managed ruleset override examples](/ruleset-engine/managed-rulesets/override-examples/).
+## More resources
+
+For additional examples of configuring overrides via API, refer to [Override examples](/ruleset-engine/managed-rulesets/override-examples/).
diff --git a/src/content/docs/terraform/additional-configurations/waf-managed-rulesets.mdx b/src/content/docs/terraform/additional-configurations/waf-managed-rulesets.mdx
index f6c65064fb56586..8e29291ae9438ea 100644
--- a/src/content/docs/terraform/additional-configurations/waf-managed-rulesets.mdx
+++ b/src/content/docs/terraform/additional-configurations/waf-managed-rulesets.mdx
@@ -15,7 +15,7 @@ This page provides examples of deploying and configuring [WAF Managed Rules](/wa
- [Deploy managed rulesets at the zone level](#deploy-managed-rulesets-at-the-zone-level)
- [Deploy managed rulesets at the account level](#deploy-managed-rulesets-at-the-account-level)
-- [Configure skip rules](#configure-skip-rules)
+- [Configure exceptions](#configure-exceptions)
- [Configure payload logging](#configure-payload-logging)
- [Configure overrides](#configure-overrides)
- [Configure the OWASP paranoia level, score threshold, and action](#configure-the-owasp-paranoia-level-score-threshold-and-action)
@@ -121,14 +121,14 @@ resource "cloudflare_ruleset" "account_level_managed_waf" {
}
```
-## Configure skip rules
+## Configure exceptions
-The following example adds two [skip rules](/waf/managed-rules/waf-exceptions/) (or exceptions) for the Cloudflare Managed Ruleset:
+The following example adds two [exceptions](/waf/managed-rules/waf-exceptions/) for the Cloudflare Managed Ruleset:
- The first rule will skip the execution of the entire Cloudflare Managed Ruleset (with ID ) for specific URLs, according to the rule expression.
- The second rule will skip the execution of two rules belonging to the Cloudflare Managed Ruleset for specific URLs, according to the rule expression.
-Add the two skip rules to the `cloudflare_ruleset` resource before the rule that deploys the Cloudflare Managed Ruleset:
+Add the two exceptions to the `cloudflare_ruleset` resource before the rule that deploys the Cloudflare Managed Ruleset:
@@ -178,7 +178,7 @@ resource "cloudflare_ruleset" "zone_level_managed_waf" {
:::caution[Important]
-Ensure that you place the skip rules **before** the rule that executes the managed ruleset (or some of its rules) that you wish to skip, as in the previous example.
+Ensure that you place the exceptions **before** the rule that executes the managed ruleset (or some of its rules) that you wish to skip, as in the previous example.
:::
## Configure overrides
diff --git a/src/content/docs/waf/custom-rules/skip/options.mdx b/src/content/docs/waf/custom-rules/skip/options.mdx
index a34e7e3ff41cbcc..6eecfd651daed6f 100644
--- a/src/content/docs/waf/custom-rules/skip/options.mdx
+++ b/src/content/docs/waf/custom-rules/skip/options.mdx
@@ -20,7 +20,7 @@ The available skip options in custom rules are the following:
- API action parameter: `phases`.
- - Skips the execution of one or more phases. Based on the phases you can skip, this option effectively allows you to skip [rate limiting rules](/waf/rate-limiting-rules/), [Super Bot Fight Mode rules](/bots/get-started/super-bot-fight-mode/), and/or [WAF Managed Rules](/waf/managed-rules/). When skipping a phase, both the account and zone-level entry point rulesets of the phase will be skipped.
+ - Skips the execution of one or more phases. Based on the phases you can skip, this option effectively allows you to skip [rate limiting rules](/waf/rate-limiting-rules/), [Super Bot Fight Mode rules](/bots/get-started/super-bot-fight-mode/), and/or [WAF Managed Rules](/waf/managed-rules/).
- The phases you can skip are the following:
diff --git a/src/content/partials/ruleset-engine/custom-rulesets-dashboard.mdx b/src/content/partials/ruleset-engine/custom-rulesets-dashboard.mdx
new file mode 100644
index 000000000000000..bf14088c013145c
--- /dev/null
+++ b/src/content/partials/ruleset-engine/custom-rulesets-dashboard.mdx
@@ -0,0 +1,5 @@
+---
+{}
+---
+
+If you are using the Cloudflare dashboard, refer to [Work with custom rulesets in the dashboard](/waf/account/custom-rulesets/create-dashboard/).
diff --git a/src/content/partials/ruleset-engine/custom-rulesets-terraform.mdx b/src/content/partials/ruleset-engine/custom-rulesets-terraform.mdx
new file mode 100644
index 000000000000000..2f89aa9a3909923
--- /dev/null
+++ b/src/content/partials/ruleset-engine/custom-rulesets-terraform.mdx
@@ -0,0 +1,5 @@
+---
+{}
+---
+
+If you are using Terraform, refer to [WAF custom rules configuration using Terraform](/terraform/additional-configurations/waf-custom-rules/#create-and-deploy-a-custom-ruleset) for examples of creating and deploying custom rulesets.
diff --git a/src/content/partials/waf/managed-rulesets/api-account-example.mdx b/src/content/partials/waf/managed-rulesets/api-account-example.mdx
index adcbb88d8c0c789..ea8e0d102a4a71b 100644
--- a/src/content/partials/waf/managed-rulesets/api-account-example.mdx
+++ b/src/content/partials/waf/managed-rulesets/api-account-example.mdx
@@ -4,7 +4,7 @@
import { Render, RuleID } from "~/components";
-The following example deploys a [WAF managed ruleset](/waf/managed-rules/#managed-rulesets) 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`.
+The following example deploys the [Cloudflare Managed Ruleset](/waf/managed-rules/reference/cloudflare-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.