diff --git a/public/images/precursor/precursor-rules.png b/public/images/precursor/precursor-rules.png new file mode 100644 index 00000000000..b698fcdea23 Binary files /dev/null and b/public/images/precursor/precursor-rules.png differ diff --git a/public/images/precursor/precursor-settings.png b/public/images/precursor/precursor-settings.png new file mode 100644 index 00000000000..ca356012489 Binary files /dev/null and b/public/images/precursor/precursor-settings.png differ diff --git a/src/content/changelog/cloudflare-challenges/2026-06-30-precursor-session-based-detection.mdx b/src/content/changelog/cloudflare-challenges/2026-06-30-precursor-session-based-detection.mdx new file mode 100644 index 00000000000..8fc9fe0eb38 --- /dev/null +++ b/src/content/changelog/cloudflare-challenges/2026-06-30-precursor-session-based-detection.mdx @@ -0,0 +1,26 @@ +--- +title: Precursor introduces session-based detection +description: Precursor brings continuous, session-based behavioral detection to Cloudflare Challenges. +date: 2026-07-06 +--- + +Precursor is rolling out to all customers starting today. Precursor is client-side JavaScript that enables session-based bot detection. + +You can [read the announcement blog](https://blog.cloudflare.com/placeholder-precursor-announcement/) for background on why we built Precursor and how session-level behavioral detection works. + +With Precursor enabled, Cloudflare can: + +- Continuously evaluate behavioral signals across a session +- Re-validate challenge clearance as behavior changes +- Update bot scores with session context +- Provide client-side visibility where none previously existed + +It integrates with existing protections, including Security Rules, and can be enabled directly from the Cloudflare dashboard with configurable modes to balance security and user experience. + +Enable Precursor in the Cloudflare dashboard + +To learn more, refer to the [Precursor documentation](/cloudflare-challenges/precursor/). 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 bc5eb92be68..ae8b6bb512c 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 @@ -5,7 +5,7 @@ description: Full-page challenge screens that verify visitors before they reach products: - cloudflare-challenges sidebar: - order: 1 + order: 2 --- import { Render } from "~/components"; @@ -56,4 +56,4 @@ To ensure your API calls are protected without breaking single-page applications 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). \ No newline at end of file +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/javascript-detections.mdx b/src/content/docs/cloudflare-challenges/challenge-types/javascript-detections.mdx index 647e769e75b..6c0c6325f23 100644 --- a/src/content/docs/cloudflare-challenges/challenge-types/javascript-detections.mdx +++ b/src/content/docs/cloudflare-challenges/challenge-types/javascript-detections.mdx @@ -8,7 +8,7 @@ tags: - JavaScript - CSP sidebar: - order: 3 + order: 4 --- import { Render, Tabs, TabItem, GlossaryTooltip } from "~/components"; diff --git a/src/content/docs/cloudflare-challenges/challenge-types/turnstile.mdx b/src/content/docs/cloudflare-challenges/challenge-types/turnstile.mdx index 3a4bd64156f..befde70a189 100644 --- a/src/content/docs/cloudflare-challenges/challenge-types/turnstile.mdx +++ b/src/content/docs/cloudflare-challenges/challenge-types/turnstile.mdx @@ -5,7 +5,7 @@ description: Embed a CAPTCHA-alternative widget that verifies visitors without i products: - cloudflare-challenges sidebar: - order: 2 + order: 3 --- import { Render } from "~/components"; diff --git a/src/content/docs/cloudflare-challenges/concepts/clearance.mdx b/src/content/docs/cloudflare-challenges/concepts/clearance.mdx index 352ffe0dba9..40bb67e503e 100644 --- a/src/content/docs/cloudflare-challenges/concepts/clearance.mdx +++ b/src/content/docs/cloudflare-challenges/concepts/clearance.mdx @@ -14,13 +14,23 @@ import { Render, DashButton, Steps } from "~/components"; ## `cf_clearance` cookies -A `cf_clearance` cookie proves to Cloudflare that the visitor is a verified human and has passed the challenge presented to them. +A `cf_clearance` cookie proves to Cloudflare that the visitor is a verified human and has passed Cloudflare's client-side verifications. -The `cf_clearance` cookie is securely tied to the specific visitor and device it was issued to. This binding is a security feature designed to prevent the cookie from being easily transferred and re-used on other machines. +The cookie contains **two types of clearance** that work together: -As an additional layer of security, Cloudflare recommends that customers [add a rate limiting rule](/waf/rate-limiting-rules/) based on the `cf_clearance` cookie value. This ensures that a single, valid cookie cannot be abused by a single machine to send an excessive volume of requests. +- **Challenge clearance**: Granted when a visitor solves a Challenge (for example, Interstitial Challenge Pages or Turnstile with pre-clearance enabled). +- **Precursor clearance**: Continuously updated based on session behavior. -Each challenge type sets a clearance level. A higher-level cookie bypasses all challenge types at or below that level. A lower-level cookie only bypasses challenges at the same level. + +The cookie is securely tied to the specific visitor and device it was issued to, preventing reuse across machines. + +As an additional layer of security, Cloudflare recommends that customers [add a rate limiting rule](/waf/rate-limiting-rules/) based on the `cf_clearance` cookie value. This helps ensure that a single, valid cookie cannot be abused by one machine to send an excessive volume of requests. + +### Challenge clearance + +Challenge clearance is granted when a visitor successfully completes a Challenge. + +Each challenge type sets a clearance level. A higher-level clearance bypasses all Challenges at or below that level. A lower-level clearance only bypasses challenges at the same level. | Clearance level | Bypasses | | --------------------- | ---------------------------------------------------- | @@ -28,11 +38,25 @@ Each challenge type sets a clearance level. A higher-level cookie bypasses all c | Managed (medium) | Managed and Non-Interactive Challenges | | Non-Interactive (low) | Non-Interactive Challenges only | -If a visitor passes an Interactive Challenge (highest security level), then the `cf_clearance` cookie indicates this to the origin and allows the visitor to bypass any other Challenge on the website, whether it is a Non-Interactive Challenge, a Managed Challenge, or another Interactive Challenge for as long as the cookie is valid. +If a visitor passes an Interactive Challenge (highest security level), they can bypass all other Challenges for as long as the clearance remains valid. + +If a visitor receives clearance at a lower level (Managed or Non-Interactive) and later encounters a higher-level challenge, they must solve the higher-level challenge again. + +The original clearance is replaced if a higher-level challenge is later solved. + +Challenge clearance remains valid for the duration configured by the customer (Challenge Passage), **unless Precursor determines the session is suspicious**. -If a visitor receives a `cf_clearance` cookie on a page that uses a WAF rule with Managed or Non-Interactive Challenge (lower security levels), then encountering a different page with a higher security clearance level Challenge will prompt them to solve the challenge again. +### Precursor clearance + +Precursor clearance is continuously re-evaluated throughout a visitor’s session. Rather than being tied to a single challenge event, it operates as an ongoing, client-side process that periodically reassesses behavior at regular intervals. As new signals are observed, the clearance is updated dynamically to reflect the current level of trust in the session. + +If Precursor determines that a session is suspicious: + +- The visitor’s effective Challenge clearance may be **reduced or invalidated**. +- The visitor may be **re-challenged**, even if the cookie has not expired. + +This creates a model where clearance is both **time-bound (Interstitial)** and **behavior-bound (Precursor)**. -The original `cf_clearance` cookie that was issued to the visitor from a lower security clearance level challenge will be replaced with the new `cf_clearance` cookie from a higher security clearance level challenge. ## Pre-clearance support in Turnstile @@ -93,27 +117,26 @@ The prerequisite is crucial for pre-clearance to function properly. If set up co For more details on managing hostnames, refer to the [Hostname Management documentation](/turnstile/additional-configuration/hostname-management/). - #### Enable pre-clearance on a new site - 1. In the Cloudflare dashboard, go to the **Turnstile** page. - + 1. In the Cloudflare dashboard, go to **Turnstile**. + - 2. Select **Add widget**. - 3. Under **Would you like to opt for pre-clearance for this site?** select **Yes**. - 4. Choose the pre-clearance level from the select box. + 2. Select **Add widget**. + 3. Under **Would you like to opt for pre-clearance for this site?**, select **Yes**. + 4. Choose a **pre-clearance level**. 5. Select **Create**. #### Enable pre-clearance on an existing site - 1. In the Cloudflare dashboard, go to the **Turnstile** page. - + 1. In the Cloudflare dashboard, go to **Turnstile**. + - 2. Go to the existing widget or site and select **Settings**. - 3. Under **Would you like to opt for pre-clearance for this site?** select **Yes**. - 4. Choose the pre-clearance level from the select box. + 2. Select an existing widget and open **Settings**. + 3. Under **Would you like to opt for pre-clearance for this site?**, select **Yes**. + 4. Choose a **pre-clearance level**. 5. Select **Update**. diff --git a/src/content/docs/cloudflare-challenges/concepts/how-challenges-work.mdx b/src/content/docs/cloudflare-challenges/concepts/how-challenges-work.mdx index b54e993c097..44a9b4ad7e8 100644 --- a/src/content/docs/cloudflare-challenges/concepts/how-challenges-work.mdx +++ b/src/content/docs/cloudflare-challenges/concepts/how-challenges-work.mdx @@ -24,6 +24,8 @@ Challenge Pages and Turnstile rely on the same underlying mechanism to issue cha JavaScript Detections is an optional feature within [Bot Management](/bots/get-started/bot-management/). When enabled, Cloudflare injects a JavaScript snippet into HTML responses to gather client-side signals. Unlike Challenge Pages, JavaScript Detections runs on every HTML request without pausing or interrupting the visitor. It populates a pass/fail result (`cf.bot_management.js_detection.passed`) that you can then act on using a [WAF custom rule](/waf/custom-rules/). +For session-level detection that informs when challenges should be applied, refer to [Precursor](/cloudflare-challenges/precursor/). + --- ## Available challenges @@ -33,6 +35,7 @@ Refer to the following pages for more information on the different challenge typ - [Interstitial Challenge Pages](/cloudflare-challenges/challenge-types/challenge-pages/) - [Turnstile](/cloudflare-challenges/challenge-types/turnstile/) - [JavaScript Detections](/cloudflare-challenges/challenge-types/javascript-detections/) +- [Precursor](/cloudflare-challenges/precursor/) --- diff --git a/src/content/docs/cloudflare-challenges/precursor.mdx b/src/content/docs/cloudflare-challenges/precursor.mdx new file mode 100644 index 00000000000..bcf69f607b9 --- /dev/null +++ b/src/content/docs/cloudflare-challenges/precursor.mdx @@ -0,0 +1,100 @@ +--- +pcx_content_type: concept +title: Precursor +description: Client-side, session-based verification that continuously evaluates visitor behavior to identify automation. +products: + - cloudflare-challenges +sidebar: + order: 4 +--- + +Precursor is a client-side, session-based verification system that continuously evaluates a visitor's behavior over time. Instead of relying on a single challenge event, Precursor runs ongoing verification in the browser to detect automation that appears legitimate in individual requests but exhibits non-human patterns across a session. + +## How it works + +Precursor operates as a continuous client-side verification loop: + +- A client-side script is injected into the page +- The script continuously collects signals and performs verification +- Each execution produces signals that are evaluated by Cloudflare +- Results are used to update session state stored in the `cf_clearance` cookie +- The process repeats throughout the session + +This enables Cloudflare to continuously evaluate session behavior over time. + +## Get started + +Enable Precursor for your zone: + +1. In the Cloudflare dashboard, select your zone. +2. Go to **Security** > **Settings**. +3. Locate **Precursor**. +4. Turn on Precursor. + +Security Settings page in the Cloudflare dashboard, showing the Precursor card with the on/off toggle + +5. **Choose a mode:** To fully verify a user session, visitors may need to complete a lightweight Challenge to establish a valid session. Precursor provides two modes depending on whether you want to prioritize user experience or strict verification: + + - **Minimize Friction (default)** + Does not show a Challenge to the visitor. Instead, Precursor attempts to establish session state in the background. + This provides a smoother user experience, but cannot guarantee that every session is fully verified. + + - **Maximize Security (recommended)** + Shows a lightweight Challenge to establish a valid session if one does not already exist. + This ensures every session is fully verified, but may introduce additional friction for users. + +Precursor mode selector showing Minimize Friction and Maximize Security options + +For most customers, selecting a mode is the only configuration required. + +### Precursor rules (optional) + +Precursor runs across your zone by default. Rules do not enable or disable Precursor — they determine which mode applies to each request. + +For example: + +- Run **Minimize Friction** across your site, but run **Maximize Security** to enforce a valid session on `/checkout`. +- Run **Maximize Security** on all pages, except your homepage. + +## Relationship to JavaScript Detections + +Precursor supersedes JavaScript Detections (JSD): + +- moves from one-time execution to continuous verification +- introduces session-based state +- enables dynamic runtime control + +## Relationship to Challenges + +Precursor and Challenges serve different roles: + +- Challenges provide point-in-time verification +- Precursor provides continuous, session-level verification + +Precursor does not replace Challenges. Instead, it strengthens them by: + +- determining when additional Challenges should be required +- re-evaluating visitors after they have already passed a Challenge +- identifying automation that emerges over time + +## Relationship to `cf_clearance` + +Precursor is tightly integrated with `cf_clearance`. When running Precursor: + +- effective clearance may be reduced or invalidated +- additional Challenges may be triggered +- the visitor may be re-verified during the same session + +## Visibility in Security Analytics + +Once Precursor runs on a zone, its detections appear in the zone's Analytics view. To open it, select your zone in the Cloudflare dashboard, then go to **Security** > **Analytics** > **Traffic** > **Bot analysis**. The bot score distribution and WAF rule-match counts now include Precursor's behavioral and biometric detections. + +For more information, refer to [Security Analytics](/waf/analytics/security-analytics/). diff --git a/src/content/docs/cloudflare-challenges/reference/index.mdx b/src/content/docs/cloudflare-challenges/reference/index.mdx index 3c0a6f05993..aa76116964a 100644 --- a/src/content/docs/cloudflare-challenges/reference/index.mdx +++ b/src/content/docs/cloudflare-challenges/reference/index.mdx @@ -5,7 +5,7 @@ description: Reference information for Cloudflare Challenges, including browsers products: - cloudflare-challenges sidebar: - order: 3 + order: 5 group: hideIndex: true --- @@ -14,4 +14,4 @@ import { DirectoryListing } from "~/components" Refer to the following pages for more information about Cloudflare Challenges: - \ No newline at end of file + diff --git a/src/content/products/challenges.yaml b/src/content/products/challenges.yaml new file mode 100644 index 00000000000..017b483addb --- /dev/null +++ b/src/content/products/challenges.yaml @@ -0,0 +1,3 @@ +name: Challenges +slug: challenges +description: Cloudflare Challenges and bot detection