[Challenges] FAQ to docs

public/__redirects

@@ -361,6 +361,9 @@
 /realtime/introduction/ /realtime/realtimekit/introduction/ 302
 /realtime/concepts/ /realtime/realtimekit/concepts/ 302
 
+# Cloudflare Challenges
+/cloudflare-challenges/frequently-asked-questions/ /cloudflare-challenges/ 301
+
 # china network
 /support/about-cloudflare/enterprise-documentation/understanding-and-configuring-an-icp-number/ /china-network/concepts/icp/ 301
 /china-network/concepts/china-express/ /china-network/concepts/global-acceleration/ 301

src/content/docs/cloudflare-challenges/challenge-types/challenge-pages/additional-configuration.mdx

@@ -17,4 +17,18 @@ You can customize your favicon by using the HTML snippet below.
 
 ```html title="HTML element"
 <link rel="shortcut icon" href="<FAVICON_LINK>" />
-```
+```
+
+## Custom Content Security Policy (CSP) and error pages
+
+Cloudflare-served Challenge Pages operate in a strictly controlled environment to maximize security and ensure the challenge mechanism functions correctly. Because of this, you cannot set your own Content Security Policy (CSP) or Referer-Policy using `<meta>` tags or Transform Rules on Challenge Pages. Origin headers are also immutable within the Challenge Page context.
+
+If you have an active Transform Rule configured to modify HTTP response headers globally across your website, such as adding custom CSP headers), this rule will interfere with and cause the Challenge Page to fail.
+
+To prevent this conflict, you must modify your Transform Rule expression to explicitly exclude Challenge platform paths and Challenge error types. Prefix your Transform Rule expression with the following logical exclusion:
+
+```txt wrap
+not (starts_with(http.request.uri.path, "/cdn-cgi/challenge-platform/") or cf.response.error_type in "managed_challenge" "iuam" "legacy_challenge" "country_challenge")
+```
+
+This exclusion ensures that your custom header modification logic is only applied to traffic destined for your origin, allowing Cloudflare's Challenge Platform to function without being impacted by conflicting response headers.

src/content/docs/cloudflare-challenges/challenge-types/challenge-pages/detect-response.mdx

@@ -23,6 +23,4 @@ fetch("/my-api-endpoint").then((response) => {
 		// Process response as usual
 	}
 });
-```
-
-For additional help, refer to our [FAQ](/cloudflare-challenges/frequently-asked-questions/).
+```

src/content/docs/cloudflare-challenges/challenge-types/challenge-pages/index.mdx

@@ -44,3 +44,13 @@ With a JavaScript (JS) Challenge, Cloudflare makes the determination on whether
 The visitor must wait until their browser finishes processing the JavaScript, which typically takes less than five seconds.
 
 If the visitor passes the Challenge, the original request continues to the destination URL. If the Challenge fails or cannot be completed, the visitor is presented with another Interstitial Challenge Page.
+
+## Compatibility limitations
+
+Traditional Challenge actions, such as Managed Challenges, interrupt the request flow by returning a full HTML page for the user's browser to render and solve. This mechanism fails when the browser expects a non-HTML response, such as a JSON or XML payload from an AJAX or XHR (fetch) request.
+
+To ensure your API calls are protected without breaking single-page applications (SPAs) or API integrations, Cloudflare recommends using Turnstile Pre-clearance.
+
+By enabling Pre-clearance, the Turnstile widget issues a persistent clearance cookie (`cf_clearance`) upon successful human verification on an initial HTML page. This cookie pre-clears the visitor to interact with sensitive API endpoints secured by WAF rules, allowing you to deploy granular security without forcing a disruptive Challenge Page response.
+
+For implementation details, refer to the [guidance on Pre-clearance for Turnstile](/cloudflare-challenges/concepts/clearance/#pre-clearance-support-in-turnstile).

src/content/docs/cloudflare-challenges/challenge-types/turnstile.mdx

@@ -35,4 +35,4 @@ The sitekey is used with [client-side rendering](/turnstile/get-started/client-s
 
 ## Get started
 
-Refer to the [Turnstile documentation](/turnstile/get-started/) for guidance on implementing a widget to your website or application.
+Refer to the [Turnstile documentation](/turnstile/get-started/) for guidance on implementing a widget to your website or application.

src/content/docs/cloudflare-challenges/reference/challenge-solve-rate.mdx

@@ -27,3 +27,41 @@ You can find the CSR of a rule by going to its corresponding dashboard page:
 For [custom rules](/waf/custom-rules/) or [rate limiting rules](/waf/rate-limiting-rules/), go to your zone > **Security** > **Security rules**.
 
 </TabItem> </Tabs>
+
+---
+
+## Challenge actions in Security Events 
+
+If you find a Challenge Solved action, such as `[js]challengeSolved` or `challengeSolved`, in your Security Events that does not seem to match the underlying rule criteria, it is because this action refers to the successful mitigation of a previous request.
+
+The Challenge lifecycle involves two distinct events, which are crucial for interpreting your logs:
+
+- Challenge trigger: The original request matched a WAF custom rule with a Challenge action. This request contains the suspicious parameters that triggered the rule.
+- Challenge solved: The client's browser sends back a subsequent request containing the validated solution. This action is logged as Challenge Solved.
+
+The parameters of the solved request may no longer match the original rule's expression. For example, if a Challenge was issued due to a low Bot Score, the score for the solved request may have already changed to a non-suspicious value upon successful verification.
+
+The Challenge Solved action is purely an informative signal that a previously issued Challenge was answered, allowing the visitor's traffic to proceed. It does not imply that the subsequent request re-matched the initial trigger rule.
+
+---
+
+## Failed Challenges
+
+You might not find a dedicated metric for failed Challenges in Security Analytics because Cloudflare calculates failure indirectly, based on the difference between Challenges issued and Challenges solved.
+
+The system views any issued Challenge that does not result in a successful clearance cookie as a failure. This is why the number of failed Challenges may appear exceptionally high: the majority of issued Challenges are never completed.
+
+The official calculation for failures is:
+
+```txt
+Failed Challenges = Total Challenges Issued − Total Challenges Solved
+```
+
+The large number of unmatched Challenges is primarily due to automated traffic (bots or scrapers) that abandon the process immediately upon encountering the initial Challenge script.
+
+Key reasons a Challenge may be issued but never solved:
+
+- The visitor gives up on the Challenge or navigates away from the page.
+- The visitor attempts to solve the Challenge but cannot provide a valid answer.
+- The system receives an invalid or malformed answer from the client.
+- The script environment (often a bot's controlled browser) fails to run the necessary client-side checks.

src/content/docs/cloudflare-challenges/reference/index.mdx

@@ -2,7 +2,7 @@
 pcx_content_type: navigation
 title: Reference
 sidebar:
-  order: 4
+  order: 3
   group: 
     hideIndex: true
 ---

src/content/docs/cloudflare-challenges/troubleshooting/index.mdx

@@ -2,11 +2,11 @@
 pcx_content_type: troubleshooting
 title: Troubleshooting
 sidebar:
-  order: 5
+  order: 4
   label: Common issues
 ---
 
-import { Render } from "~/components"
+import { Render, Details } from "~/components"
 
 ## Common issues
 
@@ -28,4 +28,97 @@ You can add tracking scripts to Challenge Pages to capture the correct referer h
 
 ### Cross-origin resource sharing (CORS) preflight requests
 
-Cross-origin resource sharing (CORS) preflight requests, or `OPTIONS`, exclude user credentials that include cookies. As a result, the `cf_clearance` cookie will not be sent with the request, causing it to fail to bypass a Challenge Page (Non-interactive, Managed, or Interactive Challenge).
+Cross-origin resource sharing (CORS) preflight requests, or `OPTIONS`, exclude user credentials that include cookies. As a result, the `cf_clearance` cookie will not be sent with the request, causing it to fail to bypass a Challenge Page (Non-interactive, Managed, or Interactive Challenge).
+
+### Challenges on Cloudflare-protected sites
+
+Cloudflare issues Challenges to website visitors to protect against malicious activity, such as bot attacks and DDoS attempts. If a legitimate human visitor is unexpectedly challenged, the reason typically stems from a security feature flagging their request.
+
+| Source | Description |
+| --- | --- |
+| High threat score | IP addresses with a high-risk score trigger Challenges. |
+| IP reputation | If your IP has a history of suspicious activity, it may be flagged. |
+| Bot detection | Automated traffic resembling bots is filtered by Cloudflare. |
+| Web Application Firewall (WAF) custom rules | Site owners may set rules targeting specific regions or user agents. |
+| Browser Integrity Check | Cloudflare verifies that browsers meet certain standards. |
+| Challenge Passage | Technologies like Privacy Pass reduce the frequency of repeated Challenges. |
+
+To avoid repeated Challenges, visitors can take the following steps to ensure their environment does not trigger security checks:
+
+- Ensure your web browser is updated to the latest stable version for full compatibility with modern challenge technologies.
+- Temporarily disable browser extensions, such as ad blockers or privacy tools, that may block standard browser headers or the necessary Challenge scripts.
+- If your IP address has a poor reputation (often seen with shared VPNs or corporate proxies), try switching to a different, trusted network connection.
+
+### Allowlist traffic from mitigation actions
+
+If you need to prevent a **Block** or **Challenge** action from being applied to specific requests, such as known search engine crawlers, monitoring services, or internal APIs, you must configure an exclusion using [WAF custom rules](/waf/custom-rules/).
+
+Cloudflare supports two primary methods for creating these exclusions:
+
+#### 1. Use a Skip rule (recommended)
+
+The most robust method for creating an exception is to create a custom rule with the **Skip** action. This allows matching requests to bypass certain security features, including Bot Management and other WAF rules.
+
+:::note
+Due to the evaluation order, **Skip** rules must be positioned before the **Block** or **Challenge** rule they are designed to bypass.
+:::
+
+<Details header="Example">
+
+Block Amazon Web Services (AWS) and Google Cloud Platform (GCP) because of large volumes of undesired traffic, but allow Googlebot and other known bots that Cloudflare validates.
+
+- Basic rule, no exclusion:
+
+  - **Expression**: `(ip.src.asnum in {16509 15169} and not cf.client.bot)`
+  - **Action**: Block (or a challenge action)
+
+- Rule that excludes IP addresses from being blocked or challenged:
+
+  - **Expression**: `(ip.src.asnum in {16509 15169} and not cf.client.bot) and not (ip.src in {192.0.2.1 198.51.100.42 203.0.113.0/24})`
+  - **Action**: Block (or a challenge action)
+
+- Two rules to skip remaining custom rules for specific IPs and block the rest.
+
+  1. Rule 1:
+
+     - Expression: `ip.src in {192.0.2.1 198.51.100.42 203.0.113.0/24}`
+     - Action: Skip > All remaining custom rules
+
+  2. Rule 2:
+
+     - Expression: `(ip.src.asnum in {16509 15169} and not cf.client.bot)`
+     - Action: Block (or a challenge action)
+</Details>
+
+#### 2. Modify the Rule Expression
+
+You can refine the expression of a **Block** or **Challenge** rule to directly exclude known good traffic by using the logical not operator with an exclusion list, such as an IP list, country code, or ASN.
+
+This approach is useful for simple exclusions but can make complex rules more difficult to maintain than separate **Skip** rules.
+
+<Details header="Example">
+
+Exclude multiple IP addresses from a **Block** or **Challenge** rule that assesses attack score.
+
+- Basic rule, no exclusion:
+
+  - **Expression**: `(http.host eq "example.com" and cf.waf.score lt 20)`
+  - **Action**: Block (or a challenge action)
+
+- Rule that excludes IP addresses from being blocked/challenged:
+
+  - **Expression**: `(http.host eq "example.com" and cf.waf.score lt 20) and not (ip.src in {192.0.2.1 198.51.100.42 203.0.113.0/24})`
+  - **Action**: Block (or a challenge action)
+
+- Two rules to skip remaining custom rules for specific IPs and block the rest.
+
+  1. Rule 1:
+
+     - Expression: `ip.src in {192.0.2.1 198.51.100.42 203.0.113.0/24}`
+     - Action: Skip > All remaining custom rules
+
+  2. Rule 2:
+
+     - Expression: `(http.host eq "example.com" and cf.waf.score lt 20)`
+     - Action: Block (or a challenge action)
+</Details>

src/content/docs/support/troubleshooting/general-troubleshooting/potential-isp-blocking.mdx

@@ -15,4 +15,4 @@ Enterprise users can lease [static IPs](/byoip/concepts/static-ips/) or get thei
 
 It is important to note that an ISP-level block is distinct from other types of website blocking. For example, website owners may enforce certain restrictions (based upon IP, ASN, country, or other factors such as rate limiting) that will return [`1XXX` errors](/support/troubleshooting/http-status-codes/cloudflare-1xxx-errors/) in the HTML body of the response. Website owners configure these blocks, so issues need to be addressed directly with the website owner. For more information on website blocking, refer to the [Web Application Firewall FAQ](/waf/troubleshooting/faq/#why-have-i-been-blocked).
 
-For information on individual users being challenged when visiting Cloudflare-protected websites, refer to [Challenges FAQ](/cloudflare-challenges/frequently-asked-questions/#why-am-i-being-challenged-on-a-cloudflare-protected-site).
+For information on individual users being challenged when visiting Cloudflare-protected websites, refer to [Challenges on Cloudflare-protected sites](/cloudflare-challenges/troubleshooting/#challenges-on-cloudflare-protected-sites).