Skip to content

Commit ffd3115

Browse files
patriciasantaanapatriciasantaana
committed
FAQ to docs
1 parent a4070db commit ffd3115

File tree

6 files changed

+163
-117
lines changed

6 files changed

+163
-117
lines changed

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

Lines changed: 15 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -17,4 +17,18 @@ You can customize your favicon by using the HTML snippet below.
1717

1818
```html title="HTML element"
1919
<link rel="shortcut icon" href="<FAVICON_LINK>" />
20-
```
20+
```
21+
22+
## Custom Content Security Policy (CSP) and error pages
23+
24+
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.
25+
26+
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.
27+
28+
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:
29+
30+
```txt wrap
31+
not (starts_with(http.request.uri.path, "/cdn-cgi/challenge-platform/") or cf.response.error_type in "managed_challenge" "iuam" "legacy_challenge" "country_challenge")
32+
```
33+
34+
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/turnstile.mdx‎

Lines changed: 11 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -33,6 +33,16 @@ When you create a widget for your website or application via the Cloudflare dash
3333

3434
The sitekey is used with [client-side rendering](/turnstile/get-started/client-side-rendering/#implicitly-render-the-turnstile-widget) by adding it to the `<div>` container placeholder. You will then place that `<div>` code snippet where you want to add the widget to your site page or form.
3535

36+
### Compatibility limitations
37+
38+
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.
39+
40+
To ensure your API calls are protected without breaking single-page applications (SPAs) or API integrations, Cloudflare recommends using Turnstile Pre-clearance.
41+
42+
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.
43+
44+
For implementation details, refer to the [guidance on Pre-clearance for Turnstile](/cloudflare-challenges/concepts/clearance/#pre-clearance-support-in-turnstile).
45+
3646
## Get started
3747

38-
Refer to the [Turnstile documentation](/turnstile/get-started/) for guidance on implementing a widget to your website or application.
48+
Refer to the [Turnstile documentation](/turnstile/get-started/) for guidance on implementing a widget to your website or application.

‎src/content/docs/cloudflare-challenges/frequently-asked-questions.mdx‎

Lines changed: 1 addition & 111 deletions
Original file line numberDiff line numberDiff line change
@@ -2,116 +2,6 @@
22
title: FAQ
33
pcx_content_type: faq
44
sidebar:
5-
order: 3
5+
order: 5
66
---
77

8-
## Why am I being challenged on a Cloudflare-protected site?
9-
10-
Cloudflare issues Challenges to website visitors to protect against malicious activity such as bot attacks and DDoS attacks. Key reasons include:
11-
12-
- **High threat score**: IP addresses with a high-risk score trigger Challenges.
13-
- **IP reputation**: If your IP has a history of suspicious activity, it may be flagged.
14-
- **Bot detection**: Automated traffic resembling bots is filtered by Cloudflare.
15-
- **Web Application Firewall (WAF) custom rules**: Site owners may set rules targeting specific regions or user agents.
16-
- **Browser Integrity Check**: Cloudflare verifies that browsers meet certain standards.
17-
- **Challenge Passage**: Technologies like Privacy Pass reduce the frequency of repeated Challenges.
18-
19-
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.
20-
21-
## How do I exclude certain requests from being blocked or challenged?
22-
23-
In certain situations you want to enforce a blocking or challenging action but make an exception for specific types of requests.
24-
25-
Cloudflare supports two methods of allowing requests using WAF custom rules:
26-
27-
- 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.
28-
- 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.
29-
30-
The examples below illustrate a few possible approaches.
31-
32-
**Example 1**
33-
34-
Exclude multiple IP addresses from a blocking/challenging rule that assesses attack score.
35-
36-
- Basic rule, no exclusion:
37-
38-
- **Expression**: `(http.host eq "example.com" and cf.waf.score lt 20)`
39-
- **Action**: Block (or a challenge action)
40-
41-
- Rule that excludes IP addresses from being blocked/challenged:
42-
43-
- **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})`
44-
- **Action**: Block (or a challenge action)
45-
46-
- Two rules to skip remaining custom rules for specific IPs and block the rest.
47-
48-
1. Rule 1:
49-
50-
- Expression: `ip.src in {192.0.2.1 198.51.100.42 203.0.113.0/24}`
51-
- Action: Skip > All remaining custom rules
52-
53-
2. Rule 2:
54-
55-
- Expression: `(http.host eq "example.com" and cf.waf.score lt 20)`
56-
- Action: Block (or a challenge action)
57-
58-
**Example 2**
59-
60-
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.
61-
62-
- Basic rule, no exclusion:
63-
64-
- **Expression**: `(ip.src.asnum in {16509 15169} and not cf.client.bot)`
65-
- **Action**: Block (or a challenge action)
66-
67-
- Rule that excludes IP addresses from being blocked/challenged:
68-
69-
- **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})`
70-
- **Action**: Block (or a challenge action)
71-
72-
- Two rules to skip remaining custom rules for specific IPs and block the rest.
73-
74-
1. Rule 1:
75-
76-
- Expression: `ip.src in {192.0.2.1 198.51.100.42 203.0.113.0/24}`
77-
- Action: Skip > All remaining custom rules
78-
79-
2. Rule 2:
80-
81-
- Expression: `(ip.src.asnum in {16509 15169} and not cf.client.bot)`
82-
- Action: Block (or a challenge action)
83-
84-
## Do the Challenge actions support content types other than HTML (for example, AJAX or XHR requests)?
85-
86-
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.
87-
88-
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.
89-
90-
## Why would I not find any failed Challenges?
91-
92-
Users do not complete all Challenges. Cloudflare issues Challenges that are never answered — only 2-3% of all served Challenges are usually answered.
93-
94-
There are multiple reasons for this:
95-
96-
- Users give up on a Challenge.
97-
- Users try to solve a Challenge but cannot provide an answer.
98-
- Users keep refreshing the Challenge, but never submit an answer.
99-
- Cloudflare receives a malformed Challenge answer.
100-
101-
You can calculated the number of failed Challenges as follows: `number of Challenges issued - number of Challenges solved`.
102-
103-
## Why do I have matches for a firewall rule that was not supposed to match the request?
104-
105-
Make sure you are looking at the correct request.
106-
107-
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.
108-
109-
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."
110-
111-
## Are custom Content Security Policies (CSP) or custom error pages supported?
112-
113-
You cannot set your own Content Security Policy (CSP) and/or Referer-Policy via meta tags or [Transform Rules](/rules/transform/) in Challenge Pages.
114-
115-
Origin headers also cannot be modified for Challenge Pages.
116-
117-
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.

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

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -27,3 +27,41 @@ You can find the CSR of a rule by going to its corresponding dashboard page:
2727
For [custom rules](/waf/custom-rules/) or [rate limiting rules](/waf/rate-limiting-rules/), go to your zone > **Security** > **Security rules**.
2828

2929
</TabItem> </Tabs>
30+
31+
---
32+
33+
## Challenge actions in Security Events
34+
35+
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.
36+
37+
The Challenge lifecycle involves two distinct events, which are crucial for interpreting your logs:
38+
39+
- Challenge trigger: The original request matched a WAF custom rule with a Challenge action. This request contains the suspicious parameters that triggered the rule.
40+
- Challenge solved: The client's browser sends back a subsequent request containing the validated solution. This action is logged as Challenge Solved.
41+
42+
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.
43+
44+
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.
45+
46+
---
47+
48+
## Failed Challenges
49+
50+
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.
51+
52+
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.
53+
54+
The official calculation for failures is:
55+
56+
```txt
57+
Failed Challenges = Total Challenges Issued − Total Challenges Solved
58+
```
59+
60+
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.
61+
62+
Key reasons a Challenge may be issued but never solved:
63+
64+
- The visitor gives up on the Challenge or navigates away from the page.
65+
- The visitor attempts to solve the Challenge but cannot provide a valid answer.
66+
- The system receives an invalid or malformed answer from the client.
67+
- 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‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
pcx_content_type: navigation
33
title: Reference
44
sidebar:
5-
order: 4
5+
order: 3
66
group:
77
hideIndex: true
88
---

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

Lines changed: 97 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -2,11 +2,11 @@
22
pcx_content_type: troubleshooting
33
title: Troubleshooting
44
sidebar:
5-
order: 5
5+
order: 4
66
label: Common issues
77
---
88

9-
import { Render } from "~/components"
9+
import { Render, Details } from "~/components"
1010

1111
## Common issues
1212

@@ -28,4 +28,98 @@ You can add tracking scripts to Challenge Pages to capture the correct referer h
2828

2929
### Cross-origin resource sharing (CORS) preflight requests
3030

31-
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).
31+
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).
32+
33+
### Challenges on Cloudflare-protected sites
34+
35+
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.
36+
37+
| Source | Description |
38+
| --- | --- |
39+
| High threat score | IP addresses with a high-risk score trigger Challenges. |
40+
| IP reputation | If your IP has a history of suspicious activity, it may be flagged. |
41+
| Bot detection | Automated traffic resembling bots is filtered by Cloudflare. |
42+
| Web Application Firewall (WAF) custom rules | Site owners may set rules targeting specific regions or user agents. |
43+
| Browser Integrity Check | Cloudflare verifies that browsers meet certain standards. |
44+
| Challenge Passage | Technologies like Privacy Pass reduce the frequency of repeated Challenges. |
45+
46+
To avoid repeated Challenges, visitors can take the following steps to ensure their environment does not trigger security checks:
47+
48+
- Ensure your web browser is updated to the latest stable version for full compatibility with modern challenge technologies.
49+
- Temporarily disable browser extensions, such as ad blockers or privacy tools, that may block standard browser headers or the necessary Challenge scripts.
50+
- If your IP address has a poor reputation (often seen with shared VPNs or corporate proxies), try switching to a different, trusted network connection.
51+
52+
### Allowlist traffic from mitigation actions
53+
54+
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/).
55+
56+
Cloudflare supports two primary methods for creating these exclusions:
57+
58+
#### 1. Use a Skip rule (recommended)
59+
60+
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.
61+
62+
:::note
63+
Due to the evaluation order, **Skip** rules must be positioned before the **Block** or **Challenge** rule they are designed to bypass.
64+
:::
65+
66+
<Details header="Example">
67+
**Example 2**
68+
69+
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.
70+
71+
- Basic rule, no exclusion:
72+
73+
- **Expression**: `(ip.src.asnum in {16509 15169} and not cf.client.bot)`
74+
- **Action**: Block (or a challenge action)
75+
76+
- Rule that excludes IP addresses from being blocked or challenged:
77+
78+
- **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})`
79+
- **Action**: Block (or a challenge action)
80+
81+
- Two rules to skip remaining custom rules for specific IPs and block the rest.
82+
83+
1. Rule 1:
84+
85+
- Expression: `ip.src in {192.0.2.1 198.51.100.42 203.0.113.0/24}`
86+
- Action: Skip > All remaining custom rules
87+
88+
2. Rule 2:
89+
90+
- Expression: `(ip.src.asnum in {16509 15169} and not cf.client.bot)`
91+
- Action: Block (or a challenge action)
92+
</Details>
93+
94+
#### 2. Modify the Rule Expression
95+
96+
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.
97+
98+
This approach is useful for simple exclusions but can make complex rules more difficult to maintain than separate **Skip** rules.
99+
100+
<Details header="Example">
101+
102+
Exclude multiple IP addresses from a **Block** or **Challenge** rule that assesses attack score.
103+
104+
- Basic rule, no exclusion:
105+
106+
- **Expression**: `(http.host eq "example.com" and cf.waf.score lt 20)`
107+
- **Action**: Block (or a challenge action)
108+
109+
- Rule that excludes IP addresses from being blocked/challenged:
110+
111+
- **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})`
112+
- **Action**: Block (or a challenge action)
113+
114+
- Two rules to skip remaining custom rules for specific IPs and block the rest.
115+
116+
1. Rule 1:
117+
118+
- Expression: `ip.src in {192.0.2.1 198.51.100.42 203.0.113.0/24}`
119+
- Action: Skip > All remaining custom rules
120+
121+
2. Rule 2:
122+
123+
- Expression: `(http.host eq "example.com" and cf.waf.score lt 20)`
124+
- Action: Block (or a challenge action)
125+
</Details>

0 commit comments

Comments
 (0)