diff --git a/public/__redirects b/public/__redirects index 3b58620dd5f522b..01b2ec9ad3a812c 100644 --- a/public/__redirects +++ b/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 diff --git a/src/content/docs/cloudflare-challenges/challenge-types/challenge-pages/additional-configuration.mdx b/src/content/docs/cloudflare-challenges/challenge-types/challenge-pages/additional-configuration.mdx index 77eebbec96e50fb..c376bda1837bd13 100644 --- a/src/content/docs/cloudflare-challenges/challenge-types/challenge-pages/additional-configuration.mdx +++ b/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" -``` \ No newline at end of file +``` + +## 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 `` tags or Transform Rules on Challenge Pages. Origin headers can be modified within the Challenge Page context and are not immutable, but they may cause issues. + +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 Page error types. Prefix your Transform Rule expression with the following logical exclusion: + +```txt wrap +not 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. \ No newline at end of file diff --git a/src/content/docs/cloudflare-challenges/challenge-types/challenge-pages/detect-response.mdx b/src/content/docs/cloudflare-challenges/challenge-types/challenge-pages/detect-response.mdx index 7f7b8fb8317e287..935b2f27fa1983b 100644 --- a/src/content/docs/cloudflare-challenges/challenge-types/challenge-pages/detect-response.mdx +++ b/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/). +``` \ No newline at end of file diff --git a/src/content/docs/cloudflare-challenges/challenge-types/challenge-pages/index.mdx b/src/content/docs/cloudflare-challenges/challenge-types/challenge-pages/index.mdx index e79bb57188526ed..c281eb77220b160 100644 --- a/src/content/docs/cloudflare-challenges/challenge-types/challenge-pages/index.mdx +++ b/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 + +Challenge Pages 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 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). diff --git a/src/content/docs/cloudflare-challenges/challenge-types/turnstile.mdx b/src/content/docs/cloudflare-challenges/challenge-types/turnstile.mdx index 5bef2f1c14f0365..cbd8882c78f26ba 100644 --- a/src/content/docs/cloudflare-challenges/challenge-types/turnstile.mdx +++ b/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. \ No newline at end of file +Refer to the [Turnstile documentation](/turnstile/get-started/) for guidance on implementing a widget to your website or application. diff --git a/src/content/docs/cloudflare-challenges/frequently-asked-questions.mdx b/src/content/docs/cloudflare-challenges/frequently-asked-questions.mdx deleted file mode 100644 index 59e63e302130636..000000000000000 --- a/src/content/docs/cloudflare-challenges/frequently-asked-questions.mdx +++ /dev/null @@ -1,117 +0,0 @@ ---- -title: FAQ -pcx_content_type: faq -sidebar: - order: 3 ---- - -## Why am I being challenged on a Cloudflare-protected site? - -Cloudflare issues Challenges to website visitors to protect against malicious activity such as bot attacks and DDoS attacks. Key reasons include: - -- **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, ensure your browser is up to date, disable any privacy tools that might block standard browser headers, or use a different network connection if your current one has a poor IP reputation. - -## How do I exclude certain requests from being blocked or challenged? - -In certain situations you want to enforce a blocking or challenging action but make an exception for specific types of requests. - -Cloudflare supports two methods of allowing requests using WAF custom rules: - -- Exclude a type of request from being blocked or challenged in a custom rule by updating the rule expression, for example adding an exclusion based on IP address, ASN, or country. -- Create a separate custom rule with a [_Skip_ action](/waf/custom-rules/skip/). This skip rule must appear before the rule with the block or challenge action in the rules list. - -The examples below illustrate a few possible approaches. - -**Example 1** - -Exclude multiple IP addresses from a blocking/challenging 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) - -**Example 2** - -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/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) - -## Do the Challenge actions support content types other than HTML (for example, AJAX or XHR requests)? - -Previously, unless you customize your front-end application, any AJAX request that is challenged will fail because AJAX calls are not rendered in the DOM. - -Now, you can [opt-in to Turnstile's Pre-clearance cookies](/cloudflare-challenges/concepts/clearance/#pre-clearance-support-in-turnstile). This allows you to issue a Challenge early in your web application flow and pre-clear users to interact with sensitive APIs. Clearance cookies issued by a Turnstile widget are automatically applied to the Cloudflare zone that the Turnstile widget is embedded on, with no configuration necessary. The duration of the clearance cookie's validity is controlled by the zone-specific configurable [Challenge Passage](/cloudflare-challenges/challenge-types/challenge-pages/challenge-passage/) security setting. - -## Why would I not find any failed Challenges? - -Users do not complete all Challenges. Cloudflare issues Challenges that are never answered — only 2-3% of all served Challenges are usually answered. - -There are multiple reasons for this: - -- Users give up on a Challenge. -- Users try to solve a Challenge but cannot provide an answer. -- Users keep refreshing the Challenge, but never submit an answer. -- Cloudflare receives a malformed Challenge answer. - -You can calculated the number of failed Challenges as follows: `number of Challenges issued - number of Challenges solved`. - -## Why do I have matches for a firewall rule that was not supposed to match the request? - -Make sure you are looking at the correct request. - -Only requests that triggered a Challenge will match the request parameters of the rule. Subsequent requests with a `[js]challengeSolved` action may not match the parameters of the rule — for example, the bot score may have changed because the user solved a Challenge. - -The "solved" action is an informative action about a previous request that matched a rule. This action states that "previously a rule had matched a request with the action set to _Interactive Challenge_ or _JS Challenge_ and now that Challenge was answered." - -## Are custom Content Security Policies (CSP) or custom error pages supported? - -You cannot set your own Content Security Policy (CSP) and/or Referer-Policy via meta tags or [Transform Rules](/rules/transform/) in Challenge Pages. - -Origin headers also cannot be modified for Challenge Pages. - -If you are setting any of these headers using Transform Rules for your entire website, you must prefix the rule with `not (starts_with(http.request.uri.path, "/cdn-cgi/challenge-platform/") or cf.response.error_type in {"managed_challenge" "iuam" "legacy_challenge" "country_challenge"})` in the rule expression to avoid issues with Challenges. \ No newline at end of file diff --git a/src/content/docs/cloudflare-challenges/reference/challenge-solve-rate.mdx b/src/content/docs/cloudflare-challenges/reference/challenge-solve-rate.mdx index 1565567fdc30000..7bf4711638f63ca 100644 --- a/src/content/docs/cloudflare-challenges/reference/challenge-solve-rate.mdx +++ b/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**. + +--- + +## 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 will 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. \ No newline at end of file diff --git a/src/content/docs/cloudflare-challenges/reference/index.mdx b/src/content/docs/cloudflare-challenges/reference/index.mdx index 4ed27cf2217939c..3c73331d54c60c4 100644 --- a/src/content/docs/cloudflare-challenges/reference/index.mdx +++ b/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 --- diff --git a/src/content/docs/cloudflare-challenges/troubleshooting/index.mdx b/src/content/docs/cloudflare-challenges/troubleshooting/index.mdx index 864a2289908d640..7ee23f4724fd0c1 100644 --- a/src/content/docs/cloudflare-challenges/troubleshooting/index.mdx +++ b/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). \ No newline at end of file +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. +::: + +
+ +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) +
+ +#### 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. + +
+ +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) +
diff --git a/src/content/docs/support/troubleshooting/general-troubleshooting/potential-isp-blocking.mdx b/src/content/docs/support/troubleshooting/general-troubleshooting/potential-isp-blocking.mdx index 2ef73d473938f34..0532965b69aff17 100644 --- a/src/content/docs/support/troubleshooting/general-troubleshooting/potential-isp-blocking.mdx +++ b/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). diff --git a/src/content/docs/waf/troubleshooting/faq.mdx b/src/content/docs/waf/troubleshooting/faq.mdx index 0fd14604b1bef3e..42656cad0dd66cc 100644 --- a/src/content/docs/waf/troubleshooting/faq.mdx +++ b/src/content/docs/waf/troubleshooting/faq.mdx @@ -64,7 +64,7 @@ ISP-level blocks are distinct from Cloudflare or site-owner security restriction When you create a custom rule with a _Block_, _Interactive Challenge_, _JS Challenge_, or _Managed Challenge (Recommended)_ action, you might unintentionally block traffic from known bots. Specifically, this might affect search engine optimization (SEO) and website monitoring when trying to enforce a mitigation action based on URI, path, host, ASN, or country. -Refer to [How do I exclude certain requests from being blocked or challenged?](/cloudflare-challenges/frequently-asked-questions/#how-do-i-exclude-certain-requests-from-being-blocked-or-challenged). +Refer to the [Challenges documentation](/cloudflare-challenges/troubleshooting/#allowlist-traffic-from-mitigation-actions) for more information. #### Bots currently detected