diff --git a/src/content/docs/bots/get-started/bot-fight-mode.mdx b/src/content/docs/bots/get-started/bot-fight-mode.mdx index d65076c633eea78..892a42b94d4ca74 100644 --- a/src/content/docs/bots/get-started/bot-fight-mode.mdx +++ b/src/content/docs/bots/get-started/bot-fight-mode.mdx @@ -41,29 +41,7 @@ Bot Fight Mode is a simple, free product that helps detect and mitigate bot traf To start using Bot Fight Mode: -{/* prettier-ignore-start */} - - - - - 1. In the Cloudflare dashboard, go to the **Security Settings** page. - - - 2. Filter by **Bot traffic**. - 3. Go to **Bot Fight Mode**. - 4. Turn **Bot Fight Mode** on. - - - - - 1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com/login), and select your account and domain. - 2. Go to **Security** > **Bots**. - 3. For **Bot Fight Mode**, select **On**. - - - - -{/* prettier-ignore-end */} + diff --git a/src/content/docs/turnstile/get-started/widget-management/dashboard.mdx b/src/content/docs/turnstile/get-started/widget-management/dashboard.mdx index 32264b323634ae4..e0b1a45a5bec95e 100644 --- a/src/content/docs/turnstile/get-started/widget-management/dashboard.mdx +++ b/src/content/docs/turnstile/get-started/widget-management/dashboard.mdx @@ -2,30 +2,17 @@ title: Create and manage widgets using the Cloudflare dashboard pcx_content_type: how-to sidebar: - order: 1 - label: Cloudflare dashboard + order: 1 + label: Cloudflare dashboard --- -import { Steps, DashButton } from "~/components"; - +import { Render } from "~/components"; The Cloudflare dashboard provides a user-friendly interface for creating and managing widgets. ## Create a widget - - 1. In the Cloudflare dashboard, go to the **Turnstile** page. - - - 2. Select **Add widget**. - 3. Fill out the required information: - - **Widget name**: A descriptive name for your widget. - - **Hostname management**: Domains where the widget will be used. - - **Widget mode**: Choose from Managed, Non-Interactive, or Invisible. - 4. (Optional) Configure **Pre-clearance support** for single-page applications. - 5. Select **Create** to save your widget. - 6. Copy your sitekey and secret key, and store the secret key securely. - + ## Manage existing widgets diff --git a/src/content/docs/use-cases/application-security/block-attacks.mdx b/src/content/docs/use-cases/application-security/block-attacks.mdx index 2e9157a5e98b4cd..47690b5e32a8a4d 100644 --- a/src/content/docs/use-cases/application-security/block-attacks.mdx +++ b/src/content/docs/use-cases/application-security/block-attacks.mdx @@ -29,3 +29,5 @@ Limit request rates based on flexible matching criteria. [Learn more about rate 1. [Deploy WAF managed rulesets](/waf/managed-rules/deploy-zone-dashboard/) 2. [Create custom rules](/waf/custom-rules/create-dashboard/) 3. [Configure rate limiting rules](/waf/rate-limiting-rules/create-zone-dashboard/) + +For WAF custom rules and rate limiting patterns specific to bot traffic, refer to [Stop malicious bots while allowing legitimate traffic](/use-cases/application-security/bots/stop-malicious-bots/). diff --git a/src/content/docs/use-cases/application-security/bots.mdx b/src/content/docs/use-cases/application-security/bots.mdx deleted file mode 100644 index 4a36d6ccea28785..000000000000000 --- a/src/content/docs/use-cases/application-security/bots.mdx +++ /dev/null @@ -1,36 +0,0 @@ ---- -pcx_content_type: how-to -title: Stop malicious bots -description: Detect and block automated threats while allowing legitimate traffic. -sidebar: - order: 4 ---- - -Malicious bots perform credential stuffing, content scraping, and inventory hoarding. Cloudflare Bot Security uses machine learning to score every request, blocking automated threats while allowing legitimate bots like search engine crawlers. - -## Solutions - -### Bot security - -Machine learning powered bot detection with granular control over bot traffic. [Learn more about bot security](/bots/). - -- **Bot scores** - Every request receives an ML-derived bot score from 1 (bot) to 99 (human) -- **Verified bots** - Allow known good bots like search engine crawlers while blocking malicious ones - -### Super Bot Fight Mode - -Basic bot protection included with Pro plans and above. [Learn more about Super Bot Fight Mode](/bots/get-started/super-bot-fight-mode/). - -- **Challenge pages** - Present JavaScript (JS) or managed challenges to suspicious traffic on Pro plans and above - -### Turnstile - -Privacy-preserving CAPTCHA alternative for forms and user interactions. [Learn more about Turnstile](/turnstile/). - -- **Form protection** - Privacy-preserving CAPTCHA alternative that protects login, signup, and checkout forms without friction - -## Get started - -1. [Enable Bot Fight Mode](/bots/get-started/bot-fight-mode/) (Free plan) -2. [Configure Super Bot Fight Mode](/bots/get-started/super-bot-fight-mode/) (Pro plan and above) -3. [Add Turnstile to forms](/turnstile/get-started/) diff --git a/src/content/docs/use-cases/application-security/bots/index.mdx b/src/content/docs/use-cases/application-security/bots/index.mdx new file mode 100644 index 000000000000000..059801d06d086d1 --- /dev/null +++ b/src/content/docs/use-cases/application-security/bots/index.mdx @@ -0,0 +1,39 @@ +--- +pcx_content_type: how-to +title: Stop malicious bots +description: Detect and block automated threats while allowing legitimate traffic. +sidebar: + order: 4 +--- + +Malicious bots perform credential stuffing, content scraping, and inventory hoarding. Cloudflare provides multiple tools to detect and block automated threats while allowing legitimate bots like search engine crawlers. + +For a step-by-step workflow that combines these tools into a layered defense, refer to [Stop malicious bots while allowing legitimate traffic](/use-cases/application-security/bots/stop-malicious-bots/). + +## Solutions + +### Bot Fight Mode + +Baseline bot protection available on all plans, including Free. Challenges requests that match known bot patterns. [Learn more about Bot Fight Mode](/bots/get-started/bot-fight-mode/). + +### Super Bot Fight Mode + +Granular bot controls for Pro plans and above. Allows verified bots, configures per-category actions, and extends protection to static resources. [Learn more about Super Bot Fight Mode](/bots/get-started/super-bot-fight-mode/). + +### Bot Management + +Machine learning-powered bot detection for Enterprise. Assigns a bot score from 1 (bot) to 99 (human) to every request. [Learn more about Bot Management](/bots/). + +### Turnstile + +Privacy-preserving challenge for forms and user interactions. Available on all plans at no cost. [Learn more about Turnstile](/turnstile/). + +### WAF custom rules + +Targeted rules that act on bot scores, headers, and request patterns. Available on all plans. [Learn more about WAF custom rules](/waf/custom-rules/). + +## Get started + +1. [Stop malicious bots while allowing legitimate traffic](/use-cases/application-security/bots/stop-malicious-bots/) — layered defense guide covering all products above +2. [Enable Bot Fight Mode](/bots/get-started/bot-fight-mode/) — quickest single step (Free plan) +3. [Add Turnstile to forms](/turnstile/get-started/) — protect login and signup forms diff --git a/src/content/docs/use-cases/application-security/bots/stop-malicious-bots.mdx b/src/content/docs/use-cases/application-security/bots/stop-malicious-bots.mdx new file mode 100644 index 000000000000000..2e11dc6f5226f7a --- /dev/null +++ b/src/content/docs/use-cases/application-security/bots/stop-malicious-bots.mdx @@ -0,0 +1,425 @@ +--- +pcx_content_type: solution-guide +title: Stop malicious bots while allowing legitimate traffic +description: Block malicious bots while allowing legitimate traffic using Bot Fight Mode, Turnstile, custom rules, and rate limiting. +sidebar: + label: Stop malicious bots +--- + +import { Tabs, TabItem, Render } from "~/components"; + +Automated traffic targets sites in different ways: credential stuffing on login pages, scraping product data, spamming contact forms. The right defense depends on which of these apply to your site and what plan you are on. This guide covers a layered approach using Cloudflare tools, from baseline protection to targeted custom rules. The core workflow uses features on Free and Pro plans, with callouts for advanced options on higher tiers. + +## Review your bot traffic + +Before you change any bot settings, review your traffic data. Making changes without understanding your traffic risks blocking legitimate visitors or missing the bots that cause the most damage. + +### Find your bot analytics + +Bot analytics show you how much of your traffic is automated, which pages bots target, and how Cloudflare scores each request. + +:::note[Bot Analytics requires a Business plan or above] +Bot score distribution data and detailed bot analytics are available on Business and Enterprise plans. Free and Pro plan users can review basic security metrics through **Security** > **Events**. For full bot analytics capabilities, refer to [Bot Analytics](/bots/bot-analytics/). +::: + + + + +1. In the Cloudflare dashboard, go to **Security** > **Analytics** > **Bot analysis**. + + + + +1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com/login) and select your account and domain. +2. Go to **Security** > **Bots**. + + + + +Review the following: + +- **Bot score distribution chart**: Scores closer to 1 indicate automated traffic. Scores closer to 99 indicate human traffic. +- **Top requested paths**: Which endpoints receive the most bot traffic. Login pages, API endpoints, and checkout flows are common targets. +- **Traffic patterns**: Sudden spikes in low-score traffic, specific user agents appearing at high volume, or geographic concentration of requests all indicate bot activity worth investigating. + +### Understand bot categories + +Cloudflare classifies bot traffic into categories based on bot scores and verification status: + +- **Verified bots**: Crawlers and services that Cloudflare has confirmed as legitimate, such as Googlebot, Bingbot, and uptime monitors. Cloudflare maintains a [verified bot list](/bots/concepts/bot/verified-bots/policy/) with strict requirements. Always allow verified bots through your protections. +- **Automated** (score 1): Definitely a bot. Cloudflare is highly confident the request is automated. +- **Likely automated** (scores 2-29): Probably a bot. This category and Automated are your primary targets — scrapers, credential stuffing tools, inventory hoarding bots, and spam submitters. +- **Likely human** (scores 30-99): These requests appear to come from real users. Do not challenge or block this traffic. + +## Block automated traffic with Bot Fight Mode + +Bot Fight Mode identifies requests that match known bot patterns and issues a computational challenge. It reduces automated traffic across your entire site without requiring you to write any rules. + +### What Bot Fight Mode does and does not do + +Bot Fight Mode is available on all Cloudflare plans, including Free. It provides broad, baseline protection. Understanding what it does and does not do helps you decide whether to turn it on and which additional layers you need. + +**What it does:** + +- Identifies requests that match known bot patterns using Cloudflare heuristics +- Issues a computational challenge (a background test that bots fail and browsers pass silently) to suspected bots rather than hard-blocking them +- Applies site-wide with no additional configuration + +**What it does not do:** + +- Does not distinguish between good bots (such as Googlebot) and bad bots. All automated traffic receives the same challenge. +- Does not protect specific URL paths more than others. The challenge applies uniformly across your site. +- Cannot be bypassed with WAF custom rule Skip actions. If Bot Fight Mode challenges a request you want to allow, your only options are IP Access rules or turning off Bot Fight Mode entirely. + +### Turn on Bot Fight Mode + + + +Bot Fight Mode begins challenging suspected bot traffic immediately. + +### Upgrade to Super Bot Fight Mode + +If you need to allow verified bots while still challenging malicious ones, Super Bot Fight Mode provides more granular controls: + +- **Verified bot allowlisting** — automatically allows known good bots through without challenges +- **Per-category actions** — configure different responses for definitely automated, likely automated, and verified bot traffic +- **Static resource protection** — extends bot detection to static assets like images and scripts +- **JavaScript detections** — uses client-side signals for additional bot identification + +For setup instructions, refer to [Super Bot Fight Mode](/bots/get-started/super-bot-fight-mode/). + +:::note[Super Bot Fight Mode requires a Pro plan or above] +Super Bot Fight Mode is available on Pro, Business, and Enterprise plans. Free plan users can use Bot Fight Mode for baseline protection. +::: + +:::caution +If your organization uses [Cloudflare Tunnel](/cloudflare-one/networks/connectors/cloudflare-tunnel/), set **Definitely Automated** to **Allow** in Super Bot Fight Mode. Otherwise, tunnel connections may fail with a `websocket: bad handshake` error. +::: + +:::note[Enterprise Bot Management] +For organizations that need machine learning-based bot scoring, behavioral analysis, and custom allow/block rules, Cloudflare Bot Management provides the most granular detection and response capabilities. Bot Management assigns a score from 1 (likely bot) to 99 (likely human) to every request, which you can reference in custom rules. For more information, refer to [Bot Management](/bots/plans/bm-subscription/). +::: + +## Protect forms from automated abuse + +Forms are among the most common targets for automated abuse. Login forms receive credential stuffing attempts that test stolen passwords against real accounts. Registration forms attract bots that create fake accounts for spam or fraud. Contact forms collect phishing links and advertising spam. + +Two tools protect form endpoints: Turnstile and rate limiting. They solve different problems and work best together. + +### Turnstile versus rate limiting + +**Turnstile** verifies that a visitor is human at the point of form submission. It prevents a single bot from submitting a form even once. Use Turnstile when you need to confirm the visitor is a real person before processing their input. + +**Rate limiting** caps the number of requests a client can make to an endpoint within a time window. It prevents volumetric abuse — the same IP hitting your login endpoint hundreds of times per minute. Use rate limiting when you need to control request volume regardless of whether the client is human. + +**Both together** provide the strongest coverage. Turnstile blocks automated submissions at the form level. Rate limiting catches high-volume attacks that bypass or do not encounter the form, such as direct `POST` requests to the endpoint that skip the client-side widget. + +### Add Turnstile to a form + +Turnstile is a free, privacy-preserving challenge that verifies visitors are human before they submit a form. Unlike traditional CAPTCHAs, Turnstile does not require users to solve visual puzzles. In Managed mode, most visitors pass without any visible interaction. + +Adding Turnstile involves three steps: create a widget, add the client-side snippet, and validate the token on your server. + +**1. Create a Turnstile widget** + + + +You need both the sitekey and secret key in the following steps. + +**2. Add the client-side snippet** + +Add the Turnstile script and widget container to your form HTML: + +```html + + +
+ +
+ +
+``` + +Replace `` with the site key from the previous step. The widget renders inside the `div` and produces a token when the visitor passes the challenge. + +**3. Validate the token on your server** + +Before processing the form submission, send the token to the Turnstile siteverify endpoint to confirm the visitor passed the challenge: + +```bash +curl "https://challenges.cloudflare.com/turnstile/v0/siteverify" \ + --header "Content-Type: application/json" \ + --data '{ + "secret": "", + "response": "" +}' +``` + +Replace `` with your secret key and `` with the `cf-turnstile-response` value from the form submission. The endpoint returns a JSON object with a `success` field. Only process the form submission if `success` is `true`. + +For complete integration details, refer to [Turnstile get started](/turnstile/get-started/). + +:::note[Turnstile is free on all plans] +Turnstile is available at no cost on all Cloudflare plans, including Free. You do not need a paid plan to add Turnstile to your forms. Turnstile also works on sites that are not proxied through Cloudflare. Refer to [Turnstile](/turnstile/) for full documentation. +::: + +### Rate limit form endpoints + +For login endpoints, a tiered rate limiting approach works well alongside Turnstile. Create rules that escalate the response based on the volume of failed attempts: + +- **Short-window rule**: If a single IP sends more than 4 `POST` requests to `/login` that return `401` or `403` within 1 minute, issue a Managed Challenge. +- **Long-window rule**: If a single IP accumulates more than 20 failed login attempts within 1 hour, block the IP for 24 hours. + +This pattern uses a counting expression that only counts `POST` requests returning authentication failure codes. Legitimate users who log in successfully on the first attempt never trigger the rule. + +Deploy both rules with the **Log** action first. Review the results in **Security** > **Events** after 24-48 hours to confirm the thresholds are not catching legitimate users. Then change to the enforcing actions. + +For step-by-step rule creation, refer to [Create a rate limiting rule in the dashboard](/waf/rate-limiting-rules/create-zone-dashboard/). For the full tiered credential stuffing example, refer to [Rate limiting best practices](/waf/rate-limiting-rules/best-practices/). + +:::note[Tiered rate limiting rules require a Business plan or above] +Rules that use counting expressions with response codes (such as counting only `401` and `403` responses) require a Business plan or above. On Free and Pro plans, you can create simpler rate limiting rules with IP-based counting. Refer to [Rate limiting rules](/waf/rate-limiting-rules/) for plan availability details. +::: + +## Target bot patterns with custom rules + +After turning on built-in bot protection, you may still see automated traffic that slips through. Bots that omit standard headers, hammer specific paths, or mimic browsers just well enough to avoid heuristic detection require targeted rules. + +Custom rules and rate limiting rules let you act on specific traffic patterns. Cloudflare separates detection (scoring traffic) from mitigation (acting on those scores). Detections like bot score label incoming requests, but they do not block anything on their own. You write rules that reference those signals to decide what action to take. + +### Block requests with missing or suspicious headers + +Legitimate browsers always send headers like `User-Agent`, `Accept`, and `Accept-Language`. Many bots omit these headers or send non-browser values. A custom rule targeting requests with empty or suspicious headers catches bots that evade score-based detection. + +Before creating custom rules, review the built-in bot settings under **Security Settings** > **Bot traffic**. These settings handle common scenarios without requiring you to write expressions: + +| Use case | Setting | +| ----------------------------------------------- | ------------------------------ | +| Block AI crawlers | **Block AI bots** | +| Block definitely automated traffic (score 1) | **Definitely automated** | +| Challenge likely automated traffic (score 2-29) | **Likely automated** | +| Allow verified bots | **Verified bots** | +| Extend protection to static resources | **Static resource protection** | + +If the built-in settings do not cover your needs, create custom rules. Start by creating an exception for verified bots so they are protected before you deploy any blocking rules. + +**First, create a verified bot exception:** + + + + +1. In the Cloudflare dashboard, go to the **Security rules** page. +2. Select **Create rule** > **Custom rules**. + + + + +1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com), and select your account and domain. +2. Go to **Security** > **WAF** > **Custom rules**. +3. Select **Create rule**. + + + + +Use the expression: + +```txt +(cf.client.bot) +``` + +Set the action to **Skip** > **All remaining custom rules**. This ensures verified bots (search engine crawlers, monitoring services) bypass your custom rules. Place this rule at the top of your custom rule list so it executes first. + +**Then, create a blocking rule:** + +Create a second custom rule that targets requests with missing or suspicious headers. For example, to challenge requests to `/login` with an empty user agent: + +```txt +(http.request.uri.path eq "/login" and http.user_agent eq "") +``` + +Set the action to **Log** first. This lets you observe which requests the rule matches without blocking legitimate traffic. After 24-48 hours, review the results in **Security** > **Events**. If the rule matches only bot traffic, change the action to **Managed Challenge** or **Block**. + +For step-by-step rule creation, refer to [Create a custom rule in the dashboard](/waf/custom-rules/create-dashboard/). + +:::note[Custom rule availability by plan] +All Cloudflare plans include custom rules. The number of available rules increases with higher plans. For the full availability breakdown, refer to [Custom rules](/waf/custom-rules/#availability). +::: + +If your bot traffic is concentrated from countries where you have no real users, you can combine geographic filters with the rules above. Add `ip.src.country` to your expression to restrict the rule to specific regions. For examples, refer to [Block traffic by geographical location](/waf/custom-rules/use-cases/block-by-geographical-location/). + +### Rate limit high-frequency paths + +Beyond form endpoints (covered in the previous section), bots also target checkout flows, API endpoints, and other high-value paths with high-frequency requests. Rate limiting rules cap the number of requests a single client can make to these paths within a time window. + +The key challenge is choosing the right threshold. Set it too low and you block legitimate users. Set it too high and bots slip through. + +1. Identify which paths to protect. Prioritize checkout flows, API endpoints, and any path that triggers expensive operations. +2. Estimate the normal request rate. Consider how many times a legitimate user would hit the endpoint in a one-minute window. +3. Create a rate limiting rule with a conservative threshold. Start with the Log action to observe what the rule would match without blocking: + - **Expression**: `http.request.uri.path eq "/api/checkout" and http.request.method eq "POST"` + - **Counting characteristic** (the field used to group requests): IP address + - **Rate**: 10 requests per 1 minute + - **Action**: Log +4. Review the results in **Security** > **Events** after 24-48 hours. Check whether any legitimate traffic would have been blocked. +5. Once you are confident the threshold is correct, change the action from Log to **Managed Challenge** or **Block**. + +For step-by-step rule creation, refer to [Create a rate limiting rule in the dashboard](/waf/rate-limiting-rules/create-zone-dashboard/). For additional patterns and thresholds, refer to [Rate limiting best practices](/waf/rate-limiting-rules/best-practices/). + +:::note[Security Analytics rate analysis requires an Enterprise plan] +Enterprise customers can use the **Request rate analysis** tab in Security Analytics to visualize request rate distributions and set thresholds using an interactive slider. On Free, Pro, and Business plans, estimate thresholds based on your expected traffic patterns and use the Log action to validate before enforcing. Refer to [Find an appropriate rate limit](/waf/rate-limiting-rules/find-rate-limit/) for the full methodology. +::: + +### Use bot score in custom rules + +:::note[Bot score in custom rules requires Enterprise Bot Management] +The `cf.bot_management.score` field is only available to Enterprise customers who have purchased Bot Management. Pro and Business customers can see bot traffic divided into groupings (Automated, Likely automated, Likely human, Verified bot) in the dashboard, but cannot reference granular bot scores in custom rule expressions. On Free plans, use `cf.client.bot` to identify verified bots. Refer to [Bot scores](/bots/concepts/bot-score/) for details on each plan's capabilities. +::: + +Bot score gives you a numeric signal to distinguish automated traffic from human visitors. Each request receives a score from 1 to 99, where lower scores indicate more automated behavior: + +| Score | Category | Meaning | +| ----- | ---------------- | ------------------------------------------------ | +| 0 | Not computed | Bot score was not calculated for this request | +| 1 | Automated | Definitely a bot | +| 2-29 | Likely automated | Probably a bot | +| 30-99 | Likely human | Probably a real user | +| N/A | Verified bot | Known good bot (Googlebot, Bingbot, and similar) | + +You reference the `cf.bot_management.score` field in custom rule expressions to act on these scores. For example, to challenge likely automated traffic on your checkout page, build a rule with the following conditions: + +| Field | Operator | Value | +| -------------------- | -------------- | ----------- | +| Bot Management Score | less than | `30` | +| URI Path | equals | `/checkout` | +| Verified Bot | does not equal | `true` | + +If you prefer the expression editor, the equivalent expression is: + +```txt +(cf.bot_management.score lt 30 and http.request.uri.path eq "/checkout" and not cf.bot_management.verified_bot) +``` + +Set the action to **Managed Challenge**. This rule challenges requests with a bot score under 30 on the checkout path while allowing verified bots through. + +For broader protection, use a layered set of rules ordered by priority: + + + +Deploy these rules in order so the Skip rule executes first. Set rules 2 and 3 to **Log** initially, review the matched traffic in **Security** > **Events** for 24-48 hours, then change to **Block** and **Managed Challenge** once you confirm the thresholds are not catching legitimate traffic. + +For the full list of bot management fields available in rule expressions, refer to [Bot Management variables](/bots/reference/bot-management-variables/). + +## Verify and tune your rules + +After you deploy bot protection rules, verify that they block malicious traffic without interfering with legitimate visitors. Security Events shows you what your rules are doing in real time. Use that data to tune thresholds and create exceptions before problems affect real users. + +### Check Security Events + +Security Events displays every request that Cloudflare mitigated — blocked, challenged, or flagged. This is where you confirm your rules are working as intended. + + + + +1. In the Cloudflare dashboard, go to the **Analytics** page. +2. Select the **Events** tab. + + + + +1. In the Cloudflare dashboard, go to **Security** > **Events**. + + + + +Review the following sections: + +- **Events summary**: Overview of mitigated requests over time. +- **Events by service**: Which rules are triggering. Events are labeled by their source: Bot Fight Mode, Super Bot Fight Mode, custom rules, or rate limiting rules. +- **Sampled logs**: Individual request details. Each log entry shows the action taken, the rule that triggered, the source IP, user agent, URI path, and country. + +Look for false positives — legitimate traffic that your rules incorrectly challenged or blocked. Common signs include: + +- Requests from known monitoring services or payment processors appearing in blocked events +- User agents matching legitimate browsers but receiving challenges +- High volumes of challenged requests from countries where you have real users + +Bot Fight Mode and Super Bot Fight Mode are aggressive by design. False positives are expected, especially in the first few days after turning them on. The key difference between the two is how you handle exceptions: + +- **Bot Fight Mode** (Free) cannot be bypassed with WAF custom rule Skip actions. Your options are IP Access rules or turning off Bot Fight Mode entirely. +- **Super Bot Fight Mode** (Pro and above) can be bypassed with WAF custom rules using the Skip action, giving you more flexibility to create exceptions. + +For more information on handling false positives, refer to [False positives](/bots/troubleshooting/false-positives/). + +### Tune based on what you see + +After reviewing Security Events for 24-48 hours, you will likely need to adjust your rules. Here are three common scenarios and how to address each one. + +**Scenario 1: Verified bots are being challenged.** + +Search engine crawlers like Googlebot or Bingbot appear in your challenged or blocked events. Create a WAF custom rule with a Skip action that allows verified bots through: + +- **Expression**: `(cf.bot_management.verified_bot)` (Pro and above) or `(cf.client.bot)` (all plans) +- **Action**: Skip > All remaining custom rules + +Place this rule at the top of your custom rule list so it executes first. On Free plans where Bot Fight Mode cannot be bypassed with Skip actions, add the bot IP ranges to your IP Access Allow list instead. + +**Scenario 2: Your monitoring tools or services are being blocked.** + +Internal monitoring tools, health check services, or partner APIs appear in blocked events. The fix depends on which feature is blocking them: + +- If **Super Bot Fight Mode** (Pro and above) is blocking the traffic, create a WAF custom rule with a Skip action matching the tool IP address or user agent. For example: `(ip.src eq 192.0.2.1)` with action **Skip** > **Skip Super Bot Fight Mode**. +- If **Bot Fight Mode** (Free) is blocking the traffic, add the tool IP address to your IP Access Allow list. Bot Fight Mode does not trigger when an IP Access rule matches the request. + +For details on Skip action configuration, refer to [WAF custom rules Skip action](/waf/custom-rules/skip/). + +**Scenario 3: Malicious traffic is still getting through.** + +You see bot activity in your logs that your current rules do not catch. Tighten your defenses: + +- **Lower your bot score threshold.** If you are challenging traffic with scores below 30, try lowering the threshold to challenge scores below 50. Monitor for false positives after each change. +- **Add path-specific rules.** Create custom rules that apply stricter thresholds to your most targeted paths. For example, challenge all traffic with a bot score below 50 on `/login` while keeping the site-wide threshold at 30. +- **Combine signals.** Use multiple fields in a single expression for more precise targeting. For example, challenge requests to `/login` that have a low bot score and an empty `Accept-Language` header: + + ```txt + (http.request.uri.path eq "/login" and cf.bot_management.score lt 30 and len(http.request.headers["accept-language"][0]) eq 0) + ``` + +Custom rules execute before Super Bot Fight Mode in the WAF evaluation order. A custom rule that takes a terminating action (Block, Managed Challenge) prevents the request from reaching Super Bot Fight Mode. Keep this in mind when troubleshooting why a rule does not appear to trigger. For details on rule execution order, refer to [WAF feature interoperability](/waf/feature-interoperability/). + +### Set up alerts + +Bot attacks can spike without warning. Set up alerts so you are notified when automated traffic increases, rather than discovering the problem after it affects your site. + +1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com/login) and select your account. +2. Go to **Notifications**. +3. Select **Add**. +4. Select **Bot Management** from the product list. +5. Choose an alert type: + - **Bot Detection Alert** — notifies you when Cloudflare detects an abnormal spike in bot traffic. The alert triggers when the Z-score (a statistical measure of how far bot traffic deviates from normal) exceeds 3.5 and bot requests exceed 200 per five-minute window. + - **Custom Bot Detection Alert** — allows filtering by user agent, hostname, URI path, IP address, ASN, JA3 TLS fingerprint, JA4 TLS fingerprint, or Bot Detection IDs. Also supports grouping by JA4 fingerprint, ASN, or Bot Detection IDs. +6. Enter a notification name and optional description. +7. Select the domains to monitor. +8. Configure a delivery method (email, PagerDuty, or webhook). +9. Select **Save**. + +Bot Detection Alerts exclude verified bots, so legitimate crawler traffic does not trigger false alert spikes. + +For general notification configuration and delivery method options, refer to [Notifications](/notifications/). + +:::note[Custom Bot Detection Alerts require Bot Management] +Custom Bot Detection Alerts with advanced filtering and grouping dimensions require Bot Management (Enterprise add-on). The standard Bot Detection Alert is available to all Bot Management customers. +::: + +## Related resources + +- [Bot Analytics](/bots/bot-analytics/) — Monitor bot traffic patterns across your domain +- [Bot Fight Mode](/bots/get-started/bot-fight-mode/) — Baseline bot protection available on all plans +- [Super Bot Fight Mode](/bots/get-started/super-bot-fight-mode/) — Granular bot controls for Pro, Business, and Enterprise plans +- [Turnstile](/turnstile/) — Free, privacy-preserving challenge for forms and user interactions +- [WAF custom rules](/waf/custom-rules/) — Write targeted rules using traffic signals and bot scores +- [Rate limiting rules](/waf/rate-limiting-rules/) — Control request volume to protect endpoints from abuse +- [Enterprise Bot Management](/bots/plans/bm-subscription/) — Machine learning-based bot scoring and behavioral analysis +- [Security Events](/waf/analytics/security-events/) — Review and investigate mitigated requests diff --git a/src/content/docs/waf/custom-rules/use-cases/challenge-bad-bots.mdx b/src/content/docs/waf/custom-rules/use-cases/challenge-bad-bots.mdx index 6d82bf1ff207195..1374f43ff99af6b 100644 --- a/src/content/docs/waf/custom-rules/use-cases/challenge-bad-bots.mdx +++ b/src/content/docs/waf/custom-rules/use-cases/challenge-bad-bots.mdx @@ -3,6 +3,8 @@ pcx_content_type: configuration title: Challenge bad bots --- +import { Render } from "~/components"; + Cloudflare's Bot Management feature scores the likelihood that a request originates from a bot. :::note @@ -13,14 +15,14 @@ Access to [Bot Management](/bots/plans/bm-subscription/) requires a Cloudflare E Before creating custom rules for bot protection, review the settings on your [Security Settings](/security/) page under **Bot traffic**. Built-in features auto-update with new bot signatures, do not count toward your custom rule limits, and are simpler to manage. -| Use case | Bot setting | -| --- | --- | -| Block AI crawlers (GPTBot, ClaudeBot, etc.) | **Block AI bots** | -| Block definitely automated traffic (bot score of 1) | **Definitely automated** | -| Challenge likely automated traffic (bot score 2-29) | **Likely automated** | -| Allow verified bots (Googlebot, Bingbot, etc.) | **Verified bots** | -| Extend bot protection to static resources | **Static resource protection** | **Security Settings** > **Bot traffic** | -| Allow WordPress loopback requests | **Optimize for WordPress** | **Security Settings** > **Bot traffic** | +| Use case | Bot setting | +| --------------------------------------------------- | ------------------------------ | --------------------------------------- | +| Block AI crawlers (GPTBot, ClaudeBot, etc.) | **Block AI bots** | +| Block definitely automated traffic (bot score of 1) | **Definitely automated** | +| Challenge likely automated traffic (bot score 2-29) | **Likely automated** | +| Allow verified bots (Googlebot, Bingbot, etc.) | **Verified bots** | +| Extend bot protection to static resources | **Static resource protection** | **Security Settings** > **Bot traffic** | +| Allow WordPress loopback requests | **Optimize for WordPress** | **Security Settings** > **Bot traffic** | Custom rules are still valuable when you need path-specific protection (different handling for `/api/` vs. `/login/`), custom score thresholds (for example, score below 20 instead of 30), conditional logic combining bot score with other fields, or custom actions not available in the built-in settings. @@ -49,21 +51,7 @@ Custom rules execute before [Super Bot Fight Mode](/bots/get-started/super-bot-f The following three custom rules provide baseline protection against malicious bots: -**Rule 1:** - -- **Expression**: `(cf.bot_management.verified_bot)` -- **Action**: _Skip:_ - - _All remaining custom rules_ - -**Rule 2:** - -- **Expression**: `(cf.bot_management.score eq 1)` -- **Action**: _Block_ - -**Rule 3:** - -- **Expression**: `(cf.bot_management.score gt 1 and cf.bot_management.score lt 30)` -- **Action**: _Managed Challenge_ + ### Specific protection for browser, API, and mobile traffic diff --git a/src/content/partials/bots/bot-score-baseline-rules.mdx b/src/content/partials/bots/bot-score-baseline-rules.mdx new file mode 100644 index 000000000000000..0bb40c6d69163aa --- /dev/null +++ b/src/content/partials/bots/bot-score-baseline-rules.mdx @@ -0,0 +1,27 @@ +--- +{} +--- + +{/* Consumed by: + - /waf/custom-rules/use-cases/challenge-bad-bots/ + - /use-cases/application-security/bots/stop-malicious-bots/ +*/} + +**Rule 1: Skip verified bots** + +- **Expression**: `(cf.bot_management.verified_bot)` +- **Action**: _Skip:_ + - _All remaining custom rules_ +- Known good bots (Googlebot, Bingbot, monitoring services) bypass all custom rules. + +**Rule 2: Block definitely automated** + +- **Expression**: `(cf.bot_management.score eq 1)` +- **Action**: _Block_ +- Score 1 traffic is definitively automated. Blocking it carries minimal false positive risk. + +**Rule 3: Challenge likely automated** + +- **Expression**: `(cf.bot_management.score gt 1 and cf.bot_management.score lt 30)` +- **Action**: _Managed Challenge_ +- Scores 2-29 indicate likely automated behavior. A challenge lets legitimate users through while stopping bots. diff --git a/src/content/partials/bots/enable-bfm.mdx b/src/content/partials/bots/enable-bfm.mdx new file mode 100644 index 000000000000000..5c7191bdd1e7a3a --- /dev/null +++ b/src/content/partials/bots/enable-bfm.mdx @@ -0,0 +1,34 @@ +--- +{} +--- + +{/* Consumed by: + - /bots/get-started/bot-fight-mode/ + - /use-cases/application-security/bots/stop-malicious-bots/ +*/} + +import { Tabs, TabItem, Steps, DashButton } from "~/components"; + +{/* prettier-ignore-start */} + + + + + 1. In the Cloudflare dashboard, go to the **Security Settings** page. + + + 2. Filter by **Bot traffic**. + 3. Go to **Bot Fight Mode**. + 4. Turn **Bot Fight Mode** on. + + + + + 1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com/login), and select your account and domain. + 2. Go to **Security** > **Bots**. + 3. For **Bot Fight Mode**, select **On**. + + + + +{/* prettier-ignore-end */} diff --git a/src/content/partials/turnstile/create-widget-dashboard.mdx b/src/content/partials/turnstile/create-widget-dashboard.mdx new file mode 100644 index 000000000000000..abd07446d8a412f --- /dev/null +++ b/src/content/partials/turnstile/create-widget-dashboard.mdx @@ -0,0 +1,24 @@ +--- +{} +--- + +{/* Consumed by: + - /turnstile/get-started/widget-management/dashboard/ + - /use-cases/application-security/bots/stop-malicious-bots/ +*/} + +import { Steps, DashButton } from "~/components"; + + + 1. In the Cloudflare dashboard, go to the **Turnstile** page. + + + 2. Select **Add widget**. + 3. Fill out the required information: + - **Widget name**: A descriptive name for your widget. + - **Hostname management**: Domains where the widget will be used. + - **Widget mode**: Choose from Managed, Non-Interactive, or Invisible. + 4. (Optional) Configure **Pre-clearance support** for single-page applications. + 5. Select **Create** to save your widget. + 6. Copy your sitekey and secret key, and store the secret key securely. +