[WAF] Improve linking between API and Terraform (#21741)

* Add links between API and Terraform sections
* Move Terraform examples of using traffic detections to WAF docs
* Move custom detection location examples to concept section
* Apply suggestions from PCX review

---------

Co-authored-by: Jun Lee <[email protected]>

Author: 2 people

src/content/docs/terraform/additional-configurations/waf-custom-rules.mdx

@@ -13,13 +13,10 @@ import { Render, GlossaryTooltip } from "~/components";
 
 This page provides examples of creating [WAF custom rules](/waf/custom-rules/) in a zone or account using Terraform. The examples cover the following scenarios:
 
-- Zone-level configurations:
-  - [Add a custom rule to a zone](#add-a-custom-rule-to-a-zone)
-  - [Add a custom rule challenging requests with leaked credentials](#add-a-custom-rule-challenging-requests-with-leaked-credentials)
-  - [Add a custom rule blocking malicious uploads](#add-a-custom-rule-blocking-malicious-uploads)
-- Account-level configurations:
-  - [Create and deploy a custom ruleset](#create-and-deploy-a-custom-ruleset)
-  - [Add a custom rule checking for exposed credentials](#add-a-custom-rule-checking-for-exposed-credentials)
+- [Add a custom rule to a zone](#add-a-custom-rule-to-a-zone) (zone-level configuration)
+- [Create and deploy a custom ruleset](#create-and-deploy-a-custom-ruleset) (account-level configuration)
+
+The WAF documentation includes additional Terraform examples — refer to [More resources](#more-resources).
 
 ## Before you start
 
@@ -33,9 +30,7 @@ This page provides examples of creating [WAF custom rules](/waf/custom-rules/) i
 
 ---
 
-## Zone-level configurations
-
-### Add a custom rule to a zone
+## Add a custom rule to a zone
 
 The following example configures a custom rule in the zone entry point ruleset for the `http_request_firewall_custom` phase for zone with ID `<ZONE_ID>`. The rule will block all traffic on non-standard HTTP(S) ports:
 
@@ -60,75 +55,17 @@ resource "cloudflare_ruleset" "zone_custom_firewall" {
 
 <Render file="add-new-rule" params={{ ruleType: "custom rule" }} /> <br />
 
-### Add a custom rule challenging requests with leaked credentials
-
-:::note
-For more information on enabling leaked credentials detection using Terraform, refer to the [leaked credentials detection](/waf/detections/leaked-credentials/get-started/#1-turn-on-the-detection) documentation.
-:::
-
-This example adds a custom rule that challenges requests with leaked credentials by using one of the [leaked credentials fields](/waf/detections/leaked-credentials/#leaked-credentials-fields) in the rule expression.
-
-<Render file="v4-code-snippets" />
-
-```tf
-resource "cloudflare_ruleset" "zone_custom_firewall_leaked_creds" {
-  zone_id     = "<ZONE_ID>"
-  name        = "Phase entry point ruleset for custom rules in my zone"
-  description = ""
-  kind        = "zone"
-  phase       = "http_request_firewall_custom"
-
-  rules {
-    ref         = "challenge_leaked_username_password"
-    description = "Challenge requests with a leaked username and password"
-    expression  = "(cf.waf.credential_check.username_and_password_leaked)"
-    action      = "managed_challenge"
-  }
-}
-```
-
-For more information on configuring custom detection locations, refer to the [Terraform example](/waf/detections/leaked-credentials/get-started/#4-optional-configure-a-custom-detection-location) in the WAF documentation.
-
-### Add a custom rule blocking malicious uploads
+## Create and deploy a custom ruleset (account-level configuration) {/* create-and-deploy-a-custom-ruleset */}
 
 :::note
-For more information on enabling malicious uploads detection using Terraform, refer to the [malicious uploads detection](/waf/detections/malicious-uploads/get-started/#1-turn-on-the-detection) documentation.
+Account-level WAF configuration requires an Enterprise plan with a paid add-on.
 :::
 
-This example adds a custom rule that blocks requests with one or more <GlossaryTooltip term="content object">content objects</GlossaryTooltip> considered malicious by using one of the [content scanning fields](/waf/detections/malicious-uploads/#content-scanning-fields) in the rule expression.
-
-<Render file="v4-code-snippets" />
-
-```tf
-resource "cloudflare_ruleset" "zone_custom_firewall_malicious_uploads" {
-  zone_id     = "<ZONE_ID>"
-  name        = "Phase entry point ruleset for custom rules in my zone"
-  description = ""
-  kind        = "zone"
-  phase       = "http_request_firewall_custom"
-
-  rules {
-    ref         = "block_malicious_uploads"
-    description = "Block requests uploading malicious content objects"
-    expression  = "(cf.waf.content_scan.has_malicious_obj and http.request.uri.path eq \"/upload.php\")"
-    action      = "block"
-  }
-}
-```
-
-For more information on configuring custom scan expressions, refer to the [Terraform example](/waf/detections/malicious-uploads/get-started/#4-optional-configure-a-custom-scan-expression) in the WAF documentation.
-
-## Account-level configurations
-
-### Create and deploy a custom ruleset
-
 The following example creates a [custom ruleset](/ruleset-engine/custom-rulesets/) in the account with ID `<ACCOUNT_ID>` containing a single custom rule. This custom ruleset is then deployed using a separate `cloudflare_ruleset` Terraform resource. If you do not deploy a custom ruleset, it will not execute.
 
-:::caution
 You can only create and deploy custom rulesets at the account level.
-:::
 
-The following configuration creates the custom ruleset with a single rule:
+The following configuration creates a custom ruleset with a single rule:
 
 <Render file="v4-code-snippets" />
 
@@ -183,68 +120,7 @@ resource "cloudflare_ruleset" "account_firewall_custom_entrypoint" {
 
 For more information on configuring and deploying custom rulesets, refer to [Work with custom rulesets](/ruleset-engine/custom-rulesets/) in the Ruleset Engine documentation.
 
-### Add a custom rule checking for exposed credentials
+## More resources
 
-<Render file="leaked-credentials-recommend-detection" product="waf" />
-
-The following configuration creates a custom ruleset with a single rule that [checks for exposed credentials](/waf/managed-rules/check-for-exposed-credentials/configure-api/#create-a-custom-rule-checking-for-exposed-credentials).
-
-You can only add exposed credential checks to rules in a custom ruleset (that is, a ruleset with `kind = "custom"`).
-
-<Render file="v4-code-snippets" />
-
-```tf
-resource "cloudflare_ruleset" "account_firewall_custom_ruleset_exposed_creds" {
-  account_id  = "<ACCOUNT_ID>"
-  name        = "Custom ruleset checking for exposed credentials"
-  description = ""
-  kind        = "custom"
-  phase       = "http_request_firewall_custom"
-
-  rules {
-    ref         = "check_for_exposed_creds_add_header"
-    description = "Add header when there is a rule match and exposed credentials are detected"
-    expression  = "http.request.method == \"POST\" && http.request.uri == \"/login.php\""
-    action      = "rewrite"
-    action_parameters {
-      headers {
-        name      = "Exposed-Credential-Check"
-        operation = "set"
-        value     = "1"
-      }
-    }
-    exposed_credential_check {
-      username_expression = "url_decode(http.request.body.form[\"username\"][0])"
-      password_expression = "url_decode(http.request.body.form[\"password\"][0])"
-    }
-  }
-}
-```
-
-<Render file="add-new-rule" params={{ ruleType: "rule" }} /> <br />
-
-The following configuration deploys the custom ruleset. It defines a dependency on the `account_firewall_custom_ruleset_exposed_creds` resource and obtains the ID of the created custom ruleset:
-
-<Render file="v4-code-snippets" />
-
-```tf
-resource "cloudflare_ruleset" "account_firewall_custom_entrypoint" {
-  account_id  = "<ACCOUNT_ID>"
-  name        = "Account-level entry point ruleset for the http_request_firewall_custom phase deploying a custom ruleset checking for exposed credentials"
-  description = ""
-  kind        = "root"
-  phase       = "http_request_firewall_custom"
-
-  depends_on = [cloudflare_ruleset.account_firewall_custom_ruleset_exposed_creds]
-
-  rules {
-    ref         = "deploy_custom_ruleset_example_com"
-    description = "Deploy custom ruleset for example.com"
-    expression  = "(cf.zone.name eq \"example.com\")"
-    action      = "execute"
-    action_parameters {
-      id = cloudflare_ruleset.account_firewall_custom_ruleset_exposed_creds.id
-    }
-  }
-}
-```
+- [Malicious uploads detection: Add a custom rule to block malicious uploads](/waf/detections/malicious-uploads/terraform-examples/#add-a-custom-rule-to-block-malicious-uploads)
+- [Leaked credentials detection: Add a custom rule to challenge requests with leaked credentials](/waf/detections/leaked-credentials/terraform-examples/#add-a-custom-rule-to-challenge-requests-with-leaked-credentials)

src/content/docs/waf/analytics/security-analytics.mdx

@@ -92,7 +92,7 @@ To apply the filters for an insight to the data displayed in the Security Analyt
 
 ### Score-based analyses
 
-The **Attack analysis**, **Bot analysis**, **Malicious uploads**, and **Account abuse detection** sections display statistics related to WAF attack scores, bot scores, WAF content scanning scores, and leaked credentials scanning of incoming requests for the selected time frame. All plans include access to the **Leaked credential check** under **Account abuse detection**. This feature detects login attempts using credentials that have been exposed online. For more information on what to do if you have credentials that have been leaked, refer to the [mitigation examples page](/waf/detections/leaked-credentials/examples/).
+The **Attack analysis**, **Bot analysis**, **Malicious uploads**, and **Account abuse detection** sections display statistics related to WAF attack scores, bot scores, WAF content scanning scores, and leaked credentials scanning of incoming requests for the selected time frame. All plans include access to the **Leaked credential check** under **Account abuse detection**. This feature detects login attempts using credentials that have been exposed online. For more information on what to do if you have credentials that have been leaked, refer to the [example mitigation rules page](/waf/detections/leaked-credentials/examples/).
 
 You can examine different traffic segments according to the current metric (attack score, bot score, or content scanning). To apply score filters for different segments, select the buttons below the traffic chart. For example, select **Likely attack** under **Attack analysis** to filter requests that are likely an attack (requests with WAF attack score values between 21 and 50).
 

src/content/docs/waf/detections/attack-score.mdx

@@ -102,4 +102,4 @@ If you are an Enterprise customer and you created a rule with _Log_ action, chan
 
 ## Additional remarks
 
-The WAF Attack Score is different from Bot Score. WAF Attack Score identifies variation of attacks that WAF Managed Rules do not catch, while Bot Score identifies bots.
+The WAF attack score is different from [bot score](/bots/concepts/bot-score/). WAF attack score identifies variations of attacks that WAF Managed Rules do not catch, while bot score identifies bots.

src/content/docs/waf/detections/leaked-credentials/api-calls.mdx

@@ -10,6 +10,10 @@ head:
 
 import { APIRequest } from "~/components";
 
+The following examples address common scenarios of using the Cloudflare API to manage and configure leaked credentials detection.
+
+If you are using Terraform, refer to [Terraform configuration examples](/waf/detections/leaked-credentials/terraform-examples/).
+
 ## General operations
 
 The following API examples cover basic operations such as enabling and disabling the leaked credentials detection.
@@ -53,11 +57,11 @@ To obtain the current status of the leaked credentials detection, use a `GET` re
 
 ## Custom detection location operations
 
-The following API examples cover operations on custom detection locations for leaked credentials detection.
+The following API examples cover operations on [custom detection locations](/waf/detections/leaked-credentials/#custom-detection-locations) for leaked credentials detection.
 
 ### Add a custom detection location
 
-Use a `POST` request similar to the following:
+To add a custom detection location, use a `POST` request similar to the following:
 
 <APIRequest
 	path="/zones/{zone_id}/leaked-credential-checks/detections"
@@ -95,7 +99,7 @@ To get a list of existing custom detection locations, use a `GET` request simila
 
 ### Delete a custom detection location
 
-Use a `DELETE` request similar to the following:
+To delete a custom detection location, use a `DELETE` request similar to the following:
 
 <APIRequest
 	path="/zones/{zone_id}/leaked-credential-checks/detections/{detection_id}"

src/content/docs/waf/detections/leaked-credentials/examples.mdx

@@ -1,12 +1,11 @@
 ---
-title: Mitigation examples
+title: Example mitigation rules
 pcx_content_type: configuration
 sidebar:
-  order: 4
-  label: Mitigation examples
+  order: 5
 head:
   - tag: title
-    content: Leaked credentials mitigation examples
+    content: Leaked credentials example mitigation rules
 description: Examples of rules for mitigating requests containing leaked credentials.
 ---
 
@@ -59,7 +58,3 @@ Create a [custom rule](/waf/custom-rules/) that challenges requests containing a
 - **Action**: _Managed Challenge_
 
 ---
-
-## More resources
-
-- [Terraform example: Add a custom rule challenging requests with leaked credentials](/terraform/additional-configurations/waf-custom-rules/#add-a-custom-rule-challenging-requests-with-leaked-credentials)

src/content/docs/waf/detections/leaked-credentials/get-started.mdx

@@ -72,7 +72,7 @@ You can combine the previous expression with other [fields](/ruleset-engine/rule
 
 </Details>
 
-For additional examples, refer to [Mitigation examples](/waf/detections/leaked-credentials/examples/).
+For additional examples, refer to [Example mitigation rules](/waf/detections/leaked-credentials/examples/).
 
 ### Handle detected leaked credentials at the origin server
 
@@ -84,22 +84,27 @@ Additionally, you may want to handle leaked credentials detected by Cloudflare a
 
 ## 4. (Optional) Configure a custom detection location
 
-To check for leaked credentials in a way that is not covered by the default configuration, add a custom detection location.
+To check for leaked credentials in a way that is not covered by the default configuration, add a [custom detection location](/waf/detections/leaked-credentials/#custom-detection-locations).
 
 <Tabs syncKey="dashPlusAPI"> <TabItem label="Dashboard">
 
 1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com/), and select your account and domain.
 2. Go to **Security** > **Settings**.
 3. Under **Incoming traffic detections**, select **Leaked credentials** and then select **Add custom username and password location**.
-4. In **Username location** and **Password location** (optional), enter expressions for obtaining the username and the password from the HTTP request. Refer to the following example expressions:
+4. In **Username location** and **Password location** (optional), enter expressions for obtaining the username and the password from the HTTP request. For example, you could use the following expressions:
 
-   | Request type     | Username location / Password location                                                                           |
-   | ---------------- | --------------------------------------------------------------------------------------------------------------- |
-   | JSON body        | `lookup_json_string(http.request.body.raw, "user")`<br/>`lookup_json_string(http.request.body.raw, "secret")`   |
-   | URL-encoded form | `url_decode(http.request.body.form["user"][0])`<br/>`url_decode(http.request.body.form["secret"][0])`           |
-   | Multipart form   | `url_decode(http.request.body.multipart["user"][0])`<br/>`url_decode(http.request.body.multipart["secret"][0])` |
+   - Username location:<br/>
+     `lookup_json_string(http.request.body.raw, "user")`
+   - Password location:<br/>
+     `lookup_json_string(http.request.body.raw, "secret")`
 
-   Refer to the [`lookup_json_string()`](/ruleset-engine/rules-language/functions/#lookup_json_string) and [`url_decode()`](/ruleset-engine/rules-language/functions/#url_decode) documentation for more information on these functions.
+   This configuration will scan incoming HTTP requests containing a JSON body with a structure similar to the following:
+
+   ```js
+   {"user": "<USERNAME>", "secret": "<PASSWORD>"}
+   ```
+
+   Refer to the [`lookup_json_string()`](/ruleset-engine/rules-language/functions/#lookup_json_string) documentation for more information on this function.
 
 5. Select **Save**.
 
@@ -126,22 +131,16 @@ Refer to the [`lookup_json_string()`](/ruleset-engine/rules-language/functions/#
 
 </TabItem> <TabItem label="Terraform">
 
-Use the `cloudflare_leaked_credential_check_rule` resource to add a custom detection location. For example:
-
-```terraform
-resource "cloudflare_leaked_credential_check_rule" "custom_location_example" {
-	zone_id = "<ZONE_ID>"
-	username = "lookup_json_string(http.request.body.raw, \"user\")"
-	password = "lookup_json_string(http.request.body.raw, \"secret\")"
-}
-```
+<Render file="detections/leaked-credentials-configure-location-terraform" />
 
-For more information, refer to the [Terraform Cloudflare provider documentation](https://registry.terraform.io/providers/cloudflare/cloudflare/latest/docs).
+Refer to the [`lookup_json_string()`](/ruleset-engine/rules-language/functions/#lookup_json_string) documentation for more information on this function.
 
 </TabItem> </Tabs>
 
 You only need to provide an expression for the username in custom detection locations.
 
+For more examples of custom detection locations for different request types, refer to [Custom detection locations](/waf/detections/leaked-credentials/#custom-detection-locations).
+
 ---
 
 ## Test your configuration

src/content/docs/waf/detections/leaked-credentials/index.mdx

@@ -47,7 +47,7 @@ Leaked credentials detection includes rules for identifying credentials in HTTP
 
 Additionally, the scan includes generic rules for other common web authentication patterns.
 
-You can also configure custom detection locations to address the specific authentication mechanism used in your web applications. A custom detection location tells the Cloudflare WAF where to find usernames and passwords in HTTP requests of your web application.
+You can also configure [custom detection locations](#custom-detection-locations) to address the specific authentication mechanism used in your web applications. A custom detection location tells the Cloudflare WAF where to find usernames and passwords in HTTP requests of your web application.
 
 ## Custom detection locations
 
@@ -72,6 +72,14 @@ You could configure a custom detection location with the following settings:
 
 When specifying a custom detection location, only the location of the username field is required.
 
+The following table includes example detection locations for different request types:
+
+| Request type     | Username location / Password location                                                                           |
+| ---------------- | --------------------------------------------------------------------------------------------------------------- |
+| JSON body        | `lookup_json_string(http.request.body.raw, "user")`<br/>`lookup_json_string(http.request.body.raw, "secret")`   |
+| URL-encoded form | `url_decode(http.request.body.form["user"][0])`<br/>`url_decode(http.request.body.form["secret"][0])`           |
+| Multipart form   | `url_decode(http.request.body.multipart["user"][0])`<br/>`url_decode(http.request.body.multipart["secret"][0])` |
+
 Expressions used to specify custom detection locations can include the following fields and functions:
 
 - Fields: