# Bots

# Account Abuse Protection (Early Access)

import { Render, Description, DashButton, Steps } from "~/components";

<Description>
	Identify and mitigate attacks on your customer and user accounts.
</Description>

Account abuse — bulk account creation and account takeover attacks — can cause financial losses and erode user trust. Fraud detection allows you to detect and mitigate these attacks among your traffic. You can use fraud signals to [update or create new rules](/waf/custom-rules/) for suspicious account activity, or pass signals to your origin to integrate into authentication and authorization systems.

## Availability

Account Abuse Protection is available in Early Access for any [Bot Management Enterprise](/bots/get-started/bot-management) customer. You can use these features at no additional cost for a limited period until they are generally available.

Contact your Cloudflare account team to request access.

---

## Concepts

### User ID

User ID is a cryptographically hashed, per-zone identifier that customers can use in [Security Analytics](/waf/analytics/security-analytics/), [Security Rules](/waf/custom-rules/), and [Managed Transforms](/rules/transform/managed-transforms/reference/). Hashed User IDs are created by encrypting the primary credentials your users provide, converting them into opaque identifiers unique to your zone. This allows traffic analysis while protecting user privacy. With access to hashed User ID, website owners can:

- Review which users have the most activity on your website.
- Find the details on a specific user's characteristics and activity patterns.
- Mitigate traffic based on the user, such as blocking a user with historically suspicious activity.
- Combine fields to see when accounts are being targeted with leaked credentials.
- Manage network patterns or signals associated with specific users.

:::note[Data privacy]
User profiling was created with privacy in mind. Its design and engineering align with our privacy and compliance programs and contain technical controls that protect the privacy of users. Hashed User IDs are created by encrypting the primary credentials your users use to access your applications.

Other Cloudflare customers cannot access your user profiles. They are unique to your zone.
:::

User ID is an opt-in feature that can be enabled in Security Settings.

To enable, edit, or disable the setting:

<Steps>
1. In the Cloudflare dashboard, go to the **Security Settings** page.

    <DashButton url="/?to=/:account/:zone/security/settings" />

2. Filter by **Fraud**.
3. Go to **User ID**.
4. Turn **User ID** on or off.
</Steps>

### Ephemeral IDs

Customers using Cloudflare [Turnstile](/turnstile/) can utilize ephemeral IDs for Fraud detection.

Refer to [Fraud detection with ephemeral IDs](/turnstile/tutorials/fraud-detection-with-ephemeral-ids/) for more information.

### Account takeover detections

Cloudflare Bot Management includes dedicated detection IDs for account takeover attacks.

Refer to [Account takeover detections](/bots/additional-configurations/detection-ids/account-takeover-detections/) for more information.

:::note
Account takeover (ATO) detections are not available for accounts using the [Data Localization Suite](/data-localization/) with [Regional Services](/data-localization/regional-services/) in the EU region. ATO detections rely on zone logs to identify suspicious activity, and Cloudflare does not ingest logs for these accounts to comply with General Data Protection (GDPR).
:::

---

## Get started

### Prerequisites

Fraud detection requires the following configurations and settings to be enabled to properly identify suspicious behavior.

#### Security Settings

- User ID: Cloudflare encrypts or hashes your user IDs to better understand typical user traffic patterns across your applications. Enabling Cloudflare to create hashed user ID mappings to your users will allow you to receive account takeover and bulk account creation detections.

#### Eligible traffic

Cloudflare automatically identifies certain login and sign up traffic on your applications and runs these detections without any additional configurations.

- Sign-ups: Cloudflare automatically monitors traffic on endpoints that match common sign up endpoints.
- Login: Cloudflare automatically monitors traffic on endpoints that match common login endpoints.

Verify that your endpoints are properly labeled to ensure Cloudflare can detect and monitor them correctly.

:::caution[Login or sign up endpoints]
Not all login or signup endpoints are automatically detected.

Cloudflare evaluates and automatically detects your website or application's login or sign up endpoint, but non-traditional login or sign up endpoints may not be recognized.

For example, if you have a non-traditional login endpoint, you should label it with `cf-log-in` using the [endpoint labeling service](/api-shield/management-and-monitoring/endpoint-labels/). Once you have applied the `cf-log-in` label, Cloudflare will use the labeled endpoint for account takeover detection decisions.
:::

:::tip[Enhanced with leaked credential detections]
Cloudflare also recommends enabling [Leaked credentials detection](/waf/detections/leaked-credentials/) to help identify compromised credentials across your users.
:::

---

### Detections

Fraud detections focus on account abuse attacks such as account takeover, bulk account creation, and credential quality. These detections run on all eligible traffic and can be used across [Cloudflare Rules](/rules/) to log, challenge, and/or block requests to your sign up and login endpoints.

#### Account creation

Disposable Email Checks detect when users sign up with throwaway email addresses commonly used for promotion abuse and fake account creation. These disposable email services allow attackers to create thousands of unique accounts without maintaining real infrastructure.

You can use `cf.fraud_detection.disposable_email` to block disposable emails or issue a [challenge](/cloudflare-challenges/challenge-types/) to anyone attempting to create an account with a disposable email.

#### Suspicious emails

Cloudflare checks email domains used during sign up against lists of known temporary or disposable email services. Cloudflare runs the same check on login requests when the extracted username is an email address.

This check also determines the value of `cf.fraud.email_risk` in Security Rules and Security Analytics. Refer to [prerequisites](#prerequisites) to ensure your traffic is eligible for detections.

| Detection tag                         | Description                                                                                                         |
| ------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
| `cf.fraud_detection.disposable_email` | Identifies emails with domains that are commonly found in lists of temporary or disposable email services.          |
| `cf.fraud.email_risk`                 | Returns `high` when Cloudflare identifies the email domain as temporary or disposable. Returns `unknown` otherwise. |

---

### Mitigations

The following Fraud detection fields can be used in Security Rules to help identify and mitigate suspicious traffic.

#### Security Rules

The following fields can be used in new and existing Security Rules.

| Field                                 | Description                                                                                        | Values                                                                                             |
| ------------------------------------- | -------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
| `cf.fraud_detection.disposable_email` | Flags whether a domain for a given email is included in a known list of temporary email providers. | `True` or `False`                                                                                  |
| `cf.fraud.email_risk`                 | Indicates whether Cloudflare identifies an email domain as temporary or disposable.                | `high` when Cloudflare identifies the domain as temporary or disposable. <br/>`unknown` otherwise. |

#### Other rules

You can use Fraud detection data in Request Header [Transform Rules](/rules/transform/managed-transforms/) to pass information down to the origin.

#### LogPush

You can add Fraud detection fields to existing or new [LogPush](/logs/logpush/) jobs.

---

## Analytics

You can find Fraud data and detections in Security Analytics, where you can see top User IDs.

<DashButton url="/?to=/:account/:zone/security/analytics" />

Fraud fields can be used as filters to identify suspicious patterns in your traffic.

The hashed User ID field within Security Analytics also provides Fraud customers with data that can help review detections and patterns per individual users rather than requests. You can review user level aggregations for IPs and IP counts, event types (login or sign up), locations, devices, and browsers.

A user level profile also provides a quick way to review the latest events associated with a user so that you can identify any anomalies and create a custom rule to log, block, or challenge that user.

# Bot Analytics

import { GlossaryTooltip, Render } from "~/components";

## Business and Enterprise

Business and Enterprise customers without Bot Management can use **Bot Analytics** to dynamically examine bot traffic. These dashboards offer less functionality than Bot Management for Enterprise but still help you understand bot traffic on your domain.

### Access

You can access Bot Analytics by going to the [Cloudflare dashboard](https://dash.cloudflare.com/login), and selecting your account and domain.

Go to **Security** > **Analytics** > **Bot analysis**.

![View Bot Analytics in the Cloudflare dashboard. For more details, keep reading.](~/assets/images/bots/bot-analytics-dashboard-biz.png)

### Features

For a full tour of Bot Analytics, see [our blog post](https://blog.cloudflare.com/introducing-bot-analytics/). At a high level, the tool includes:

- **Requests by traffic type**: View your total domain traffic segmented vertically by traffic type. Keep an eye on _automated_ and _likely automated_ traffic.
- **Requests by detection source**: Identify the most common detection engines used to score your traffic. Hover over a tooltip to learn more about each engine.
- **Top requests by attribute**: View more detailed information on specific IP addresses and other characteristics.

Bot Analytics shows up to 72 hours of data at a time and can display data up to 30 days old. Bot Analytics displays data in real time in most cases.

<Render file="analytics-features" product="bots" />

### Common uses

Business and Enterprise customers without Bot Management can use Bot Analytics to:

- Understand <GlossaryTooltip term="bot">bot</GlossaryTooltip> traffic
- Study recent attacks to find trends and detailed information
- Learn more about Cloudflare’s detection engines with real data

For more details and granular control over bot traffic, consider upgrading to [Bot Management for Enterprise](/bots/bot-analytics/#enterprise-bot-management).

## Enterprise Bot Management

Enterprise customers with Bot Management can use **Bot Analytics** to dynamically examine bot traffic.

### Access

You can access Bot Analytics by going to the [Cloudflare dashboard](https://dash.cloudflare.com/login), and selecting your account and domain.

Go to **Security** > **Analytics** > **Bot analysis**.

![View Bot Analytics in the Cloudflare dashboard. For more details, keep reading.](~/assets/images/bots/bot-analytics-dashboard-ent.png)

### Features

<Render file="bm-analytics-features" product="bots" />

<Render file="analytics-features" product="bots" />

### Common uses

Bot Management customers can use Bot Analytics to:

- Understand traffic during [your onboarding phase](/bots/get-started/bot-management/).
- Tune WAF custom rules to be effective but not overly aggressive.
- Study recent attacks to find trends and detailed information.
- Learn more about Cloudflare’s detection engines with real data.

### API

Data from Bot Analytics is also available via the GraphQL API. You can access <GlossaryTooltip term="bot score">bot scores</GlossaryTooltip>, bot sources, <GlossaryTooltip term="bot tags" link="/bots/concepts/bot-tags/">bot tags</GlossaryTooltip>, and bot _decisions_ (_automated_, _likely automated_, etc.), and more.

Read the [GraphQL Analytics API documentation](/analytics/graphql-api/) for more information about GraphQL and basic querying.

# BotBase

BotBase is Cloudflare's directory of all known bots, including [verified bots and agents](/bots/concepts/bot/verified-bots/). It provides a comprehensive, searchable view of the entire bot directory directly in the Cloudflare dashboard, where you can see how Cloudflare classifies each bot and target individual bots in your security configuration.

BotBase currently serves as a visibility plane for tracked bots. To mitigate these bots, you can use [Security rules](/security/rules/) or the [AI traffic options](/bots/concepts/bot/#ai-bots).

## Availability

BotBase is available to [Enterprise Bot Management](/bots/get-started/bot-management/) customers.

## Access

To view BotBase, go to **Security Analytics** > **Bot analysis** > **BotBase**. You can also access BotBase from **Security Settings** > **Bot Management** > **BotBase**.

## What you can do

- Browse the full catalogue of all verified bots and agents, and see the behavior or behaviors each one is classified under.
- Search and filter the directory to find a specific bot or group of bots.
- Filter your own traffic to a specific bot to investigate its activity on your zone.
- Copy a bot's detection ID to target it in [Security rules](/security/rules/).
- If you operate a bot, submit it for verification from the **Submission form** tab and track its review status from the **Submission history** tab. For more information, refer to [Becoming a Verified bot](/bots/concepts/bot/verified-bots/#becoming-a-verified-bot).

## Requests

The **Requests** column summarizes requests associated with each bot over the previous 24 hours and shows an hourly sparkline.

| Metric           | Definition                                                              |
| ---------------- | ----------------------------------------------------------------------- |
| **Successful**   | Requests with an edge HTTP response status in the `2xx` or `3xx` range. |
| **Unsuccessful** | Requests with any other edge HTTP response status.                      |

These metrics describe HTTP response outcomes, not the mitigation that a website owner configured for a request. Unsuccessful requests can include errors returned by the origin, such as `404` and `5xx` responses.

To investigate a bot's traffic, select its row to open Security Analytics in a new tab filtered to that bot's detection ID. Expand a request in the request log to review the **Mitigation**, **Edge status code**, and **Origin status code** fields.

## Classification

BotBase classifies each tracked bot by its behavior — what the bot may do on your site. A single bot can have one or more behaviors. To read more, see [Verified bot classifications](/bots/concepts/bot/verified-bots/).

## Radar's public-facing BotBase

Every bot tracked in BotBase, along with select metadata, is available publicly in [Cloudflare Radar's bots and agents directory](https://radar.cloudflare.com/bots/directory).

# Business Insights

import { DashButton } from "~/components";

**Business Insights** helps business decision-makers and content owners analyze bot traffic to their website over the last 24 hours, 7 days, or 30 days.

## Availability

Business Insights is available to all [Enterprise Bot Management](/bots/get-started/bot-management/) customers.

Business Insights is an observability surface and does not provide controls. To mitigate bots, use [Security rules](/security/rules/) or the [AI bot management options](/bots/additional-configurations/block-ai-bots/).

## Access

<DashButton url="/?to=/:account/:zone/analytics/business-insights" />

You can also reach the dashboard from your zone-level **Analytics** > **Business Insights** in the Cloudflare dashboard.

## Definitions

The dashboard uses the following definitions:

- **Content pages**: Content is initially defined as HTML pages on your website.
- **Crawl-to-referral ratio, per bot operator**: The average crawl-to-referral ratio (number of crawls sent by this company, vs. the number of visitors who visit you through a referral link from that company, tracked through UTM parameters) for a given company, in the selected time period.
- **Crawl-to-referral ratio, site-wide**: The average crawl-to-referral ratio (number of crawls sent by this company, vs. the number of visitors who visit you through a referral link from that company, tracked through UTM parameters) across all activity on your zone, in the selected time period.
- **Classification**: Each crawler is classified with Cloudflare's updated taxonomy. See [Verified bot classifications](/bots/concepts/bot/verified-bots/) for more information. If the company has at least 1 bot with an AI use case, we label the operator with the "AI" label, plus provide this as a filter.
- **Operator**: An operator row aggregates requests from all bots associated with that operator.

### Outcome

**Outcome** summarizes the HTTP responses for requests attributed to an operator.

| Outcome               | Definition                                                                                  |
| --------------------- | ------------------------------------------------------------------------------------------- |
| **Allowed**           | All requests received successful HTTP responses (`2xx` or `3xx`).                           |
| **Blocked**           | All requests received unsuccessful HTTP responses (status codes other than `2xx` or `3xx`). |
| **Partially blocked** | The requests include both successful and unsuccessful HTTP responses.                       |

For a **Partially blocked** row, the Outcome cell shows the successful and unsuccessful request counts.

Outcome is based on HTTP response status and does not identify the mitigation that a website owner configured for a request. Unsuccessful responses can include errors returned by the origin, such as `404` and `5xx` responses. To investigate a request, review its mitigation, edge status code, and origin status code in [Security Analytics](/waf/analytics/security-analytics/).

# Changelog

import { ProductReleaseNotes } from "~/components";

{/* <!-- Actual content lives in /src/content/release-notes/bots.yaml. Update the file there for new entries to appear here. For more details, refer to https://developers.cloudflare.com/style-guide/documentation-content-strategy/content-types/changelog/#yaml-file --> */}

<ProductReleaseNotes />

# Glossary

import { Glossary } from "~/components"

Review the definitions for terms used across Cloudflare's Bots documentation.

<Glossary product="bots" />

# Cloudflare bot solutions

import { CardGrid, Description, Feature, LinkTitleCard, Plan, RelatedProduct, Render } from "~/components"

<Description>

Identify and mitigate automated traffic to protect your domain from bad bots. 
</Description>

<Plan type="all" />

Bots — automated software that sends requests to your site — can scrape content, stuff stolen credentials into login forms, hoard inventory, and inflate server costs. Cloudflare's bot solutions detect this automated traffic and let you decide how to respond.

Cloudflare offers three bot-specific products: Bot Fight Mode, Super Bot Fight Mode, and Bot Management for Enterprise.

<Render file="non-contract-enablement" product="fundamentals" />

## Which bot solution do I need?

If you need a simple toggle that challenges detected bots across your entire domain, use Bot Fight Mode (Free) or Super Bot Fight Mode (Pro, Business, Enterprise without Bot Management add-on). These products are included with your plan but do not allow you to write rules based on bot score or target specific endpoints. Super Bot Fight Mode adds configurable actions per bot category and supports WAF custom rule exceptions, but does not offer the granular per-request scoring of Bot Management.

If you need granular control — per-request bot scores, custom rules, per-endpoint handling, and detailed analytics — use Bot Management for Enterprise. This is recommended for ecommerce, banking, and security use cases. To enable Bot Management for Enterprise, contact your account team.

To see the differences in features and functionality, visit [Plans](/bots/plans/).

## Features

<Feature header="Bot Fight Mode" href="/bots/get-started/bot-fight-mode/">
Challenge detected bot traffic across your entire domain with a single toggle. 
</Feature>

<Feature header="Super Bot Fight Mode" href="/bots/get-started/super-bot-fight-mode/">
Identify traffic matching patterns of known bots, challenge or block bots, protect static resources, and view analytics to help you understand bot traffic using Super Bot Fight Mode. 
</Feature>

<Feature header="Bot Analytics" href="/bots/bot-analytics/">
Use Bot Analytics to dynamically examine bot traffic. 
</Feature>

<Feature header="Firewall variables" href="/bots/reference/bot-management-variables/">
Access several new variables within the Firewall expression builder. 
</Feature>

## Related products

<RelatedProduct header="API Shield" href="/api-shield/" product="api-shield">
Identify and address API vulnerabilities using API Shield. 
</RelatedProduct>

<RelatedProduct header="DDoS Protection" href="/ddos-protection/" product="ddos-protection">
Detect and mitigate Distributed Denial of Service (DDoS) attacks using Cloudflare's Autonomous Edge. 
</RelatedProduct>

<RelatedProduct header="Turnstile" href="/turnstile/" product="turnstile">
Use Cloudflare's smart CAPTCHA alternative to run less intrusive challenges. 
</RelatedProduct>

<RelatedProduct header="WAF" href="/waf/" product="waf">
Get automatic protection from vulnerabilities and the flexibility to create custom rules. 
</RelatedProduct>

## More resources

<CardGrid>

<LinkTitleCard title="Plans" href="https://www.cloudflare.com/plans/#overview" icon="document">
Compare available Cloudflare plans
</LinkTitleCard>

</CardGrid>

# AI Labyrinth

import { Steps, DashButton } from "~/components";

The AI Labyrinth adds invisible links on your webpage with specific `Nofollow` tags to block AI crawlers that do not adhere to the recommended guidelines and crawl without permission. AI crawlers that scrape your website content without permission will be stuck in a maze of never-ending links, and their details are recorded and used by all Cloudflare customers who choose to block [AI bots](/bots/concepts/bot/#ai-bots).

These links do not impact your search engine optimization (SEO) or your website's appearance, and are only seen by bots. AI bots that respect no-crawl instructions will safely ignore this honeypot.

## AI Labyrinth in Security Analytics

When AI Labyrinth is enabled, Cloudflare logs security events for AI Labyrinth under the **AI Labyrinth** service. The following actions describe what happened to the request:

| Action | Description |
| --- | --- |
| **AI Labyrinth Served** | Cloudflare injected AI Labyrinth honeypot links into the HTML response. |
| **AI Labyrinth Crawls** | A crawler followed one of the injected honeypot links and entered the maze. |

AI Labyrinth actions are not mitigations. Cloudflare does not block or challenge the request.

A high volume of **AI Labyrinth Crawls** relative to **AI Labyrinth Served** indicates that non-compliant AI crawlers are actively following the injected links.

You can view these events in [Security Analytics](/waf/analytics/security-analytics/) and [Security Events](/waf/analytics/security-events/).

### After you turn off AI Labyrinth

When you turn off AI Labyrinth, Cloudflare immediately stops injecting new honeypot links into your pages. However, links generated while the feature was on remain valid for a limited time. Cloudflare still serves labyrinth content for these links, so you may continue to see AI Labyrinth actions in Security Analytics and Security Events until the links expire. This is expected behavior and does not mean the feature is still on.

## Enable AI Labyrinth

<Steps>
  1. In the Cloudflare dashboard, go to the **Security Settings** page.

      <DashButton url="/?to=/:account/:zone/security/settings" />
  2. Filter by **Bot traffic**.
  3. Go to **AI Labyrinth**.
  4. Turn **AI Labyrinth** on.
</Steps>

# Block AI Bots

### New defaults on September 15, 2026

On September 15, 2026, Cloudflare will set updated defaults for new domains: bots classified as Training or as Agent will be blocked on pages that display ads, and Search will remain allowed. Mixed-purpose crawlers that combine Search and Training will also be blocked by all configurations to block AI training, including the legacy "Block AI bots" option. Before September 15, all customers can [opt out of these new defaults](https://dash.cloudflare.com/?to=/:account/:zone/security/settings).

All Cloudflare customers can choose to block AI bots and agents based on their behavior. Cloudflare offers presets for the most common AI behaviors to give customers the option to treat different AI use cases distinctly:

- **Search**: crawlers that collect or index your content to answer questions about it later.
- **Agent**: automated activity acting in real time on a person's behalf, such as chat fetch bots and browser-use agents.
- **Training**: crawlers taking your content to train or fine-tune a model, including mixed-purpose crawlers that are used both for Training and for Search.

Each blocking option will block Verified bots classified with that behavior, plus additional unverified bots that fall under these classifications.

Each setting includes three mitigation options:

- **Block (on all pages)** - Issues the block across the entire zone.
- **Block on pages with ads** - Uses Cloudflare automated detection for pages that display ads on your zone to block only on those pages.
- **Allow (do not block)** - Does not add any blocking.

To configure these policies, customers can go to **Security Settings** > **Configure AI bot policies**.

## Block AI bots [Deprecating on September 15, 2026]

This setting blocks verified bots that are classified as crawling for the purpose of AI training, as well as a number of unverified bots that behave similarly.

:::note
This option excludes mixed-purpose bots that are used both for Training and for Search.
:::

To configure this setting and set their preference for blocking mixed-purpose bots, customers can go to **Security Settings** > **Block AI bots**.

# Custom rules

import { GlossaryTooltip, Render } from "~/components";

Bot protection on Cloudflare works through two complementary mechanisms: built-in settings configured through toggles in **Security Settings**, and [WAF custom rules](/waf/custom-rules/) that you write using [bot management fields](/bots/reference/bot-management-variables/). Understanding when to use each approach helps you avoid creating duplicate rules and simplifies your security configuration.

The following features are configured through toggles and dropdowns in [Security Settings](/security/settings/). They do not require you to write any rule expressions.

| Feature | What it does | Availability |
| --- | --- | --- |
| [Block AI bots](/bots/additional-configurations/block-ai-bots/) | Blocks AI crawlers (GPTBot, ClaudeBot, Bytespider, and others) using an auto-updating managed rule | All plans |
| [AI Labyrinth](/bots/additional-configurations/ai-labyrinth/) | Feeds non-compliant AI crawlers into a maze of generated content | All plans |
| [Managed robots.txt](/bots/additional-configurations/managed-robots-txt/) | Prepends AI crawler disallow directives to your `robots.txt` | All plans |
| Super Bot Fight Mode > **Definitely automated** | Blocks or challenges traffic with a [bot score](/bots/concepts/bot-score/) of 1 | Pro, Business, Enterprise |
| Super Bot Fight Mode > **Likely automated** | Blocks or challenges traffic with a bot score of 2-29 | Business, Enterprise |
| [Verified bots](/bots/concepts/bot/verified-bots/) | Managed category of high-trust bots (Googlebot, Bingbot, and others) | Pro, Business, Enterprise |
| [Static resource protection](/bots/additional-configurations/static-resources/) | Extends bot actions to cover static file types | Pro, Business, Enterprise |
| [Optimize for WordPress](/bots/troubleshooting/wordpress-loopback-issue/) | Allows WordPress loopback requests through bot protection | Pro, Business, Enterprise |
| [JavaScript detections](/cloudflare-challenges/challenge-types/javascript-detections/) | Injects a lightweight script to identify clients that cannot execute JavaScript | All plans (automatic on Free) |

Bot settings update automatically as Cloudflare identifies new bot signatures and AI crawlers, while custom rules require manual updates. They do not count toward your [custom rule limits](/waf/custom-rules/#availability), and apply uniformly across your domain without the risk of expression errors.

## Custom rules use cases

Custom rules are valuable when you need capabilities that built-in settings do not offer. The following scenarios require [WAF custom rules](/waf/custom-rules/) with [bot management fields](/bots/reference/bot-management-variables/). Bot management fields are available to customers with a [Bot Management](/bots/get-started/bot-management/) subscription.

### Path-specific protection

Since Bot settings apply to all traffic across your domain, you may need an alternative approach to bot handling for different paths using custom rules — for example, stricter protection on `/login/` than on `/public/`.

#### Example

Block likely automated traffic only on your login endpoint:

```txt
(cf.bot_management.score lt 30 and not cf.bot_management.verified_bot and http.request.uri.path eq "/login")
```

### Custom score thresholds

The **Definitely automated** and **Likely automated** settings in Super Bot Fight Mode use fixed bot score groupings (1 and 2-29). If you need a different threshold, for example, challenging all traffic with a score below 20, you need a custom rule.

### Conditional logic

If you need to combine bot score with other request fields, such as country, ASN, URI path, JA3/JA4 fingerprint, or user agent, you need custom rules. Bot settings do not support compound conditions.

#### Example

Challenge likely automated traffic only from specific ASNs:

```txt
(cf.bot_management.score lt 30 and not cf.bot_management.verified_bot and ip.src.asnum in {64496 65536})
```

### Custom actions

Bot settings offer **Block**, **Managed Challenge**, and **Allow** as actions.

If you need other actions, such as **Log** (for testing rules before enforcement), **Interactive Challenge**, or **Skip** (to bypass other rules), you need custom rules.

### Detection ID targeting

To act on specific bot heuristic detections, such as [account takeover](/bots/additional-configurations/detection-ids/account-takeover-detections/) or [scraping](/bots/additional-configurations/detection-ids/scraping-detections/) patterns, you need custom rules using the `cf.bot_management.detection_ids` field. Bot settings do not expose individual detection IDs.

### Forwarding bot data to origin

To send bot scores, verified bot status, or JA3/JA4 fingerprints to your origin server, use [Transform Rules](/rules/transform/) (including [Managed Transforms](/rules/transform/managed-transforms/)) or [Snippets](/rules/snippets/). These are not part of the built-in bot settings.

## Execution order

Custom rules execute before Super Bot Fight Mode managed rules. If a custom rule takes a <GlossaryTooltip term="terminating action">terminating action</GlossaryTooltip> (such as _Block_ or _Managed Challenge_), the request does not reach bot settings.

Refer to [Security features interoperability](/waf/feature-interoperability/) for more information.

# Additional configurations

import { DirectoryListing } from "~/components"

Refer to the following pages for more information on additional bot management configurations:

<DirectoryListing />

# robots.txt setting

import { Steps, DashButton } from "~/components";

AI companies use crawlers to collect website content for training language models, generating search answers, and other purposes. A `robots.txt` file at the root of your domain tells these crawlers which content they should or should not access. Bot Preference Sync generates managed `robots.txt` directives from your Search, Agent, and Training policies when at least one policy is set to **Block**, **Block on pages with ads**, or, for Training, **Disallow**.

`robots.txt` compliance is voluntary. The file expresses your preferences, but it does not prevent crawlers from accessing your content at a technical level. Some crawler operators may disregard your `robots.txt` directives (instructions like `Disallow: /`) and crawl your content regardless.

:::caution[When does the managed content appear?]
Cloudflare prepends managed directives and the Content Signals Policy to your `robots.txt` only when **Enable Bot Preference Sync** is turned on and at least one of your Search, Agent, or Training policies is set to **Block**, **Block on pages with ads**, or, for Training, **Disallow**. With every policy set to allow, there is nothing to prepend and your `robots.txt` is served unchanged.

After you save your AI bot policies, the managed content appears within a few seconds. Reload your `robots.txt` to verify — no cache purge is required.
:::

:::note
To enforce access restrictions, use [AI Crawl Control](/ai-crawl-control/features/manage-ai-crawlers/) to block selected AI crawlers. You can use `robots.txt` to express your preferences and AI Crawl Control to enforce crawler-specific blocks.
:::

## Compatibility with existing `robots.txt` files

Cloudflare detects whether your origin server already has a `robots.txt` file and adjusts accordingly — either merging with your existing file or creating one from scratch.

### Existing robots.txt file

If your website already has a `robots.txt` file — verified by an HTTP `200` response — Cloudflare will prepend our managed `robots.txt` before your existing `robots.txt`, combining both into a single response.

For example, without this feature enabled, the `robots.txt` content of `crawlstop.com` would be:

```txt title="Feature not enabled"
User-agent: *
Disallow: /lp
Disallow: /feedback
Disallow: /langtest

Sitemap: https://www.crawlstop.com/sitemap.xml
```

With the managed `robots.txt` enabled, Cloudflare will prepend our managed content before your original content, resulting in what you can view at https://www.crawlstop.com/robots.txt.

```txt title="Feature enabled"
# As a condition of accessing this website, you agree to abide by the
# following content signals:

# (a)  If a content-signal = yes, you may collect content for the
#      corresponding use.
# (b)  If a content-signal = no, you may not collect content for the
#      corresponding use.
# (c)  If the website operator does not include a content signal for a
#      corresponding use, the website operator neither grants nor restricts
#      permission via content signal with respect to the corresponding use.

# The content signals and their meanings are:

# search: building a search index and providing search results (e.g., returning
#         hyperlinks and short excerpts from your website's contents). Search
#         does not include providing AI-generated search summaries.
# ai-input: inputting content into one or more AI models (e.g., retrieval
#           augmented generation, grounding, or other real-time taking of
#           content for generative AI search answers).
# ai-train: training or fine-tuning AI models.

# ANY RESTRICTIONS EXPRESSED VIA CONTENT SIGNALS ARE EXPRESS RESERVATIONS OF
# RIGHTS UNDER ARTICLE 4 OF THE EUROPEAN UNION DIRECTIVE 2019/790 ON COPYRIGHT
# AND RELATED RIGHTS IN THE DIGITAL SINGLE MARKET.

# BEGIN Cloudflare Managed content

User-Agent: *
Content-signal: search=yes, ai-train=no, use=reference
Allow: /

User-agent: Amazonbot
Disallow: /

User-agent: Applebot-Extended
Disallow: /

User-agent: Bytespider
Disallow: /

User-agent: CCBot
Disallow: /

User-agent: ClaudeBot
Disallow: /

User-agent: Google-Extended
Disallow: /

User-agent: GPTBot
Disallow: /

User-agent: meta-externalagent
Disallow: /

# END Cloudflare Managed Content
User-agent: *
Disallow: /lp
Disallow: /feedback
Disallow: /langtest

Sitemap: https://www.crawlstop.com/sitemap.xml
```

### No robots.txt file

If your website does not have a `robots.txt` file, Cloudflare creates a new file with managed `Disallow` rules for known AI crawlers and serves it for you.

## Implementation

To add managed directives for AI training crawlers:

<Steps>
  1. In the Cloudflare dashboard, go to the **Security Settings** page.

     <DashButton url="/?to=/:account/:zone/security/settings" />
  2. Filter by **Bot traffic**.
  3. Select **Configure AI bot policies**.
  4. For **Training**, select *Disallow*.
  5. Turn on **Enable Bot Preference Sync**.
  6. Select **Save**.
</Steps>

With Bot Preference Sync enabled, setting **Training** to _Disallow_ adds managed directives and enables edge blocking for AI training crawlers. Mixed-use crawlers are excluded from this edge block.

The **Search** and **Agent** policies also add their respective managed directives when set to _Block_ or _Block on pages with ads_.

## Content Signals Policy

Content Signals are a set of machine-readable directives in a `robots.txt` file that categorize how crawlers may use your content. The three categories are `search` (building a search index), `ai-input` (feeding content into AI models for real-time answers), and `ai-train` (training or fine-tuning AI models).

Domains on the Free plan that do not have their own `robots.txt` file and do not use the managed `robots.txt` feature will display the Content Signals Policy when a crawler requests the `robots.txt` file for your domain.

The Content Signals Policy defines these categories but does not express any specific preferences about your content. To set preferences (for example, `ai-train=no`), configure your AI bot policies and enable Bot Preference Sync.

```txt title="Content Signals Policy"
# As a condition of accessing this website, you agree to abide by the
# following content signals:

# (a)  If a content-signal = yes, you may collect content for the
#      corresponding use.
# (b)  If a content-signal = no, you may not collect content for the
#      corresponding use.
# (c)  If the website operator does not include a content signal for a
#      corresponding use, the website operator neither grants nor restricts
#      permission via content signal with respect to the corresponding use.

# The content signals and their meanings are:

# search: building a search index and providing search results (e.g., returning
#         hyperlinks and short excerpts from your website's contents). Search
#         does not include providing AI-generated search summaries.
# ai-input: inputting content into one or more AI models (e.g., retrieval
#           augmented generation, grounding, or other real-time taking of
#           content for generative AI search answers).
# ai-train: training or fine-tuning AI models.

# ANY RESTRICTIONS EXPRESSED VIA CONTENT SIGNALS ARE EXPRESS RESERVATIONS OF
# RIGHTS UNDER ARTICLE 4 OF THE EUROPEAN UNION DIRECTIVE 2019/790 ON COPYRIGHT
# AND RELATED RIGHTS IN THE DIGITAL SINGLE MARKET.
```

Cloudflare includes the Content Signals Policy whenever Bot Preference Sync adds managed directives to your `robots.txt` file.

:::caution
Google Search Console may occasionally report `Syntax not understood` for Content Signals and newer directives in the `robots.txt` standard. However, we have observed no impact on crawling rates or SEO as a result of these reports.
:::

## Content use signal

Cloudflare is testing `content-use`, an optional extension to [Content Signals](https://contentsignals.org/) that lives in your `robots.txt`. It adds a fourth field alongside the existing `search`, `ai-input`, and `ai-train` signals to describe what a crawler may keep and reuse after accessing your content. The field takes one of three values, from least to most permissive:

| Value           | Meaning                                |
| --------------- | -------------------------------------- |
| `use=immediate` | Interact, but store and reuse nothing. |
| `use=reference` | Index, excerpt, and link back.         |
| `use=full`      | Summarize and reproduce.               |

For customers who have turned on the managed `robots.txt` setting, Cloudflare adds `use=reference` to the managed content, in line with the existing default of `search=yes,ai-train=no`:

```txt title="Managed robots.txt with the content-use signal"
User-Agent: *
Content-signal: search=yes, ai-train=no, use=reference
Allow: /
```

## Availability

Managed `robots.txt` for AI crawlers is available on all plans.

# Sequence rules

import { Render, Steps } from "~/components";

<Render
	file="sequence-rules"
	product="bots"
	params={{
		one: "Sequence rules",
		two: "/bots/additional-configurations/sequence-rules/",
	}}
/>

:::caution[`431` error]
Too many concurrent requests to your zone may add cookies that create a header that is too large, causing a `431` error.
:::

## Prerequisites

- Your account must have the Fraud Detection subscription.
- Each zone must configure the endpoints to track via Endpoint Management.

You can [build a sequence custom rule via the Cloudflare dashboard](#build-a-sequence-custom-rule-via-the-cloudflare-dashboard) or [using the API](#manage-sequence-rules-via-the-api).

---

## Availability

<Render file="sequence-rules-availability" product="bots" />

---

## Build a sequence custom rule via the Cloudflare dashboard

<Render file="sequence-custom-rules" product="api-shield" />

---

## Manage sequence rules via the API

### Enable sequence rules

<Steps>
	1. [Create an API token](/fundamentals/api/get-started/create-token/) if you
	do not already have one. The API token must include the _Zone_ > _Fraud
	Detection_ > _Edit_ permission. 2. [Get the zone
	ID](/fundamentals/account/find-account-and-zone-ids/) for the zone(s) where
	you want to enable sequence rules. 3. [Add the
	endpoints](/api-shield/management-and-monitoring/) that you want to track in
	your sequence rules using API Shield's Endpoint Management and make note of
	the short ID. 4. Enable the sequence cookie by adding your API token and zone
	ID to the following API call.
</Steps>

:::note

The short ID will not be visible until your account team has enabled this feature for you.
:::

```bash title="API call"
curl --request PUT \
https://api.cloudflare.com/client/v4/zones/{zone_id}/fraud_detection/sequence_cookies \
--header "Authorization: Bearer <API_TOKEN>" \
--header "Content-Type: application/json" \
--data '{"enabled": true}'
```

5. Use the expression editor to write sequence or timing based rules via [custom rules](/waf/custom-rules/), [rate limiting rules](/waf/rate-limiting-rules/), or [transform rules](/rules/transform/). You can put these rules in log only mode to monitor.

:::note
When you enable sequence rules, Cloudflare will start setting cookies for all requests that match your endpoints.
:::

Once you have enabled sequence rules, the rules fields will be populated and you can now use the new fields in your rules.

### Disable sequence rules

Disabling sequence rules will stop the rules fields from being populated. If you still have rules deployed which depend on these fields, those rules may not behave as intended. Remove or disable any rules that rely on sequence fields before disabling sequence rules.

To disable sequence rules:

<Steps>
	1. [Create an API token](/fundamentals/api/get-started/create-token/) if you
	do not already have one. The API token must include the _Zone_ > _Fraud
	Detection_ > _Edit_ permission. 2. [Get the zone
	ID](/fundamentals/account/find-account-and-zone-ids/) for the zone(s) where
	you want to enable sequence rules. 3. [Add the
	endpoints](/api-shield/management-and-monitoring/) that you want to track in
	your sequence rules using API Shield's Endpoint Management and make note of
	the short ID. 4. Disable the sequence cookie using your API token, zone ID,
	and by setting `enabled` to `false` on the following API call.
</Steps>

:::note
The short ID will not be visible until your account team has enabled this feature for you.
:::

```bash title="API call"
curl --request PUT https://api.cloudflare.com/client/v4/zones/{zone_id}/fraud_detection/sequence_cookies \
--header "Authorization: Bearer <API_TOKEN>" \
--data '{"enabled": false}'
```

---

## Rules fields

Sequence rules introduces three new fields to Cloudflare Rules. All of these fields reference operations by their short ID. Accounts that have the Fraud Detection subscription can refer to the short ID by viewing the endpoint details via **API Shield** > **Endpoint Management** in the Cloudflare dashboard. Accounts without Fraud Detection do not have access to this field.

Cloudflare only stores up to the 10 most recent operations in a sequence for up to one hour. If there are more than 10 operations in the sequence, older operations will be dropped and will not be included in the following fields. Similarly, if an operation happened more than one hour ago, it will also not be included in the following fields.

### Example rules

The customer must request endpoint A before endpoint B.

```txt title="Valid sequence"
cf.sequence.current_op eq "bbbbbbbb" and
any(cf.sequence.previous_ops[*] == "aaaaaaaa")
```

```txt title="Invalid sequence"
cf.sequence.current_op eq "bbbbbbbb" and
not any(cf.sequence.previous_ops[*] == "aaaaaaaa")
```

Customer must request endpoint A at least one second before endpoint B.

```txt title="Valid sequence"
cf.sequence.current_op eq "bbbbbbbb" and
cf.sequence.msec_since_op["aaaaaaaa"] ge 1000
```

```txt title="Invalid sequence"
cf.sequence.current_op eq "bbbbbbbb" and
not cf.sequence.msec_since_op["aaaaaaaa"] ge 1000
```

---

## Limitations

Cloudflare only supports HTTPS requests since our cookies set the `Secure` attribute.

---

## Availability

Sequence rules is currently in private beta. If you would like to be included in the beta, contact your account team.

# Static resource protection

import { Render, Steps, GlossaryTooltip, DashButton } from "~/components";

Pro, Business, and Enterprise customers can use Cloudflare's bot solutions to protect their <GlossaryTooltip term="static content">static resources</GlossaryTooltip> from bots.

:::caution[Warning]

If you enable static resource protection, you may block good bots — like mail clients — that routinely fetch static resources. Make sure you understand your existing infrastructure before enabling this feature.
:::

## Super Bot Fight Mode

To enable this feature as a Pro or Business customer or an Enterprise customer without Bot Management:

<Steps>
  1. In the Cloudflare dashboard, go to the **Security Settings** page.

     <DashButton url="/?to=/:account/:zone/security/settings" />
  2. Filter by **Bot traffic**.
  3. Go to **Super Bot Fight Mode**.
  4. Under **Configurations**, select the edit icon for **Static resource protection** and turn it on.
</Steps>

:::caution

The **Static Resource Protection** setting will only activate if at least one of the bot categories (definite, likely, or verified) is _not_ set to `Allow`. If all categories are set to `Allow`, this setting will not have any impact since it works alongside these bot settings as part of the managed rules.
:::

## Bot Management for Enterprise

Static resources are protected by default when you create [custom rules](/waf/custom-rules/) using `cf.bot_management.score`.

To exclude static resources, you would need to include `not (cf.bot_management.static_resource)` as part of your custom rule.

## Which files are protected?

Static resources are files with the following extensions:

`ico|jpg|png|jpeg|gif|css|js|tif|tiff|bmp|pict|webp|svg|svgz|class|jar|txt|csv|doc|docx|xls|xlsx|pdf|ps|pls|ppt|pptx|ttf|otf|woff|woff2|eot|eps|ejs|swf|torrent|midi|mid|m3u8|m4a|mp3|ogg|ts`

Additionally, the `/.well-known/` URL path and all elements in it are considered a static resource, regardless of the file extension.

# Account takeover detections

import { Render, Steps, DashButton } from "~/components";

Using the detection IDs below, you can detect and mitigate account takeover attacks. You can monitor the number of login requests for a given software and network combination, as well as the percentage of login errors. When it reaches a suspicious level, you can prevent these attacks by using [custom rules](/waf/custom-rules/), [rate limiting rules](/waf/rate-limiting-rules/), and [Workers](/workers/).

| <div style="width:100px">Detection ID</div> | Description                                                                                                                                                                                                                                                                                                                  |
| ------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `201326592`                                 | Matches traffic that is making a suspicious amount of login failures to the zone.                                                                                                                                                                                                                                            |
| `201326593`                                 | Matches traffic that is making a suspicious amount of login attempts to the zone.                                                                                                                                                                                                                                            |
| `201326598`                                 | Sets a dynamic threshold based on the normal traffic that is unique to the zone.<br /><br /> When the ID matches a login failure, Bot Management sets the [bot score](/bots/concepts/bot-score/) to 29 and uses [anomaly detection](/bots/concepts/bot-detection-engines/#anomaly-detection-enterprise) as its score source. |

:::caution[Login endpoints]
Not all login endpoints are automatically detected.

Cloudflare evaluates and automatically detects your website or application's login endpoint, but non-traditional login endpoints may not be recognized.

For example, if you have a non-traditional login endpoint, you should label it with `cf-log-in` using the [endpoint labeling service](/api-shield/management-and-monitoring/endpoint-labels/). Once you have applied the `cf-log-in` label, Cloudflare will use the labeled endpoint for account takeover detection decisions.
:::

## Challenges for account takeover detections

Cloudflare's [Managed Challenge](/cloudflare-challenges/challenge-types/challenge-pages/#managed-challenge) can limit brute-force attacks on your login endpoints.

To access account takeover detections:

<Steps>
  1. In the Cloudflare dashboard, go to the **Security rules** page.

      <DashButton url="/?to=/:account/:zone/security/security-rules" />
  2. Select **Create rule** and choose **Custom rule**.
  3. Fill out the form using **Bot Detection IDs** along with other necessary information.
  4. Select **Save as draft** to return to the rule later, or **Deploy** to deploy the rule.
</Steps>

```js title="Rule example"

(any(cf.bot_management.detection_ids[*] eq 201326593))
```

## Limit logins with account takeover detections

Rate limiting rules can limit the number of logins from a particular IP, JA4 fingerprint, or country.

To use rate limiting rules with account takeover detections:

<Steps>
  1. In the Cloudflare dashboard, go to the **Security rules** page.

      <DashButton url="/?to=/:account/:zone/security/security-rules" />
  2. Select **Create rule** and choose **Rate limiting rule**.
  3. Fill out the form using the **Custom expression builder** and `cf.bot_management_detection_ids` along with other necessary information.
  4. Select **Save as draft** to return to the rule later, or **Deploy** to deploy the rule.
</Steps>

:::tip[Enhanced with leaked credential detections]
The rule can be enhanced with Leaked Credential Checks. Refer to the [WAF documentation](/waf/detections/leaked-credentials/) for more information on how to include leaked credentials and account takeover detections in a rate limiting rule.

:::

# Additional detections

Cloudflare bot detection includes additional signals to catch different kinds of automated traffic.

Bot management customers automatically benefit from the residential proxy detection improvement below, which lowers the [bot score](/bots/concepts/bot-score/) for matched requests. Using the detection ID in [custom rules](/waf/custom-rules/) provides even more visibility and control over mitigating residential proxy traffic.


| <div style="width:100px">Detection ID</div> | Description                              |
| ------------------------------------------ | ---------------------------------------- |
| `50331651`                                 | Observes traffic from residential proxy networks and similar commercial proxies. <br /><br />When the ID matches a request, Bot Management sets the bot score to 29 and uses [anomaly detection](/bots/concepts/bot-detection-engines/#anomaly-detection-enterprise) as its score source. |

# Detection IDs

import { Render, Tabs, TabItem, Steps, DashButton } from "~/components";

Detection IDs are static rules that detect predictable bot behavior with no overlap with human traffic. Each ID maps to a specific [detection method](/bots/concepts/bot-detection-engines/) such as heuristics, verified bot detections, or anomaly detections. For example, a detection ID can identify when a client sends headers in a different order than what its claimed browser would use.

If you are having an issue with one of our heuristics, detection IDs allow you to decide which heuristics to enforce on your zones using customer configurable heuristics. You can choose unique actions for different bots, detected through Cloudflare’s heuristics engine. You can block, allow, or serve alternate content to specific bots to meet the unique needs of your site’s traffic.

:::note
A request can trigger multiple detection IDs.
:::

You can use `cf.bot_management.detection_ids` fields in tools such as:

- [Custom rules](/waf/custom-rules/)
- [Advanced Rate Limiting](/waf/rate-limiting-rules/)
- [Transform Rules](/rules/transform/)
- [Workers](/workers/) (as `request.cf.botManagement.detectionIds`)

Bot Detection IDs and tags are also available in [Bot Analytics](/bots/bot-analytics/) and [Security Analytics](/waf/analytics/security-analytics/).

:::caution[Beta detections]
Cloudflare may occasionally try beta detections as we continuously improve our detections.

It is possible, but uncommon, for you to have beta detection IDs on the Cloudflare dashboard that are not actively collecting data on your zone.
:::

---

## Detection tags

Detection tags refer to the category associated with the detection ID at the time that Cloudflare has fingerprinted a bot. For example, if a detection tag is `go`, this means that Cloudflare has observed traffic from that detection ID from a Go programming language bot.

:::note

Detection tags are available in Security Analytics, but not in the Security Events.
:::

---

## Create or edit an expression

<Steps>
  1. In the Cloudflare dashboard, go to the **Security Analytics** page.

      <DashButton url="/?to=/:account/:zone/security/analytics" />
  2. Apply filters and select **Create custom security rule** to create a custom rule based on your filters.

      Alternatively, if you have already created a custom rule, you can go to the existing rule in **Security rules** and edit the expression based on your filters.

      <DashButton url="/?to=/:account/:zone/security/security-rules" />
  3. Use the `cf.bot_management.detection_ids` field in the rule expression.
  4. Select **Deploy**.
</Steps>

---

## Use cases

### Block requests that match a specific detection ID

```js
any(cf.bot_management.detection_ids[*] eq 3355446)
and not cf.bot_management.verified_bot
and http.request.uri.path eq "/login"
and http.request.method eq "POST"
```

### Run Bot Management without specific detection IDs

```js
cf.bot_management.score lt 30
and not cf.bot_management.verified_bot
and http.request.uri.path eq "/login"
and http.request.method eq "POST"
and not any(cf.bot_management.detection_ids[*] in {3355446 12577893})
```

---

## Bot Detection IDs via Logpush

You can create or edit existing Logpush jobs to include the new Bot Detection IDs field which will provide an array of IDs for each request that has heuristics match on it. The `BotDetectionIDs` field is available as part of the HTTP Requests dataset and you can add it to new or existing jobs via the Logpush API or on the Cloudflare dashboard. This is the primary method to discover Detection IDs.

<Tabs>
  <TabItem label="Dashboard">
    <Steps>
      1. In the Cloudflare dashboard, go to the **Logpush** page.

          <DashButton url="/?to=/:account/logs" />
      2. Select **Create a Logpush Job**.
      3. Select and enter the destination information.
      4. Select **HTTP Requests** as the dataset.
      5. Select **BotDetectionIDs** under the General data field category.
      6. Prove the ownership.
      7. Select **Save**.
    </Steps>
  </TabItem>
  <TabItem label="API">
    [Update your logpush job](/logs/logpush/logpush-job/log-output-options/) by adding `BotDetectionIDs` to the  `output_options:`  parameters.
  </TabItem>
</Tabs>

---

## Availability

Detection IDs are available for Enterprise Bot Management customers.

# Scraping detections

import { Steps, DashButton } from "~/components";

Scraping behavioral detection IDs allow you to better protect your website from volumetric scraping attacks by identifying anomalous behavior. The detection IDs below are specifically designed to catch suspicious scraping activity at the zone level.

| <div style="width:100px">Detection ID</div> | Description                                                                                         |
| ------------------------------------------- | --------------------------------------------------------------------------------------------------- |
| `50331648`                                  | Observes patterns of requests sent to your zone, dynamically analyzing behavior by ASN.             |
| `50331649`                                  | Observes patterns of requests sent to your zone, dynamically analyzing behavior by JA4 fingerprint. |

## Challenges for scraping detections

Cloudflare's [Managed Challenge](/cloudflare-challenges/challenge-types/challenge-pages/#managed-challenge) can limit scraping attacks on your website.

To access scraping detections:

<Steps>
	1. In the Cloudflare dashboard, go to the **Security rules** page.

		<DashButton url="/?to=/:account/:zone/security/security-rules" />
	2. Select **Create rule** and choose **Custom rule**.
	3. Fill out the form using **Bot Detection IDs** along with other necessary information.
	4. Select **Save as draft** to return to the rule later, or **Deploy** to deploy the rule.
</Steps>

```js title="Rule example"

(any(cf.bot_management.detection_ids[*] in {50331648 50331649}) and not cf.bot_management.verified_bot)
```

:::tip[Best practice]
If you are choosing to challenge as your rule action, ensure that you exclude any API calls on which you do not want to issue a challenge. To exclude requests to such paths, edit the [WAF custom rule](/waf/custom-rules/) to exclude the relevant paths.
:::

:::note
The matched traffic for detection IDs `50331648` and `50331649` is dynamically re-calculated, meaning a single fingerprint would not be permanently flagged unless it continues to behave suspiciously at all times.
:::

# JA3/JA4 fingerprint

import { Render } from "~/components"

[**JA3**](https://github.com/salesforce/ja3) and [**JA4**](https://github.com/FoxIO-LLC/ja4) **fingerprints** identify TLS clients based on how they initiate connections. Each client type (browser, bot, or application) has distinct connection characteristics, so the resulting fingerprint acts as a stable identifier across different destination IPs, ports, and certificates.

JA4 improves on JA3 by sorting ClientHello extensions, which reduces the number of unique fingerprints for modern browsers and makes grouping easier.

:::note

JA3 and JA4 fingerprints are only available to Enterprise customers who have purchased Bot Management. 
:::

<Render file="signals-intelligence-and-ja4" product="bots" />

```json

{
  "ja4Signals": {
    "h2h3_ratio_1h": 0.98826485872269,
    "heuristic_ratio_1h": 7.288895722013e-05,
    "reqs_quantile_1h": 0.99905741214752,
    "uas_rank_1h": 901,
    "browser_ratio_1h": 0.93640440702438,
    "paths_rank_1h": 655,
    "reqs_rank_1h": 850,
    "cache_ratio_1h": 0.18918327987194,
    "ips_rank_1h": 662,
    "ips_quantile_1h": 0.99926590919495
  },
  "jaSignalsParsed": {
    "ratios": {
      "h2h3_ratio_1h": 0.98826485872269,
      "heuristic_ratio_1h": 7.288895722013e-05,
      "browser_ratio_1h": 0.93640440702438,
      "cache_ratio_1h": 0.18918327987194
    },
    "ranks": {
      "uas_rank_1h": 901,
      "paths_rank_1h": 655,
      "reqs_rank_1h": 850,
      "ips_rank_1h": 662
    },
    "quantiles": {
      "reqs_quantile_1h": 0.99905741214752,
      "ips_quantile_1h": 0.99926590919495
    }
  }
}

```

When JA4 Signals are missing, the output appears as follows:

```json output title="Missing JA4 signals output"
{
  "ja4Signals": {},
  "jaSignalsParsed": {
    "ratios": {},
    "ranks": {},
    "quantiles": {}
  }
}
```

:::note

This sample was generated using [Workers' Cloudflare Object script](/workers/examples/accessing-the-cloudflare-object/). 
:::

<Render file="ja3-ja4-null" product="bots" />

## Analytics

To get more information about potential bot requests, use these JA3 and JA4 fingerprints in:

- [Bot Analytics](/bots/bot-analytics/#enterprise-bot-management)
- [Security Events](/waf/analytics/security-events/) and [Security Analytics](/waf/analytics/security-analytics/)
- [Analytics GraphQL API](/analytics/graphql-api/), specifically the **HTTP Requests** dataset
- [Logs](/logs/logpush/logpush-job/datasets/zone/http_requests/)

## Actions

To adjust how your application responds to specific fingerprints, use them with:

- [WAF custom rules](/waf/custom-rules/)
- [Transform Rules](/rules/transform/)
- [Cloudflare Workers](/workers/runtime-apis/request/#incomingrequestcfproperties)

## Use cases

### Block or allow certain traffic

A group of similar requests may share the same JA3 fingerprint. For this reason, JA3 may be useful in blocking an incoming threat. For example, if you notice that a bot attack is not caught by existing defenses, create a [custom rule](/waf/custom-rules/) that blocks or challenges the JA3 used for the attack.

Alternatively, if existing defenses are blocking traffic that is actually legitimate, create a [custom rule](/waf/custom-rules/) with the _Skip_ action allowing the JA3 seen across good requests.

JA3 may also be useful if you want to immediately remedy false positives or false negatives with Bot Management.

### Allow mobile traffic

Often, mobile application traffic will produce the same JA3 fingerprint across devices and users. This means you can identify your mobile application traffic by its JA3 fingerprint.

Use the JA3 fingerprint to [allow traffic](/waf/custom-rules/use-cases/challenge-bad-bots/#adjust-for-mobile-traffic) from your mobile application, but block or challenge remaining traffic.

# Signals Intelligence

import { Render } from "~/components"

Bot Management customers can view aggregate intelligence data for each [JA4 fingerprint](/bots/additional-configurations/ja3-ja4-fingerprint/) based on traffic across the Cloudflare network. Use this data to understand why a request received a specific bot score or to feed into your own machine learning models running in [Cloudflare Workers](/workers/) or at your origin.

Specifically, for each JA4 fingerprint, you will be able to access the following information:

- The percentage of traffic associated with browsers that Cloudflare sees.
- The percentage of traffic associated with known bots that Cloudflare sees.
- The number of networks Cloudflare sees actively using this fingerprint.
- The number of Cloudflare sites that see traffic from this fingerprint.
- The frequency that fingerprint requests caches content and generates errors.

You can also use these fields with [Workers AI](/workers-ai/) to build custom machine learning models.

## Signals Intelligence fields

Signals Intelligence fields show observations about a particular JA4 that Cloudflare has seen globally over the last hour.

| <div style="width:170px">Field name</div> | Description                                                                                                                                                                                                                                       |
| ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `h2h3_ratio_1h`                           | The ratio of HTTP/2 and HTTP/3 requests combined with the total number of requests for the JA4 fingerprint in the last hour. Higher values indicate a higher proportion of HTTP/2 and HTTP/3 requests compared to other protocol versions.        |
| `heuristic_ratio_1h`                      | The ratio of requests with a `scoreSrc` value of "heuristics" for the JA4 fingerprint in the last hour. Higher values suggest a larger proportion of requests being flagged by heuristic-based scoring.                                           |
| `reqs_quantile_1h`                        | The quantile position of the JA4 fingerprint based on the number of requests across all fingerprints in the last hour. Higher values indicate a relatively higher number of requests compared to other fingerprints.                              |
| `uas_rank_1h`                             | The rank of the JA4 fingerprint based on the number of distinct user agents across all fingerprints in the last hour. Lower values indicate a higher diversity of user agents associated with the fingerprint.                                    |
| `browser_ratio_1h`                        | The ratio of requests originating from browser-based user agents for the JA4 fingerprint in the last hour. Higher values suggest a higher proportion of browser-based requests.                                                                   |
| `paths_rank_1h`                           | The rank of the JA4 fingerprint based on the number of unique request paths across all fingerprints in the last hour. Lower values indicate a higher diversity of request paths associated with the fingerprint.                                  |
| `reqs_rank_1h`                            | The rank of the JA4 fingerprint based on the number of requests across all fingerprints in the last hour. Lower values indicate a higher number of requests associated with the fingerprint.                                                      |
| `cache_ratio_1h`                          | The ratio of cacheable responses for the JA4 fingerprint in the last hour. Higher values suggest a higher proportion of responses that can be cached.                                                                                             |
| `ips_rank_1h`                             | The rank of the JA4 fingerprint based on the number of unique client IP addresses across all fingerprints in the last hour. Lower values indicate a higher number of distinct client IPs associated with the fingerprint.                         |
| `ips_quantile_1h`                         | The quantile position of the JA4 fingerprint based on the number of unique client IP addresses across all fingerprints in the last hour. Higher values indicate a relatively higher number of distinct client IPs compared to other fingerprints. |

<Render file="signals-intelligence-and-ja4" product="bots" />

:::note
Signals Intelligence fields are available for analysis in [Security Analytics](/waf/analytics/security-analytics/) and [Security Events](/waf/analytics/security-events/). They cannot be used as filter fields in WAF custom rule expressions.
:::

# Bot detection engines

import { Render } from "~/components";

Cloudflare uses multiple detection engines because different bot types require different detection strategies. Simple bots can be caught by pattern matching against known signatures, while sophisticated bots require machine learning and behavioral analysis.

The engines available to your domain depend on your plan.

## Heuristics

<Render file="bots-heuristics" product="bots" />

## JavaScript detections

<Render file="bots-jsd" product="bots" />

JSD is completely optional. To adjust your settings, configure Super Bot Fight Mode from **Security** > **Bots**.

## Adaptive Intelligence (Business and Enterprise)

<Render file="bots-ml" product="bots" />

<Render file="latest-ml-model-enable" product="bots" />

If you do not enable auto-updates, a fixed model version continues to score your traffic. To learn what changes when you enable auto-updates, refer to [Machine Learning models](/bots/reference/machine-learning-models/).

## Anomaly detection (Enterprise)

<Render file="bots-ad" product="bots" />

## Notes on detection

<Render file="bots-cookie" product="bots" />

<Render file="disable-cf-bm-cookie" product="bots" />

# Bot scores

import { GlossaryTooltip, Render } from "~/components";

A bot score is a score from _1_ to _99_ that indicates how likely that request came from a bot.

For example, a score of 1 means Cloudflare is quite certain the request was automated, while a score of 99 means Cloudflare is quite certain the request came from a human.

You can use bot scores in [WAF custom rules](/waf/custom-rules/) to block, challenge, or allow requests based on their score. Bot scores are also available in [Workers](/workers/) to customize application behavior. For more details, refer to [Bot Management variables](/bots/reference/bot-management-variables/).

:::note

Granular bot scores are only available to Enterprise customers who have purchased Bot Management. All other customers can only access this information through [bot groupings](#bot-groupings) in Bot Analytics.
:::

## Bot groupings

Customers with a Pro plan or higher can automatically see bot traffic divided into groups by going to **Security** > **Bots**.

| Category             | Range                                                                                  |
| -------------------- | -------------------------------------------------------------------------------------- |
| **Not computed**     | Bot scores of 0.                                                                       |
| **Automated**        | Bot scores of 1.                                                                       |
| **Likely automated** | Bot scores of 2 through 29.                                                            |
| **Likely human**     | Bot scores of 30 through 99.                                                           |
| **Verified bot**     | Non-malicious automated traffic (used to power search engines and other applications). |

:::note

Bot scores are not computed for requests to paths that are handled by Cloudflare and will never be blocked or forwarded to the origin. Note that some features that are enabled before Bot Management, such as Redirect Rules, may result in requests not being scored.
:::

## How Cloudflare generates bot scores

The following detection engines only apply to Enterprise Bot Management. For specific details about the engines included in your plan, refer to [Plans](/bots/plans/).

### Heuristics

Catches automated traffic through pattern matching against a database of known malicious fingerprints.

<Render file="bots-heuristics" product="bots" />

The Heuristics engine gives automated requests a score of 1 for high-confidence, deterministic detections. Occasionally, heuristics will set a score of 29 in cases where Cloudflare has identified automated traffic and is still assessing traffic overlap.

### Machine learning

Catches sophisticated bots by analyzing request features across billions of daily requests. Produces most scores between 2 and 99.

<Render file="bots-ml" product="bots" />

### Anomaly detection

Detects outlier requests by comparing traffic against a learned baseline for your specific site.

<Render file="bots-ad" product="bots" />

### JavaScript detections

Catches headless browsers (browsers controlled by software, with no visible window or human operator) and other automation tools.

<Render file="bots-jsd" product="bots" />

JSD is enabled by default but completely optional. To adjust your settings, open the Bot Management Configuration page from **Security** > **Bots**.

### Cloudflare service

**Cloudflare Service** is a special <GlossaryTooltip term="bot score">bot score</GlossaryTooltip> source for Enterprise Zero Trust to avoid false positives.

### Not computed

A bot score of 0 means Bot Management did not evaluate the request. This applies to internal Cloudflare service requests and requests that were redirected or handled by another feature (such as [Redirect Rules](/rules/url-forwarding/)) before Bot Management could run. A score of 0 does not indicate the request is safe or human.

### Notes on detection

<Render file="bots-cookie" product="bots" />

:::note

Requests with a missing or empty `User-Agent` header are immediately assigned a bot score of **1** by the Heuristics engine. This is expected behavior and a common false-positive trigger for traffic from [Zero Trust](/cloudflare-one/) (WARP) or corporate proxy environments that suppress or strip the `User-Agent` header.

If you are seeing unexpected score-1 traffic from known corporate users, check whether a proxy is removing the header. You can use the [`cf.bot_management.corporate_proxy`](/bots/reference/bot-management-variables/#corporate-proxy) field or an IP allowlist to exempt that traffic from bot-based actions.

:::

# Bot tags

import { Render, GlossaryTooltip } from "~/components"

<GlossaryTooltip term="bot tags">Bot tags</GlossaryTooltip> provide more detail about *why* Cloudflare assigned a <GlossaryTooltip term="bot score" link="/bots/concepts/bot-score/">bot score</GlossaryTooltip> to a request.

Use these tags to learn more about your bot traffic and better inform security settings.

:::note

Bot tags are only available to Enterprise customers who have purchased Bot Management.
:::

## Potential values

Once you [enable bot tags](#enable-bot-tags), you can see more information about bot requests, such as whether a request came from a verified bot (like Bing) or a category of verified bot (like SearchEngine).

The following values are **examples** of what may be present in the `BotTags` log field, but not an exhaustive list:

- api
- google
- bing
- googleAds
- googleMedia
- googleImageProxy
- pinterest
- newRelic
- baidu
- apple
- yandex

When matching the Ruleset Engine field, use uppercase tag values such as `API`, `GOOGLE`, or `BING`.

## Use bot tags

To include bot tags in logs, add the `BotTags` field when using [Logpush](/logs/logpush/).

To match bot tags in Ruleset Engine expressions, use the [`cf.bot_management.tags`](/ruleset-engine/rules-language/fields/reference/cf.bot_management.tags/) field. For example:

```txt
any(cf.bot_management.tags[*] eq "API")
```

# Bot Feedback Loop

import { GlossaryTooltip, Steps, DashButton } from "~/components";

The Bot Feedback Loop allows you to report requests that Bot Management <GlossaryTooltip term="bot score" link="/bots/concepts/bot-score/">scored</GlossaryTooltip> incorrectly. When you submit a false negative or false positive report, Cloudflare analyzes the data and uses it to train the next machine learning model.

## Availability

Bot Feedback Loop is available for Enterprise Bot Management customers. Visit [Plans](/bots/plans/) for more information.

## False Positive

A false positive can happen if Cloudflare scores a request from a person using a browser, mobile application or desktop application in the _automated_ or _likely automated_ range.

## False Negative

If Cloudflare is unable to detect a portion of automated traffic on your site, submitting a False Negative report will help us catch it in the future.

### Subtypes

| Subtype                | Definition                                                                                                                                                                                                |
| ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Account Creation Abuse | The automated creation of many new accounts in order to gain access to site resources.                                                                                                                    |
| Ad Fraud               | Fraudulent increase in the number of times an advertisement is clicked on or displayed.                                                                                                                   |
| Credit Card Abuse      | Attempts to repeatedly validate many credit card numbers or the same credit card number with different validation details.                                                                                |
| Cashing Out            | Abusing the target Internet application to obtain valuable goods.                                                                                                                                         |
| Login Abuse            | Attempts to gain access to a password protected portion of an Internet application using many different combinations of usernames and passwords.                                                          |
| Inventory Abuse        | Automated abuse related to purchasing limited stock inventory or holding inventory to prevent others from making transactions.                                                                            |
| Denial of Service      | Automated requests with the intent of exhausting server resources to prevent the Internet application from functioning.                                                                                   |
| Expediting             | Automating the use of an Internet application to make transactions faster than a human visitor to gain unfair advantage.                                                                                  |
| Fuzzing                | Finding implementation bugs through the use of malformed data injection in an automated fashion.                                                                                                          |
| Scraping               | Automated retrieval of valuable or proprietary information from an Internet application.                                                                                                                  |
| Spamming               | The abuse of content forms to send spam.                                                                                                                                                                  |
| Token Cracking         | Identification of valid token codes providing some form of user benefit within the application.                                                                                                           |
| Vulnerability Scanning | Systematic enumeration and examination of identifiable, guessable and unknown content locations, paths, file names, parameters, to find weaknesses and points where a security vulnerability might exist. |

## Submit a report

<Steps>
  1. In the Cloudflare dashboard, go to the **Security Analytics** page.

      <DashButton url="/?to=/:account/:zone/security/analytics" />
  2. Apply one or more filters.
  3. Under **Request activity**, filter by **Bot analysis**.
  4. Select **Report incorrect data** and fill out the form.
  5. Select **Submit**.
</Steps>

## Via the API

### Create a feedback report

```sh
curl 'https://api.cloudflare.com/client/v4/zones/{zone_id}/bot_management/feedback' \
--header "X-Auth-Email: <EMAIL>" \
--header "X-Auth-Key: <API_KEY>" \
--header "Content-Type: application/json" \
--data '{
  "type": "false_positive",
  "description": "Legitimate customers having low score",
  "expression": "(cf.bot_management.score le 46 and ip.src.asnum eq 132892 and http.host eq \"api-discovery.theburritobot.com\" and cf.bot_management.ja3_hash eq \"3fed133de60c35724739b913924b6c24\")",
  "first_request_seen_at": "2022-08-01T00:00:00Z",
  "last_request_seen_at": "2022-08-10T00:00:00Z",
  "requests": 100,
  "requests_by_score": {
    "1": 50,
    "10": 50
  },
  "requests_by_score_src": {
    "heuristics": 25,
    "machine_learning": 75
  },
  "requests_by_attribute": {
    "topIPs": [
      {
        "metric": "10.75.34.1",
        "requests": 100
      }
    ],
    "topUserAgents": [
      {
        "metric": "curl/7.68.0",
        "requests": 100
      }
    ]
  }
}'
```

### List feedback reports

```bash
curl 'https://api.cloudflare.com/client/v4/zones/{zone_id}/bot_management/feedback' \
--header "X-Auth-Email: <EMAIL>" \
--header "X-Auth-Key: <API_KEY>"
```

```json output
[
	{
		"created_at": "2022-08-19T00:05:24.749712Z",
		"type": "false_positive",
		"description": "Legitimate customers having low score",
		"expression": "(cf.bot_management.score le 46 and ip.src.asnum eq 132892 and http.host eq \"api-discovery.theburritobot.com\" and cf.bot_management.ja3_hash eq \"3fed133de60c35724739b913924b6c24\")",
		"first_request_seen_at": "2022-08-01T00:00:00Z",
		"last_request_seen_at": "2022-08-10T00:00:00Z",
		"requests": 100,
		"requests_by_score": {
			"1": 50,
			"10": 50
		},
		"requests_by_score_src": {
			"heuristics": 25,
			"machine_learning": 75
		},
		"requests_by_attribute": {
			"topIPs": [
				{
					"metric": "10.75.34.1",
					"requests": 100
				}
			],
			"topUserAgents": [
				{
					"metric": "curl/7.68.0",
					"requests": 100
				}
			]
		}
	}
]
```

## API Fields

| Field                   | Type    | Description                                                                 | Value Example                                                                                                                                                        |
| ----------------------- | ------- | --------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type`                  | string  | The feedback report type.                                                   | `false_positive`                                                                                                                                                     |
| `description`           | string  | The feedback report description with more details on the issue.             | Legitimate customers having low scores.                                                                                                                              |
| `expression`            | string  | The wirefilter expression matching reported requests.                       | `(cf.bot_management.score le 46 and ip.src.asnum eq 132892 and http.host eq "app.example.com" and cf.bot_management.ja3_hash eq "3fed133de60c35724739b913924b6c24")` |
| `first_request_seen_at` | string  | The time range start when the first request has been seen, RFC 3339 format. | `2022-08-01T00:00:00Z`                                                                                                                                               |
| `last_request_seen_at`  | string  | The time range end when the last request has been seen, RFC 3339 format.    | `2022-08-10T00:00:00Z`                                                                                                                                               |
| `requests`              | integer | The total number of reported requests.                                      | `100`                                                                                                                                                                |
| `requests_by_score`     | object  | The requests breakdown by score.                                            | See example below.                                                                                                                                                   |
| `requests_by_score_src` | object  | Requests breakdown by score source.                                         | See example below.                                                                                                                                                   |
| `requests_by_attribute` | object  | Requests breakdown by attribute (optional).                                 | See example below.                                                                                                                                                   |

`requests_by_score`

```json
{
	"1": 50,
	"10": 50
}
```

`requests_by_score_src`

```json
{
	"machine_learning": 75,
	"heuristics": 25
}
```

`requests_by_attribute`

```json
{
	"topIPs": [
		{
			"metric": "10.75.34.1"
			"requests": 100
		}
	],
	"topUserAgents": [
		{
			"metric": "curl/7.68.0",
			"requests": 100
		}
	]
}
```

### Expression fields

| Field                        | Type    | Description                                                                                                                                                                 |
| ---------------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `cf.bot_management.ja3_hash` | string  | This provides an SSL/TLS fingerprint to help you identify potential bot requests.                                                                                           |
| `cf.bot_management.score`    | integer | This represents the likelihood that a request originates from a bot using a score from 1-99.                                                                                |
| `http.host`                  | string  | This represents the hostname used in the full request URI.                                                                                                                  |
| `http.request.uri.path`      | string  | This represents the URI path of the request.                                                                                                                                |
| `http.user_agent`            | string  | This represents the HTTP user agent which is a request header that contains a characteristic string to allow identification of the client operating system and web browser. |
| `ip.src.asnum`               | integer | This represents the 16- or 32-bit integer representing the Autonomous System (AS) number associated with client IP address.                                                 |
| `ip.src.country`             | string  | This represents the 2-letter country code in ISO 3166-1 Alpha 2 format.                                                                                                     |
| `ip.src`                     | string  | The source address of the IP.                                                                                                                                               |

## Recommendations when submitting a report

When you submit a report, use the filters available in the Bot Analytics dashboard to ensure that your report includes only the traffic that received an incorrect score. In addition to filtering by a score (required), you may want to filter by user-agent, IP, ASN or JA3 to more precisely highlight the section of traffic that was scored incorrectly.

If you are not certain if some traffic received an incorrect score, keep this traffic in the report.

We appreciate any comments you wish to leave in the description field that might help our team better understand these requests in the context of typical traffic to your domain.

## Recommendations after submitting a false positive

:::note
The instructions below apply to Enterprise subscription with Bot Management only.
:::

After submitting a false positive, you can explicitly allow the traffic if you are confident that this traffic source cannot be used for abuse in the future. To allow traffic, you can create a WAF custom rule with a [Skip the remaining custom rules](/waf/custom-rules/skip/options/#skip-the-remaining-custom-rules-current-ruleset) action that matches the characteristics of your false positive report. We recommend any skip rule that you create uses the most narrow possible scope, including restricting the request methods and URIs that the expected traffic has access to, to limit potential abuse.

- Allowing a **[JA3/JA4 fingerprint](/bots/additional-configurations/ja3-ja4-fingerprint/)**: If you want to allow access to a stable software client that does not come from a dedicated IP, you can do so by looking up the JA3 fingerprint(s) used by that client in the Bot Analytics dashboard, and creating a WAF custom rule to allow traffic based on that JA3 fingerprint. JA3 fingerprints will only match a client’s TLS library, so be cautious in looking for both overlap with other clients and with variation based on the operating system. <br/><br/>Cloudflare does not recommend relying on JA3 rules for mobile applications that may be abused. If you have questions about how to securely allow traffic from your mobile application, please contact your account team.

:::note
The instructions below apply to Enterprise subscription with Bot Management, Bot Fight Mode and Super Bot Fight Mode.
:::

- Allowing an **IP address**: Only use an IP address to allow traffic if the IP is a dedicated resource that belongs only to the traffic source you wish to allow. <br/>If the traffic you want to allow shares an IP with other traffic sources, or if the IP changes frequently, consider an alternative to allowing by IP address.

## Recommendations after submitting a false negative

After submitting a false negative report, you can explicitly block or rate-limit the incorrectly scored traffic using a combination of characteristics such as IP address, JA3 fingerprint, ASN, and user-agent. Before blocking or rate-limiting based on JA3 fingerprint, please use Bot Analytics to confirm that fingerprint is not being used by legitimate traffic sources.

# Concepts

import { DirectoryListing } from "~/components"

Refer to the following pages for more information on bot concepts:

<DirectoryListing />

# Bots

A **bot** is a software application programmed to do certain tasks.

Bots can be used for good (chatbots, search engine crawlers) or for evil (inventory hoarding, credential stuffing).

:::note[More information]

For more background, refer to [What is a bot?](https://www.cloudflare.com/learning/bots/what-is-a-bot/).
:::

## AI bots

AI crawlers and agents interact with your site for very different reasons, and you may want to treat those reasons differently. Rather than relying on a single "AI bot" label, Cloudflare classifies bots by **behavior** — what a bot does on your site — so you can allow the behavior that helps your business and block the behavior that harms it. A single bot can have more than one behavior.

### Classification

Cloudflare lets all customers manage three AI-related use cases directly:

| Behavior | What it does |
| --- | --- |
| **Search** | Collects or indexes your content so it can answer questions about it later. |
| **Agent** | Automated activity acting in real time on a person's behalf to get something done, such as chat fetch bots and browser-use agents. |
| **Training** | Crawls your content to train or fine-tune a model, permanently absorbing your data into the model. |

Cloudflare classifies other behaviors, too — refer to [Verified bots](/bots/concepts/bot/verified-bots/).

# Verified bots

import { GlossaryTooltip } from "~/components";

A <GlossaryTooltip term="verified bot">Verified bot</GlossaryTooltip> is a bot or agent that Cloudflare has confirmed is **transparent about who it is and what it does**: it represents itself honestly and does not abuse the access that honesty earns. Examples include search engine crawlers, monitoring services, and user-driven agents.

Being Verified means a bot or agent meets two bars:

1. **Honest self-identification** — it declares who it is deterministically, through a cryptographic [Web Bot Auth](/bots/reference/bot-verification/web-bot-auth/) signature, a published IP list with a stable user-agent, or reverse DNS.
2. **Non-abusive behavior** — it obeys `robots.txt` and crawl directives, maintains reasonable request rates, and has not been observed evading website owner preferences or attacking sites.

:::note[Signed agents are now Verified]
As of July 1, 2026, the distinction between a Verified bot and a signed agent is expressed by a new metadata field tracked in [BotBase](/bots/botbase/): Direct versus Intermediary access, which tracks who can operate the bot.
:::

## Classification

:::note
These updated classifications reflect the new taxonomy of bots used in [BotBase](/bots/botbase/). They are not individual fields in WAF custom rules, but have backwards-compatible categories from the original taxonomy of Verified bots (see [Legacy categories](#legacy-categories) below).
:::

Cloudflare classifies each tracked bot by its behavior — what the bot may do on your site. A single bot can have one or more of the following behaviors:

| Behavior | Description |
| --- | --- |
| Search | Crawling to build search indexes or RAG databases. |
| Agent | User-directed agents visiting a page on behalf of a human. |
| Training | Crawling to train or fine-tune models. |
| Transact | Checkout or other transaction actions on behalf of users. |
| Data Collection | Price scraping, competitive intelligence gathering, and third-party analytics. |
| Security Testing | Vulnerability scanning and penetration testing. |
| SEO | SEO crawling, site auditing, and accessibility checks. |
| Ads Verification | Ad placement verification and ad fraud detection. |
| Social / Link Preview | Link previews for social platforms and messaging apps. |
| Feed Fetching | RSS readers, podcast aggregators, and news feed bots. |
| Monitoring & Operations | Uptime monitoring, webhooks, and health checks. |

Search, Agent, and Training are also available as managed presets you can act on across all plans. For more information, refer to [AI bots](/bots/concepts/bot/#ai-bots).

Cloudflare also labels every Verified bot or agent by how it is operated.

| Label | Description |
| --- | --- |
| **Direct** | Operated by a single, narrow operator — usually on the operator's own infrastructure. Only that operator can send requests that present as this bot. |
| **Intermediary** | An agentic service that a wide range of end users can operate. The operator runs the software, but each action is initiated by a different end user. |

Because an **intermediary** acts on behalf of many different end users, the operator and the end user are not the same party. This introduces **transitive trust**: you may trust the intermediary operator, but not necessarily every end user driving it. Cloudflare is experimenting with forwarding information about the end user (using the `Forwarded` header defined in [RFC 7239](https://www.rfc-editor.org/info/rfc7239)) so that website owners can apply their preferences to the party ultimately responsible for a request.

## Becoming a Verified bot

You can request for your bot or agent to be added to Cloudflare's bots and agents directory by filling out the [BotBase submission form](https://dash.cloudflare.com/?to=/:account/application-security/botbase/form) in the Cloudflare dashboard.

Once Cloudflare approves a Verified bot, it should appear in [BotBase](/bots/botbase/), shared through [Cloudflare Radar's bots and agents directory](https://radar.cloudflare.com/verified-bots).

### Track your submission

After submitting, track your application's progress in the Cloudflare dashboard under [BotBase > Submission history](https://dash.cloudflare.com/?to=/:account/application-security/botbase/history).

| Status | Meaning |
| --- | --- |
| Waiting For Review | Cloudflare has received your submission and it is queued for review. |
| Accepted | Your bot was approved and will appear in BotBase and Radar's bots and agents directory. |
| Rejected | Your submission was declined. The dashboard does not show the rejection reason — [contact Cloudflare Support](/support/contacting-cloudflare-support/) for details. |
| Cancelled | The submission was withdrawn. |

The bot must be Verified using one of the following validation methods:

- [Web Bot Auth](/bots/reference/bot-verification/web-bot-auth/)
- [IP validation](/bots/reference/bot-verification/ip-validation/)

### Breach of policy

If any of the requirements to validate are breached, a service will be removed from the global allowlist.

The following are examples of breaches of policy:

- Adding a set of IPs that are not solely used by Verified service.
- The service IPs are breached by an attacker.
- The service has vulnerabilities that have not been patched.
- A block of IPs not briefed on onboarding is added to the list.
- The disclosed purpose of the service does not reflect on the traffic.
- An AI Crawler that does not respect the crawl-delay directive in robots.txt.

## Legacy categories

:::note
The original categories of Verified bots continue to be usable in WAF custom rules and currently continue to work as before, even as Cloudflare continues launching new capabilities based on the updated taxonomy.
:::

<details>
<summary>Academic research</summary>

**String value**: `Academic Research`

**Definition**: Gathers data for scholarly research or academic purposes.

**Example**: Library of Congress, TurnItInBot, Bibliothèque nationale de France
</details>

<details>
<summary>Accessibility</summary>

**String value**: `Accessibility`

**Definition**: Scans websites to identify their accessibility.

**Example**: Accessible Web Bot
</details>

<details>
<summary>Advertising or marketing</summary>

**String value**: `Advertising & Marketing`

**Definition**: Automates marketing tasks including, but not limited to, ad placement and performance tracking.

**Example**: Google Adsbot
</details>

<details>
<summary>Aggregators</summary>

**String value**: `Aggregator`

**Definition**: Collects content from various online sources and consolidates it in one place.

**Example**: Pinterest, Indeed Jobsbot
</details>

<details>
<summary>AI Assistant</summary>

**String value**: `AI Assistant`

**Definition**: Automated AI bot driven by user action.

**Example**: Perplexity-User, DuckAssistBot
</details>

<details>
<summary>AI Crawler</summary>

**String value**: `AI Crawler`

**Definition**: Crawls websites for content that is used for training AI models.

**Example**: Google Bard, ChatGPT bot
</details>

<details>
<summary>AI Search</summary>

**String value**: `AI Search`

**Definition**: Powers AI-driven search experiences.

**Example**: OAI-SearchBot

:::note
Under the taxonomy introduced on July 1, 2026, there is no longer a meaningful distinction between "AI Search" and traditional search — both are treated as **Search** behavior. The `AI Search` category value is retained for backward compatibility with existing rules, but new search crawlers are classified under **Search**. Refer to [AI bots](/bots/concepts/bot/#ai-bots).
:::
</details>

<details>
<summary>Archiver</summary>

**String value**: `Archiver`

**Definition**: Saves snapshots of websites to preserve digital content for historical records.

**Example**: Internet Archive, CommonCrawl
</details>

<details>
<summary>Feed fetcher</summary>

**String value**: `Feed Fetcher`

**Definition**: Retrieves updates from feeds to power readers or other applications.

**Example**: RSS or Podcast feed updaters
</details>

<details>
<summary>Monitoring or analytics</summary>

**String value**: `Monitoring & Analytics`

**Definition**: Tracks a website's uptime, performance, and user traffic to gather key monitoring metrics.

**Example**: Uptime Monitors
</details>

<details>
<summary>Page preview</summary>

**String value**: `Page Preview`

**Definition**: Generates previews for links shared on social media or in messaging apps.

**Example**: Facebook, Slack, Twitter, or Discord Link Preview tools
</details>

<details>
<summary>Search engine crawler</summary>

**String value**: `Search Engine Crawler`

**Definition**: A bot that discovers and indexes web pages for search results.

**Example**: Googlebot, Bingbot, Yandexbot, Baidubot
</details>

<details>
<summary>Search engine optimization</summary>

**String value**: `Search Engine Optimization`

**Definition**: Analyzes websites to improve their standing in search engine results pages.

**Example**: Google Lighthouse, GT Metrix, Pingdom, AddThis
</details>

<details>
<summary>Security</summary>

**String value**: `Security`

**Definition**: Scans websites to detect security vulnerabilities and potential threats.

**Example**: Vulnerability Scanners, SSL Domain Control Validation (DCV) Check Tools
</details>

<details>
<summary>Social media marketing</summary>

**String value**: `Social Media Marketing`

**Definition**: Manages and automates activities on social platforms.

**Example**: Brandwatch
</details>

<details>
<summary>Webhooks</summary>

**String value**: `Webhooks`

**Definition**: An automated messenger that sends data from one application to another for specific events.

**Example**: Payment processors, WordPress Integration tools
</details>

<details>
<summary>Other</summary>

**String value**: `Other`

**Definition**: A dedicated category for bots that do not fit into the other classifications.
</details>

Cloudflare reserves the right to re-assign Verified bot categories if the bot's public documentation and observed behavior differ from the category listed in the bot submission form.

## Availability

Historically, Verified bots have been excluded in default bot configurations across all plans. Now, all customers have the option to [configure AI bot policies](/bots/additional-configurations/block-ai-bots/) to define their block vs. allow expectations.

# Bot Fight Mode

import { Steps, Render, DashButton, GlossaryTooltip } from "~/components";

Bot Fight Mode is a simple, free product that helps detect and mitigate bot traffic on your domain. When enabled, the product:

- Identifies traffic matching patterns of known bots
- Issues computationally expensive challenges that force the requesting client to perform CPU-intensive calculations, increasing the cost for bots to send automated requests
- Notifies [Bandwidth Alliance](https://cloudflare.com/bandwidth-alliance/) partners (if applicable) to disable bots

## Considerations

<Render file="about-plan-considerations" product="bots" />

## Interaction with other app security features

<Render
	file="app-security-interoperability"
	product="waf"
	params={{ botsFeatureName: "Bot Fight Mode" }}
/>

---

## Enable Bot Fight Mode

To start using Bot Fight Mode:

<Render file="enable-bfm" product="bots" />

<Render file="sbfm-upgrade" product="bots" />

---

## Disable Bot Fight Mode

If you find that **Bot Fight Mode** is causing problems with your application traffic, you may want to disable it.

To disable Bot Fight Mode:

<Steps>
  1. In the Cloudflare dashboard, go to the **Security Settings** page.

      <DashButton url="/?to=/:account/:zone/security/settings" />
  2. Filter by **Bot traffic**.
  3. Go to **Bot Fight Mode**.
  4. Turn **Bot Fight Mode** off.
</Steps>

---

## Block AI bots

Refer to [Block AI bots](/bots/additional-configurations/block-ai-bots/).

:::note

You can view blocked AI bot traffic via [Security Analytics](/waf/analytics/security-analytics/).
:::

---

## Visibility

You can see bot-related actions by going to **Security** > **Analytics** and selecting the **Events** tab. Any requests challenged by this product will be labeled **Bot Fight Mode** in the **Service** field. This allows you to observe, analyze, and follow trends in your bot traffic over time.

---

## Limitations

### Rules

You cannot bypass or skip Bot Fight Mode using WAF custom rules or Page Rules. This is because Bot Fight Mode does not run on the [Ruleset Engine](/ruleset-engine/) — it operates in a separate evaluation pipeline where _Skip_, _Bypass_, and _Allow_ actions have no effect.

If you need to create exceptions for specific traffic (for example, your own API clients or monitoring tools), use [Super Bot Fight Mode](/bots/get-started/super-bot-fight-mode/) instead. Super Bot Fight Mode runs on the Ruleset Engine and supports Skip rules.

Bot Fight Mode can still trigger if you have [IP Access rules](/waf/tools/ip-access-rules/), but it will not trigger if an IP Access rule matches the request first.

### JavaScript Detections

<Render
	file="jsd-availability"
	product="bots"
	params={{
		planType: "Bot Fight Mode",
		enablement: "automatically enabled and cannot be disabled",
	}}
/>

<Render file="content-security-policy-limitation" product="bots" />

# Bot Management

import { Steps, Render, DashButton } from "~/components";

Bot Management for Enterprise is a paid add-on that provides sophisticated bot protection for your domain. Customers can identify automated traffic, take appropriate action, and view detailed analytics within the dashboard.

This Enterprise product provides the most flexibility to customers by:

- Generating a [bot score](/bots/concepts/bot-score/) of 1-99 for every request. Scores below 30 are commonly associated with bot traffic. This lets you write targeted rules instead of applying blanket actions to all detected bots.
- Allowing customers to take action on this score with [WAF custom rules](/waf/custom-rules/) or [`Workers`](/workers/runtime-apis/request/#incomingrequestcfproperties). For example, you can challenge low-scoring requests on your login page while allowing them on your public blog.
- Allowing customers to view this score in Bot Analytics or Logs, so you can analyze bot traffic patterns and tune your rules over time.

---

## Enable Bot Management for Enterprise

Bot Management is automatically enabled for Enterprise zones entitled with the add-on.

<Steps>
  1. In the Cloudflare dashboard, go to the **Security Settings** page.

      <DashButton url="/?to=/:account/:zone/security/settings" />
  2. Filter by **Bot traffic**.
  3. Go to **Bot management**.
  4. Turn **Bot management** on.
  5. Choose how your domain should respond to various types of traffic by selecting the associated edit icon.
      - For more details on verified bots, refer to [Verified Bots](/bots/concepts/bot/verified-bots/).
      - For more details on supported file types, refer to [Static resource protection](/bots/additional-configurations/static-resources/).
      - For more details on invisible code injection, refer to [JavaScript detections](/cloudflare-challenges/challenge-types/javascript-detections/).
      - For more details on WordPress optimization, refer to [Super Bot Fight Mode for WordPress](/bots/troubleshooting/wordpress-loopback-issue/).
</Steps>

:::note

If you are not seeing Bot Management enabled on your zone or if you still see **Add Bot Management** on the Cloudflare dashboard, contact your account team for the proper entitlements.
:::

---

## Setup

Cloudflare recommends that you deploy the following basic settings and customize them according to the traffic in your zone.

### Enable the latest Machine Learning version

<Render file="latest-ml-model-enable" product="bots" />

### Block AI Bots

Refer to [Block AI bots](/bots/additional-configurations/block-ai-bots/).

:::note
You can view blocked AI bot traffic via [Security Analytics](/waf/analytics/security-analytics/).
:::

### Deploy custom rule templates

The **Definitely Automated** and **Likely Automated** toggles you configured in the previous step already provide baseline protection against automated traffic.

If you need additional control, such as path-specific protection, custom score thresholds, or combining bot score with other fields, Cloudflare provides [rule templates](https://dash.cloudflare.com/?to=/:account/:zone/security/security-rules?template=bot_traffic) to get started.

:::note
Custom rules created from these templates execute before the managed rules configured in **Security Settings**. For more details on this execution order, refer to [Security features interoperability](/waf/feature-interoperability/).
:::

These templates use wirefilter expression syntax. In these expressions, `eq` means equals, `le` means less than or equal to, `ge` means greater than or equal to, and `not` excludes matching traffic.

- [Definite Bots template](https://dash.cloudflare.com/?to=/:account/:zone:/security/security-rules/custom-rules/create?template=Definitely%20Bots): Targets malicious bot traffic while ignoring verified bots and routes delivering static content.

  ```txt wrap
  (cf.bot_management.score eq 1 and not cf.bot_management.verified_bot and not cf.bot_management.static_resource)
  ```

- [Likely Bots template](https://dash.cloudflare.com/?to=/:account/:zone/security/security-rules/custom-rules/create?template=Likely%20Bots): Targets traffic likely to be malicious bots while ignoring verified bots and routes with static content. It may contain a small amount of non-bot traffic.

  ```txt wrap
  (cf.bot_management.score ge 2 and cf.bot_management.score le 29 and not cf.bot_management.verified_bot and not cf.bot_management.static_resource)
  ```

- (Optional) [JavaScript detections template](https://dash.cloudflare.com/?to=/:account/:zone/security/security-rules/custom-rules/create?template=JavaScript%20Verified%20URLs): You must first enable JavaScript Detections from Security Settings, then set up a [managed challenge](/cloudflare-challenges/challenge-types/challenge-pages/#managed-challenge). Make sure to add a method and URI path. JavaScript detections improves security for URLs that should only expect JavaScript-enabled clients.

  ```txt wrap
  (not cf.bot_management.js_detection.passed and http.request.method eq "" and http.request.uri.path in {""})
  ```

# Get started with Cloudflare bot solutions

import { DirectoryListing } from "~/components"

Refer to the following pages to get started with Cloudflare's bot solutions based on your plan type:

<DirectoryListing />

# Super Bot Fight Mode

import { Render, Steps, DashButton } from "~/components";

Super Bot Fight Mode is included in your Pro, Business, or Enterprise subscription. Compared to [Bot Fight Mode](/bots/get-started/bot-fight-mode/), Super Bot Fight Mode adds configurable actions per bot category, bot analytics, and the ability to create exceptions using [WAF custom rules](/waf/custom-rules/). When enabled, the product:

- Identifies traffic matching patterns of known bots
- Can challenge or block bots
- Offers protection for static resources
- Provides limited analytics to help you understand bot traffic

Accounts with an Enterprise subscription but not the [Bot Management add-on](/bots/get-started/bot-management/) will have Super Bot Fight Mode for Business.

## Considerations

<Render file="about-plan-considerations" product="bots" />

### Interaction with other app security features

<Render
	file="app-security-interoperability"
	product="waf"
	params={{ botsFeatureName: "Super Bot Fight Mode" }}
/>

### Configure exceptions to Super Bot Fight Mode

[Custom rules](/waf/custom-rules/) are executed before Super Bot Fight Mode. To configure exceptions to Super Bot Fight Mode, create a custom rule with the [_Skip_ action](/waf/custom-rules/skip/). The _Skip_ action allows the request to bypass the Super Bot Fight Mode phase without terminating the request, enabling it to continue through the rest of the security stack.

## Enable Super Bot Fight Mode

<Render file="sbfm-upgrade" product="bots" />

To start using Super Bot Fight Mode:

<Render file="enable-sbfm" product="bots" />

:::caution[Warning]

If your organization also uses [Cloudflare Tunnel](/cloudflare-one/networks/connectors/cloudflare-tunnel/), keep **Definitely Automated** set to **Allow**. Otherwise, Super Bot Fight Mode may block tunnel connections, causing failures with a `websocket: bad handshake` error.
:::

<Render file="flexible-sbfm" product="bots" />

---

## Disable Super Bot Fight Mode

If you find that **Super Bot Fight Mode** is causing problems with your application traffic, you may want to disable it.

To disable Super Bot Fight Mode:

<Steps>
	1. In the Cloudflare dashboard, go to the **Security Settings** page.

		<DashButton url="/?to=/:account/:zone/security/settings" />
	2. Filter by **Bot traffic**.
	3. Go to **Super Bot Fight Mode**.
	4. For all bot groupings (**Definitely automated traffic**, **Likely automated traffic**, and **Verified bots**), set the value to **Allow**.
	5. For all other options (**Static resource protection**, **JavaScript detections**, and **Optimize for WordPress**), select the edit icon and ensure they are off.
</Steps>

<Render file="flexible-sbfm" product="bots" />

---

## Block AI bots

Refer to [Block AI bots](/bots/additional-configurations/block-ai-bots/).

:::note
You can view blocked AI bot traffic via [Security Analytics](/waf/analytics/security-analytics/).
:::

---

## Analytics

### Bot Report

Use the **Bot Report** to monitor bot traffic for the past 24 hours.

To access the **Bot Report**, go to **Security** > **Analytics** > **Bot analysis**. If you see a double-digit percentage of automated traffic, you may want to upgrade to [Bot Management](/bots/plans/bm-subscription/) to save money on origin costs and protect your domain from large-scale attacks.

![Example traffic distribution as part of a bot report](~/assets/images/bots/bot-report-pro.png)

### Security events

You can see bot-related actions by going to **Security** > **Analytics** and selecting the **Events** tab. Any requests challenged by this product will be labeled **Super Bot Fight Mode** in the **Service** field. This allows you to observe, analyze, and follow trends in your bot traffic over time.

---

## Ruleset Engine

Super Bot Fight Mode rules run after WAF custom rules in the request evaluation pipeline. Specifically, Super Bot Fight Mode runs during the `http_request_sbfm` phase of the [Ruleset Engine](/ruleset-engine/about/phases/).

<Render file="bfm-change-notice" product="bots" />

# Business

import { Render } from "~/components";

<Render file="plan-intro" product="bots" />

<Render file="buttons-plan-pages" product="bots" />

<table>
	<thead>
		<tr>
			<th width="25%"></th>
			<th width="30%"></th>
		</tr>
	</thead>
	<tbody>
		<tr>
			<td>
				<b>Plan name</b>
			</td>
			<td>Super Bot Fight Mode</td>
		</tr>
		<tr>
			<td>
				<b>Availability</b>
			</td>
			<td>
				All Business customers and Enterprise customers without Bot Management[^1]
			</td>
		</tr>
		<tr>
			<td>
				<b>Type of bots detected</b>
			</td>
			<td>Simple bots, headless browsers, and many sophisticated bots</td>
		</tr>
		<tr>
			<td>
				<b>Actions</b>
			</td>
			<td>Customer chooses whether to allow, block, or challenge</td>
		</tr>
		<tr>
			<td>
				<b>Analytics</b>
			</td>
			<td>
				Dedicated Bot Analytics tool, available in <b>Security Analytics</b>
			</td>
		</tr>
		<tr>
			<td>
				<b>Control</b>
			</td>
			<td>Applied to all traffic across a domain</td>
		</tr>
		<tr>
			<td>
				<b>Additional features</b>
			</td>
			<td>
				<a href="/bots/additional-configurations/block-ai-bots/">Block AI bots</a>, <br/>
				<a href="/bots/additional-configurations/ai-labyrinth/">AI Labyrinth</a>, <br />
				<a href="/bots/additional-configurations/managed-robots-txt/">Instruct AI bot traffic with <code>robots.txt</code></a>, <br />
				<a href="/bots/concepts/bot-score/#bot-groupings">Definitely and Likely automated bots</a>, <br />
				<a href="/bots/concepts/bot/verified-bots/">Verified bots</a>, <br />
				<a href="/bots/additional-configurations/static-resources/">Static resource protection</a>, <br />
				<a href="/bots/troubleshooting/wordpress-loopback-issue/">Optimize for WordPress</a>, <br />
				<a href="/cloudflare-challenges/challenge-types/javascript-detections/">JavaScript Detections</a> 
			</td>
		</tr>
	</tbody>
</table>

[^1]: When users purchase Bot Management for Enterprise, Cloudflare automatically replaces and disables other bot products to prevent overlap.

<Render file="bot-settings-vs-custom-rules" product="bots" />

## How do I get started?

<Render file="plan-get-started" product="bots" />

# Enterprise Bot Management

import { Render } from "~/components";

<Render file="plan-intro" product="bots" />

<Render file="buttons-plan-pages" product="bots" />

<table>
	<thead>
		<tr>
			<th width="25%"></th>
			<th width="30%"></th>
		</tr>
	</thead>
	<tbody>
		<tr>
			<td>
				<b>Plan name</b>
			</td>
			<td>Bot Management for Enterprise</td>
		</tr>
		<tr>
			<td>
				<b>Availability</b>
			</td>
			<td>Added to Enterprise plans by your account team</td>
		</tr>
		<tr>
			<td>
				<b>Enablement</b>
			</td>
			<td>Quick onboarding with help from our Solutions Engineering team</td>
		</tr>
		<tr>
			<td>
				<b>Type of bots detected</b>
			</td>
			<td>
				Simple and sophisticated bots, headless browsers, and domain-specific
				anomalies
			</td>
		</tr>
		<tr>
			<td>
				<b>Actions</b>
			</td>
			<td>
				Customer chooses from several options, including block and various
				challenges
			</td>
		</tr>
		<tr>
			<td>
				<b>Analytics</b>
			</td>
			<td>
				Dedicated Bot Analytics tool, available in <b>Security Analytics</b>
			</td>
		</tr>
		<tr>
			<td>
				<b>Control</b>
			</td>
			<td>
				Ability to restrict by path, IP address, and more. <br /><br />Access to <a href="/bots/concepts/bot-score/">bot score</a>, <a href="/bots/additional-configurations/ja3-ja4-fingerprint/">JA3/JA4 fingerprint</a>, <a href="/bots/concepts/bot-tags/">bot tags</a> fields, and <a href="/bots/additional-configurations/detection-ids/">detection IDs</a>.
			</td>
		</tr>
		<tr>
			<td>
				<b>Additional features</b>
			</td>
			<td>
				<a href="/bots/additional-configurations/block-ai-bots/">Block AI bots</a>, <br/>
				<a href="/bots/additional-configurations/ai-labyrinth/">AI Labyrinth</a>, <br />
				<a href="/bots/additional-configurations/managed-robots-txt/">Instruct AI bot traffic with <code>robots.txt</code></a>, <br />
				<a href="/bots/concepts/bot-score/#bot-groupings">Definitely and Likely automated bots</a>, <br />
				<a href="/bots/concepts/bot/verified-bots/">Verified bots</a>, <br />
				<a href="/bots/additional-configurations/static-resources/">Static resource protection</a>, <br />
				<a href="/bots/troubleshooting/wordpress-loopback-issue/">Optimize for WordPress</a>, <br />
				<a href="/cloudflare-challenges/challenge-types/javascript-detections/">JavaScript Detections</a> 
			</td>
		</tr>
	</tbody>
</table>

:::note

Zones that have [Enterprise Bot Management](/bots/get-started/bot-management/) enabled will not see Bot Fight Mode or Super Bot Fight Mode under **Security** > **Bots**.
:::

## Bot settings vs. custom rules

Bot Management customers have both bot settings (configured in **Security Settings**) and the ability to create custom rules using bot score fields. Start with the bot settings for baseline protection, then add custom rules only when you need additional control.

| Feature | Handled by bot settings | When to use custom rules instead |
| --- | --- | --- |
| Block or challenge definitely automated traffic | No | Path-specific rules, custom thresholds, or combining with other fields |
| Block or challenge likely automated traffic | No | Path-specific rules, custom thresholds, or combining with other fields |
| Allow or block verified bots | No | Granular control by verified bot category |
| Block AI crawlers | Yes | Target individual AI crawlers using detection IDs |
| Protect static resources | No | Exclude static resources from specific rules |
| Optimize for WordPress | No | No |
| Forward bot data to origin | No | Use [Transform Rules](/rules/transform/) or [Snippets](/rules/snippets/) |
| Detection ID targeting | No | Use `cf.bot_management.detection_ids` in [custom rules](/waf/custom-rules/) |
| JA3/JA4 fingerprint rules | No | Use `cf.bot_management.ja3_hash` or `cf.bot_management.ja4` in [custom rules](/waf/custom-rules/) |

For more details on when custom rules are needed, refer to [custom rules](/bots/additional-configurations/custom-rules/).

## How do I get started?

<Render file="plan-get-started" product="bots" />

# Free

import { Render } from "~/components";

<Render file="plan-intro" product="bots" />

<Render file="buttons-plan-pages" product="bots" />

<table>
	<thead>
		<tr>
			<th width="25%"></th>
			<th width="30%"></th>
		</tr>
	</thead>
	<tbody>
		<tr>
			<td>
				<b>Plan name</b>
			</td>
			<td>Bot Fight Mode</td>
		</tr>
		<tr>
			<td>
				<b>Availability</b>
			</td>
			<td>All Free customers</td>
		</tr>
		<tr>
			<td>
				<b>Type of bots detected</b>
			</td>
			<td>Simple bots from cloud hosting providers and headless browsers</td>
		</tr>
		<tr>
			<td>
				<b>Actions</b>
			</td>
			<td>Cloudflare issues a computationally expensive challenge</td>
		</tr>
		<tr>
			<td>
				<b>Control</b>
			</td>
			<td>Applied to all traffic across a domain</td>
		</tr>
		<tr>
			<td>
				<b>Additional features</b>
			</td>
			<td>
				<a href="/bots/additional-configurations/block-ai-bots/">Block AI bots</a>, <br/>
				<a href="/bots/additional-configurations/ai-labyrinth/">AI Labyrinth</a>, <br />
				<a href="/bots/additional-configurations/managed-robots-txt/">Instruct AI bot traffic with <code>robots.txt</code></a>
			</td>
		</tr>
	</tbody>
</table>

## How do I get started?

<Render file="plan-get-started" product="bots" />

# Plans

import { LinkButton, Render } from "~/components";

<Render file="plan-intro" product="bots" />

<LinkButton variant="primary" href="/bots/plans/free/">
	Free
</LinkButton>
<LinkButton variant="primary" href="/bots/plans/pro/">
	Pro
</LinkButton>
<LinkButton variant="primary" href="/bots/plans/biz-and-ent/">
	Business
</LinkButton>
<LinkButton variant="primary" href="/bots/plans/bm-subscription/">
	Bot Management for Enterprise
</LinkButton>

## How do I get started?

<Render file="plan-get-started" product="bots" />

# Pro

import { Render } from "~/components";

<Render file="plan-intro" product="bots" />

<Render file="buttons-plan-pages" product="bots" />

<table>
	<thead>
		<tr>
			<th width="25%"></th>
			<th width="30%"></th>
		</tr>
	</thead>
	<tbody>
		<tr>
			<td>
				<b>Plan name</b>
			</td>
			<td>Super Bot Fight Mode</td>
		</tr>
		<tr>
			<td>
				<b>Availability</b>
			</td>
			<td>All Pro customers</td>
		</tr>
		<tr>
			<td>
				<b>Type of bots detected</b>
			</td>
			<td>Simple bots and headless browsers</td>
		</tr>
		<tr>
			<td>
				<b>Actions</b>
			</td>
			<td>Customer chooses whether to allow, block, or challenge</td>
		</tr>
		<tr>
			<td>
				<b>Analytics</b>
			</td>
			<td>
				Limited analytics available in a <b>Bot Report</b>
			</td>
		</tr>
		<tr>
			<td>
				<b>Control</b>
			</td>
			<td>Applied to all traffic across a domain</td>
		</tr>
		<tr>
			<td>
				<b>Additional features</b>
			</td>
			<td>
				<a href="/bots/additional-configurations/block-ai-bots/">Block AI bots</a>, <br/>
				<a href="/bots/additional-configurations/ai-labyrinth/">AI Labyrinth</a>, <br />
				<a href="/bots/additional-configurations/managed-robots-txt/">Instruct AI bot traffic with <code>robots.txt</code></a>, <br />
				<a href="/bots/concepts/bot-score/#bot-groupings">Definitely automated bots</a>, <br />
				<a href="/bots/concepts/bot/verified-bots/">Verified bots</a>, <br />
				<a href="/bots/additional-configurations/static-resources/">Static resource protection</a>, <br />
				<a href="/bots/troubleshooting/wordpress-loopback-issue/">Optimize for WordPress</a>, <br />
				<a href="/cloudflare-challenges/challenge-types/javascript-detections/">JavaScript Detections</a> 
			</td>
		</tr>
	</tbody>
</table>

<Render file="bot-settings-vs-custom-rules" product="bots" />

## How do I get started?

<Render file="plan-get-started" product="bots" />

# Bot Detection Alerts

import { AvailableNotifications, Steps, DashButton } from "~/components"

Bot alerts inform you when Cloudflare detects spikes in your traffic with any of the following characteristics:

- A global spike in traffic that has a bot score of less than 30.
- An increase in traffic on available dimensions in [Set up a bot detection alert](#set-up-a-bot-detection-alert).
- Filters of your choosing in [Set up a bot detection alert](#set-up-a-bot-detection-alert).

--- 

## Alert types

<AvailableNotifications product="Bots" />

### Set up a bot detection alert

To receive Bot alerts, you must [configure a notification](/notifications/get-started/). All plans can receive notifications through email or webhooks. Business and higher plans can also use PagerDuty.

<Steps>
  1. In the Cloudflare dashboard, go to the **Notifications** page.
  
      <DashButton url="/?to=/:account/notifications" />
  3. Select **Add**.
  4. Select **Bot Management** from the Product list.
  5. Choose one of the available bot detection alerts (depending on whether you want to set up custom filters and/or grouping):
      - Bot Detection Alert
      - Custom Bot Detection Alert
  6. Enter a notification name and (optionally) a description.
  7. Select the domain(s) to monitor for this alert.
  8. Configure a delivery method for the notification. The available delivery methods depend on your Cloudflare plan. For more information, refer to [Cloudflare Notifications](/notifications/).
  9. If you are creating a notification for Custom Bot Detection Alert, define the parameters that will filter the notifications you will receive.
  10. Select **Save**.
</Steps>

---

## Alert logic

The Bot Detection Alert notifies you when Cloudflare detects an abnormal spike to your zone where the [Z-score](https://blog.cloudflare.com/introducing-thresholds-in-security-event-alerting-a-z-score-love-story/) exceeds 3.5 and bot requests exceed 200 per 5 minutes (bot score below 30). A Z-score measures how far a value deviates from the average, so a Z-score above 3.5 indicates a statistically unusual traffic spike.

The Z-score is calculated using a six-hour baseline window and a five-minute observation window.

Bot Detection Alerts are delivered with Cloudflare’s Notifications system via email, webhook, or Pager Duty.

You will not receive duplicate alerts within the same one-hour time frame, except in rare cases where different alert values simultaneously trigger alerts.

In addition to the information above, Custom Bot Detection Alerts allow you to include or exclude certain conditions:

- User-agent
- Hostname
- URI Path
- IP Source Address
- Autonomous System Number (AS Num)
- JA3 Fingerprint
- JA4 Fingerprint
- Bot Detection IDs

You can also choose to group by the following dimensions so that they can be alerted of volumetric anomalies based on:

- JA4 Fingerprint (removes the filter of bot score < 30)
- AS Num
- Bot Detection IDs

:::note
Bot Detection Alerts exclude [verified bots](/bots/concepts/bot/verified-bots/). 
:::

# Bot Management variables

import { Render } from "~/components";

## Ruleset Engine fields

Bot Management provides access to several [fields](/ruleset-engine/rules-language/fields/reference/?field-category=Bots) within the expression builder of Ruleset Engine-based products such as [WAF custom rules](/waf/custom-rules/) and [Cache Rules](/cache/how-to/cache-rules/).

- **Bot Score** (`cf.bot_management.score`): An integer between 1-99 that indicates [Cloudflare's level of certainty](/bots/concepts/bot-score/) that a request comes from a bot.
- **Verified Bot** (`cf.bot_management.verified_bot`): A boolean value that indicates whether a request originates from a Cloudflare allowed bot.

  Cloudflare maintains a large allowlist of good, automated bots (such as Google Search Engine and Pingdom) that perform beneficial tasks. Cloudflare identifies and verifies these bots primarily through reverse DNS validation, ensuring the source IP matches the requesting service.

  We also use additional validation methods, including checking ASN blocks and public lists. If these methods are unavailable, Cloudflare utilizes internal data and machine learning to identify and verify legitimate IP addresses from good bots. Most customers choose to [allow this traffic](/ruleset-engine/rules-language/fields/reference/cf.bot_management.verified_bot/).

- **Serves Static Resource** (`cf.bot_management.static_resource`): An identifier that matches [file extensions](/bots/additional-configurations/static-resources/) for many types of static resources. Use this variable if you send emails that retrieve static images.
- **ja3Hash** (`cf.bot_management.ja3_hash`) and **ja4** (`cf.bot_management.ja4`): A [**JA3/JA4 fingerprint**](/bots/additional-configurations/ja3-ja4-fingerprint/) helps you profile specific SSL/TLS clients across different destination IPs, Ports, and X509 certificates.
- **Bot Detection IDs** (`cf.bot_management.detection_ids`): List of IDs that correlate to the Bot Management heuristic detections made on a request (you can have multiple heuristic detections on the same request).
- **Bot Tags** (`cf.bot_management.tags`): A list of tags associated with bot traffic.
- **Signed Agent** (`cf.bot_management.signed_agent`): A boolean value that indicates whether the request originated from a known agent that self-identifies with Web Bot Auth. Such agents are now classified as [verified bots and agents](/bots/concepts/bot/verified-bots/) labeled as intermediary.
- **Verified Bot Categories** (`cf.verified_bot_category`): A string that allows you to segment your verified bot traffic by its [type and purpose](/bots/concepts/bot/verified-bots/#legacy-categories).

## Workers variables

These variables are also available as part of the [request.cf](/workers/runtime-apis/request/#incomingrequestcfproperties) object via Cloudflare Workers:

- `request.cf.botManagement.score`
- `request.cf.botManagement.verifiedBot`
- `request.cf.botManagement.staticResource`
- `request.cf.botManagement.ja3Hash`
- `request.cf.botManagement.ja4`
- `request.cf.botManagement.jsDetection.passed`
- `request.cf.botManagement.detectionIds`
- `request.cf.botManagement.signedAgent`
- `request.cf.verifiedBotCategory`

## O2O and subrequests

For Orange-to-Orange (O2O) traffic and any related subrequests where Bot Management is in effect, Bot Management fields (including bot score, verified bot, and JA3/JA4) represent the eyeball (end-user) connection to your platform.

Eyeball signals are preserved through the O2O chain, so the fields must be present regardless of which O2O request path you reach.

## Corporate Proxy

The Bot Management Corporate Proxy field contains identified cloud-based corporate proxies and secure web gateways that are Enterprise-only, and provide outbound security services to their clients.

You can access the Corporate Proxy field in [WAF custom rules](/waf/custom-rules/), [Rate limiting rules](/waf/rate-limiting-rules/), or [Workers](/workers/) to provide different security rules for traffic from these sources. You can also exempt them from rules using Bot Management scores.

```txt title="Example"
not cf.bot_management.verified_bot
and not cf.bot_management.static_resource
and not  cf.bot_management.corporate_proxy
and cf.bot_management.score lt 30
```

## Log fields

Once you enable Bot Management, Cloudflare also surfaces bot information in its [HTTP requests log fields](/logs/logpush/logpush-job/datasets/zone/http_requests/):

- BotDetectionIDs
- BotScore
- BotScoreSrc
- BotTags

## Ephemeral IDs

[Ephemeral IDs](/turnstile/additional-configuration/ephemeral-id/) are short-lived device identifiers returned in the [Turnstile Siteverify API](/turnstile/get-started/server-side-validation/) response under `metadata.ephemeral_id`. They are not Ruleset Engine fields and cannot be used in WAF custom rules or Workers directly.

:::note
Ephemeral IDs require **Enterprise Bot Management** with the Turnstile Enterprise add-on, or a standalone **Enterprise Turnstile** subscription. The feature must be enabled by your Cloudflare account team and cannot be self-activated.
:::

Refer to [Ephemeral IDs](/turnstile/additional-configuration/ephemeral-id/) for implementation details and the full enablement process.

# Reference

import { DirectoryListing } from "~/components"

Refer to the following pages for more information on Cloudflare's bot solutions:

<DirectoryListing />

# Machine Learning models

import { Render } from "~/components"

## Enable auto-updates to the Machine Learning models

<Render file="latest-ml-model-enable" product="bots" />

### What will change

Enabling auto-updates moves your traffic onto the model behind Adaptive Intelligence. This model retrains more frequently than fixed, numbered versions were released, so your bot score reflects newly identified attack patterns as the model learns them, rather than only when a new version ships.

If you are on an older, fixed Machine Learning model, you will see a score change to requests scored by the **Machine Learning** source as soon as you enable auto-updates.

### Risks of not updating

If you do not enable auto-updates, your traffic continues to be scored by your current fixed model version. Cloudflare does not maintain or monitor fixed model versions after they are superseded, and scoring accuracy degrades as attack patterns evolve beyond what that version was trained on.

### Model versions and release notes

The following table lists released versions through v9, the final fixed version. Enabling auto-updates moves you off numbered versions entirely, onto Adaptive Intelligence.

| Version | Release Notes                                                                                                                                                                                                                               | Launch Date |
| ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- |
| v1      | First Machine Learning Model released.                                                                                                                                                                                                      | Q1 2019     |
| v2      | Introduced dynamic inter-request features to leverage the Cloudflare network to detect new bots more accurately. <br/><br/>Feedback other Bot Management detection mechanisms to the machine learning model to more accurately detect bots. | Q1 2020     |
| v3      | Fixed accuracy issues under some conditions in the previous version.                                                                                                                                                                        | Q2 2020     |
| v4      | Improved scoring for iOS devices. <br/><br/>Fixed scoring inaccuracy in Firefox builds.                                                                                                                                                     | Q1 2021     |
| v5      | Recalibrated model for the [removal of `_cfduid` cookie](https://blog.cloudflare.com/deprecating-cfduid-cookie/). <br/><br/> Introduced new signals to reduce false negatives.                                                              | Q2 2021     |
| v6      | Significantly improved scoring for native Android application traffic. <br/><br/>Improved scoring on the newest versions of Chromium browsers.                                                                                              | Q1 2022     |
| v7      | Increased recognition of distributed botnets. <br/><br/>Improved HTTP/3 scoring.                                                                                                                                                            | Q1 2024     |
| v8      | Improved detection of residential proxies. <br/><br/>Increased weight on network level traffic characteristics.                                                                                                                             | Q2 2024     |
| v9      | Improved model consistency and model efficacy against randomization attack techniques | Q2 2025     |

# Sample terms

Cloudflare recommends that customers consider updating their Terms of Service to address bots specifically related to Artificial Intelligence (AI) training and data scraping. The text below provides an informational example of the kind of language that could be added to a website's terms of use.

> **Artificial Intelligence Restriction**
>
> You may not use automated bots to access, scan, scrape, data mine, copy, or use the materials or content on this website for developing, training, fine-tuning, or otherwise contributing to or improving a machine learning model or artificial intelligence (AI) system or the operation thereof, unless your bot's user agent is (I) explicitly permitted ("allowed") to do so in this website's `robots.txt` file and (II) solely used to identify bots used for AI purposes (i.e., this provision does not apply to user agents that are used for multiple purposes, such as search engine indexing and AI purposes).

:::caution[Disclaimer]

This language is provided for informational purposes only. It does not constitute legal advice, nor does it guarantee any specific outcome. 

This is an illustrative example of language that can be included in a website's terms to put AI providers on notice that they are not authorized to use automated means to scrape content from your website for purposes of training or otherwise contributing to their AI models or systems, unless you have expressly permitted them to do so in your `robots.txt` file. 
:::

# Bot verification methods

import { DirectoryListing } from "~/components"

Refer to the following pages for more information on Cloudflare's validation methods for [verified bots and agents](/bots/concepts/bot/verified-bots/).

<DirectoryListing />

# IP validation

import { GlossaryTooltip, Steps } from "~/components"

The IP validation method aims to identify all of the IP addresses that a bot may use to send requests. IP validation is only used as a verification method for [verified bots](/bots/concepts/bot/verified-bots/).

Cloudflare can achieve this in two ways:

- **Using IP list provided by the bot owner**: The bot owner can host a public list of IP ranges (for example, [Googlebot's list](https://developers.google.com/static/search/apis/ipranges/googlebot.json)). Cloudflare fetches and uses this list directly for validation.
- **Using Domain-based reverse DNS**: The bot owner can provide a domain (or set of domains) that their bot requests originate from. Cloudflare collects the IP addresses observed in the requests with the bot's user agent, and performs reverse DNS lookups. If the reverse DNS of an IP resolves to one of the provided domains, Cloudflare considers it valid and stores it.

## Public IP List

To verify a bot using a public IP list, you need to provide:

- A fixed and limited set of IP addresses, which can be verified via publicly accessible plain-text, `JSON`, or `CSV`.
- IP addresses used solely by the bot owner.
- A user-agent match pattern.

## Reverse DNS

To verify a bot using reverse DNS, you need to provide:

- A list of domain suffixes to validate DNS records.
- IP addresses should have PTR records set correctly.
- A user-agent match pattern.

## Generic user-agents

User-agent patterns that match generic user-agents will be rejected by the Verified Bots API. When you add a user-agent pattern that is considered very common to the Verified Bot form, you may encounter an error message that will prompt you to correct the user-agent before you can submit again.

Generic user-agents include:

- `Dart`
- `Go-http-client`
- `GuzzleHttp`
- `Google Chrome`
- `Mozilla Firefox`
- `Safari`
- `Nessus`
- `Websocket++`
- `cloudflare-go`
- `fasthttp`
- `got`
- `nginx-ssl early hints`
- `node`
- `node-fetch`
- `okhttp`
- `python-requests`
- `uTorrent`

# Web Bot Auth

import { GlossaryTooltip, Steps } from "~/components";

Web Bot Auth is an authentication method that leverages cryptographic signatures in HTTP messages to verify that a request comes from an automated bot. Web Bot Auth is used as a verification method for [verified bots and agents](/bots/concepts/bot/verified-bots/).

It relies on IETF drafts: a [directory draft](https://datatracker.ietf.org/doc/html/draft-meunier-http-message-signatures-directory-03) allowing the crawler to share their public keys, and a [protocol draft](https://datatracker.ietf.org/doc/html/draft-meunier-web-bot-auth-architecture-02) defining how these keys should be used to attach the crawler's identity to HTTP requests.

This documentation goes over specific integration within Cloudflare.

## 1. Generate a valid signing key

You need to generate a signing key which will be used to authenticate your bot's requests.

<Steps>
1. Generate a unique [Ed25519](https://ed25519.cr.yp.to/) private key to sign your requests. This example uses the [OpenSSL](https://openssl-library.org/) `genpkey` command:
    :::note 
    Cloudflare supports Ed25519 key algorithm.
    :::

    ```sh
    openssl genpkey -algorithm ed25519 -out private-key.pem
    ```
2. Extract your public key.

   ```sh
   openssl pkey -in private-key.pem -pubout -out public-key.pem
   ```
3. Convert the public key to JSON Web Key (JWK) using a tool of your choice. This example uses [`jwker`](https://github.com/jphastings/jwker) command line application.
   ```sh
   go install github.com/jphastings/jwker/cmd/jwker@latest
   jwker public-key.pem public-key.jwk
   ```
</Steps>

By following these steps, you have generated a private key and a public key, then converted the public key to a JWK.

:::note
You can also [generate a JavaScript key using WebCrypto API](https://developer.mozilla.org/en-US/docs/Web/API/SubtleCrypto/generateKey), which will produce a key in the correct JWK format.

Many existing [JWK libraries](https://jwt.io/libraries) support WebCrypto API for generating JavaScript key.
:::

## 2. Host a key directory

You need to host a key directory which creates a way for your bot to authenticate its requests to Cloudflare.
This directory should follow the definition from [draft-meunier-http-message-signatures-directory-03](https://datatracker.ietf.org/doc/html/draft-meunier-http-message-signatures-directory-03).

<Steps>
1. Host a key directory at `/.well-known/http-message-signatures-directory` (note that this is a requirement). This key directory should serve a JSON Web Key Set (JWKS) including the public key derived from your signing key.
2. Serve the web page over HTTPS (not HTTP).
3. [Calculate the base64 URL-encoded JWK thumbprint](https://www.rfc-editor.org/rfc/rfc8037.html#appendix-A.3) associated with your Ed25519 public key.
4. Sign your HTTP response using the HTTP message signature specification by attaching one signature per key in your key directory. This ensures no one else can mirror your directory and attempt to register on your behalf. Your response must include the following headers:
   - `Content-Type`: This header must have the value `application/http-message-signatures-directory+json`.
   - `Signature`: Construct a [`Signature` header](https://www.rfc-editor.org/rfc/rfc9421#name-the-signature-http-field) over your chosen components.
   - `Signature-Input`: Construct a [`Signature-Input` header](https://www.rfc-editor.org/rfc/rfc9421#name-the-signature-input-http-fi) over your chosen components. The header must meet the following requirements.
     | Required component / parameter | Requirement                                                                                                                                                                                       |
     | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
     | `tag`                          | This should be equal to `http-message-signatures-directory`.                                                                                                                                      |
     | `keyid`                        | JWK thumbprint of the corresponding key in your directory.                                                                                                                                        |
     | `created`                      | This should be equal to a `Unix` timestamp associated with when the message was sent by your application.                                                                                         |
     | `expires`                      | This should be equal to a `Unix` timestamp associated with when Cloudflare should no longer attempt to verify the message.                                                                        |
     | `@authority`                   | This should be equal to the value of the Host header sent by the request. You should set the [`req` component parameter](https://datatracker.ietf.org/doc/html/rfc9421#content-request-response). |

   The following example shows the annotated request and response with required headers against `https://example.com`. The value of `Signature` here is purely for illustrative purposes, and not the actual generated signature.
   ```txt
   GET /.well-known/http-message-signatures-directory HTTP/1.1
   Host: example.com
   Accept: application/http-message-signatures-directory+json

   HTTP/1.1 200 OK
   Content-Type: application/http-message-signatures-directory+json
   Signature: sig1=:TD5arhV1ved6xtx63cUIFCMONT248cpDeVUAljLgkdozbjMNpJGr/WAx4PzHj+WeG0xMHQF1BOdFLDsfjdjvBA==:
   Signature-Input: sig1=("@authority";req);alg="ed25519";keyid="poqkLGiymh_W0uP6PZFw-dvez3QJT5SolqXBCW38r0U";nonce="ZO3/XMEZjrvSnLtAP9M7jK0WGQf3J+pbmQRUpKDhF9/jsNCWqUh2sq+TH4WTX3/GpNoSZUa8eNWMKqxWp2/c2g==";tag="http-message-signatures-directory";created=1750105829;expires=1750105839
   Cache-Control: max-age=86400
   {
     "keys": [{
       "kty": "OKP",
       "crv": "Ed25519",
       "x": "JrQLj5P_89iXES9-vFgrIy29clF9CC_oPPsw3c5D0bs", // Base64 URL-encoded public key, with no padding
     }]
   }
   ```
</Steps>

:::note
This URL serves a standard JSON Web Key Set. Besides `x`, `crv`, and `kty`, you can include other standard JSON Web Key parameters, and you may publish non-Ed25519 keys as well. Multiple Ed25519 keys are supported. Only those for which you provide a signature in the above format are going to be used.

Cloudflare will ignore all other key types and key parameters except those containing `kty`, `crv`, and `x` formatted above. Do not include information that would leak your private key, such as the `d` parameter.
:::

You can use the Cloudflare-developed [`http-signature-directory` CLI tool](https://crates.io/crates/http-signature-directory) to assist you in validating your directory.

## 3. Register your bot and key directory

You need to register your bot and its key directory to add your bot to the list of verified bots.

<Steps>
1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com/), and select your account and domain.
2. Go to **Manage Account** > **Configurations**.
3. Go to the **Bot Submission Form** tab.
4. For **Verification Method**: select **Request Signature**.
5. For **Validation Instructions**: enter the URL of your key directory. You can additionally supply User Agents values (and their match patterns) that will be sent by your bot.
6. Select **Submit**.
</Steps>

Cloudflare accepts all valid Ed25519 keys found in your key directory. In the event a key already exists in Cloudflare's registered database, Cloudflare will work with you to supply a new key, or rotate your existing key.

You can track the status of your registration in the Cloudflare dashboard under [BotBase > Submission history](https://dash.cloudflare.com/?to=/:account/application-security/botbase/history).

After successful verification, you will be able to send verified requests.

## 4. (After verification) Sign your requests

After your bot has been successfully verified, your bot is ready to sign its requests. The signature protocol is defined in [draft-meunier-web-bot-auth-architecture-02](https://datatracker.ietf.org/doc/html/draft-meunier-web-bot-auth-architecture-02)

### 4.1. Choose a set of components to sign

Choose a set of components to sign.

A component is either an HTTP header, or any [derived components](https://www.rfc-editor.org/rfc/rfc9421#name-derived-components) in the HTTP Message Signatures specification. Cloudflare recommends the following:

- Choose at least the `@authority` derived component, which represents the domain you are sending requests to. For example, a request to `https://example.com` will be interpreted to have an `@authority` of `example.com`.
- Use components that only contain ASCII values. HTTP Message Signature specification disallows non-ASCII characters, which will result in failure to validate your bot's requests.

:::note[Use components with only ASCII values]
Cloudflare currently does not support `bs` or `sf` parameter designed to serialize non-ASCII values into ASCII equivalents.
:::

:::caution[`Content-Digest` header]
If you wish to sign your [message content](https://www.rfc-editor.org/rfc/rfc9421#name-message-content) using a `Content-Digest` header, note that you should only do so if there is zero risk of a message being altered on the way to Cloudflare.

For example, if the message is unencrypted and proxied to Cloudflare, you should not use `Content-Digest`.
:::

### 4.2. Calculate the JWK thumbprint

[Calculate the base64 URL-encoded JWK thumbprint](https://www.rfc-editor.org/rfc/rfc8037.html#appendix-A.3) from the public key you registered with Cloudflare.

### 4.3. Construct the required headers

Construct the three required headers for Web Bot Auth.

#### `Signature-Input` header

Construct a [`Signature-Input` header](https://www.rfc-editor.org/rfc/rfc9421#name-the-signature-input-http-fi) over your chosen components. The header must meet the following requirements.

| Required component parameter | Requirement                                                                                                                                                                                                                                               |
| ---------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `tag`                        | This should be equal to `web-bot-auth`.                                                                                                                                                                                                                   |
| `keyid`                      | This should be equal to the thumbprint computed in step 2.                                                                                                                                                                                                |
| `created`                    | This should be equal to a `Unix` timestamp associated with when the message was sent by your application.                                                                                                                                                 |
| `expires`                    | This should be equal to a `Unix` timestamp associated with when Cloudflare should no longer attempt to verify the message. A short `expires` reduces the likelihood of replay attacks, and Cloudflare recommends choosing suitable short-lived intervals. |

:::tip[`nonce`]
The `nonce` parameter allows you to supply a `nonce` to prevent attackers from replaying past messages against a server.

While Cloudflare recommends including it, there is currently no `nonce` validation, nor does Cloudflare guard against replay attacks using a database of seen `nonces`.

Instead, Cloudflare recommends short `expires` as a protection against replay attacks. A minute is often sufficient.
:::

#### `Signature` header

Construct a [`Signature` header](https://www.rfc-editor.org/rfc/rfc9421#name-the-signature-http-field) over your chosen components.

#### `Signature-Agent` header

Construct a [`Signature-Agent` header](https://datatracker.ietf.org/doc/html/draft-meunier-http-message-signatures-directory-03#name-header-field-definition) that points to your key directory. Cloudflare implements the `Signature-Agent` format from `draft-meunier-http-message-signatures-directory-03`, where the header value is a structured string such as `"https://signature-agent.test"`.

Cloudflare will fail to verify a message if:

- The message includes a `Signature-Agent` header that is not an `https://`.
- The message includes a valid URI but does not enclose it in double quotes. This is due to Signature-Agent being a structured field.
- The message uses the dictionary form from later drafts, such as `sig2="https://signature-agent.test"`.
- The message has a valid `Signature-Agent` header, but does not include it in the component list in `Signature-Input`.

### 4.4. Add the headers to your bot's requests

Attach these three headers to your bot's requests.

An example request may look like this:

```txt
Signature-Agent: "https://signature-agent.test"
Signature-Input: sig2=("@authority" "signature-agent")
 ;created=1735689600
 ;keyid="poqkLGiymh_W0uP6PZFw-dvez3QJT5SolqXBCW38r0U"
 ;alg="ed25519"
 ;expires=1735693200
 ;nonce="e8N7S2MFd/qrd6T2R3tdfAuuANngKI7LFtKYI/vowzk4lAZYadIX6wW25MwG7DCT9RUKAJ0qVkU0mEeLElW1qg=="
 ;tag="web-bot-auth"
Signature: sig2=:jdq0SqOwHdyHr9+r5jw3iYZH6aNGKijYp/EstF4RQTQdi5N5YYKrD+mCT1HA1nZDsi6nJKuHxUi/5Syp3rLWBA==:
```

:::note
You can test how Cloudflare interprets your signed requests against https://crawltest.com/cdn-cgi/web-bot-auth. This endpoint returns an HTTP `401` if your message is formatted correctly but your key is unknown, an HTTP `200` if the key is known and your message is verified, and an HTTP `400` otherwise. You may also see an HTTP `401` if your key is known but the message failed to verify.
:::

---

## Transitive trust and the `Forwarded` header

An agent that reaches your site is often not operated by the company that built it. A platform can run automations on behalf of many different end users, so the operator and the end user are not the same party. Cloudflare refers to this chain — website owner → bot operator → end user — as **transitive trust**.

To carry an operator's identity through that chain, Cloudflare is experimenting with the `Forwarded` header defined in [RFC 7239](https://www.rfc-editor.org/info/rfc7239). This works like `X-Forwarded-For` does for IP addresses: a preference to allow an operator holds whether that operator reaches you directly or through intermediaries that Cloudflare trusts.

The operator is identified with the `for` parameter:

```txt
Forwarded: for="openai"
```

The header can also carry the [`content-use`](/bots/additional-configurations/managed-robots-txt/#content-use-signal) value that the operator commits to for the content it accesses:

```txt
Forwarded: for="openai";use="reference"
```

:::note
Transitive trust and the `Forwarded` header are experimental and may change.
:::

---

## Limitations

Cloudflare's implementation of Web Bot Auth does not support every component and parameter defined in IETF RFC 9421. If you include any of the following in your request's Signature-Input header, verification will fail.

- `@query-params`: Cloudflare recommends signing the whole query using the `@query` component instead of signing an individual parameter.
- `@status`: This is not possible to include in the request path.

The following component parameters defined in IETF RFC 9421 are not supported, and Cloudflare will fail to verify a message if they are included:

- `sf` (for HTTP header fields)
- `bs` (for HTTP header fields)
- `key` (for HTTP header fields)
- `req` (for HTTP header fields or derived components)
- `name` (for `@query-param` support - this requires `@query-param` support)

---

## Troubleshooting

### Failed message validation

If your message is failing validation, the cause(s) may include:

- Ensure you have a [`Signature-Agent` header](/bots/reference/bot-verification/web-bot-auth/#signature-agent-header), and that its value is in double-quotes.
- Ensure your [`Signature-Agent` header](/bots/reference/bot-verification/web-bot-auth/#signature-agent-header) uses a structured string, not a dictionary.
- Ensure you include `signature-agent` in the component list in your [`Signature-Input` header](/bots/reference/bot-verification/web-bot-auth/#signature-agent-header).
- Ensure your `expires` timestamp is not too short, such that, by the time it arrives at Cloudflare servers, it has already expired. A minute is often sufficient.
- Ensure you are not signing components containing non-ASCII values, or on the unsupported list.

### Use HTTP message signatures / Web Bot Auth on a zone without Cloudflare's verification

If you wish to use HTTP Message Signatures (Web Bot Auth) for your own origin processing and do not want Cloudflare's verification to intervene or populate the `cf.bot_management.verified_bot` field, you can request that the Cloudflare verification feature be disabled for your zone.

To disable Web Bot Auth verification, contact [Cloudflare Support](/support/contacting-cloudflare-support/).

Disabling this feature means that Cloudflare will not validate incoming signatures. Verified bots will then fall back to other methods (such as reverse DNS validation) to determine if traffic is legitimate.

## Additional resources

You may wish to refer to the following resources.

- Cloudflare blog: [Message Signatures are now part of our Verified Bots Program](https://blog.cloudflare.com/verified-bots-with-cryptography).
- Cloudflare blog: [Forget IPs: using cryptography to verify bot and agent traffic](https://blog.cloudflare.com/web-bot-auth/).
- Cloudflare's [`web-bot-auth` library in Rust](https://crates.io/crates/web-bot-auth).
- Cloudflare's [`web-bot-auth` npm package in Typescript](https://www.npmjs.com/package/web-bot-auth).

# Bot Management skips

import { GlossaryTooltip } from "~/components"

There are instances in which Bot Management does not run and certain fields, such as the [JA3/JA4 field](/bots/additional-configurations/ja3-ja4-fingerprint/), are not populated because it has been determined that running Bot Management would not be necessary.

Refer to <GlossaryTooltip term="bot score" link="/bots/concepts/bot-score/#not-computed">bot scores</GlossaryTooltip> for more information about why a request is not scored.

## Common reasons for Bot Management to not score a request

### Requests to internal endpoints

Requests such as `/cdn-cgi/` are handled individually and will never receive a Bot Management score. Email Obfuscation, Web Analytics, Trace Requests, Challenge Pages, and JavaScript Detections do not receive bot scores. Refer to the table below for some examples of internal endpoints.

| Route                                                             |
| ----------------------------------------------------------------- |
| `/cdn-cgi/rum`                                                    |
| `/cdn-cgi/script_monitor/report`                                  |
| `/cdn-cgi/trace`                                                  |
| `/cdn-cgi/challenge-platform/…`                                   |
| `/cdn-cgi/scripts/5c5dd728/cloudflare-static/email-decode.min.js` |

### Purge requests

All HTTP purge requests will not receive a bot score.

### Early hints cache requests

Early hints cache requests will not receive a bot score.

# Handle False Positives from Bot Fight Mode or Super Bot Fight Mode

import { Render } from "~/components";

[Bot Fight Mode (BFM)](/bots/get-started/bot-fight-mode/) and [Super Bot Fight Mode (SBFM)](/bots/get-started/bot-fight-mode/) are designed to stop active attacks quickly. Due to their aggressive nature, false positives can occur where legitimate human or automated traffic is incorrectly challenged or blocked.

When dealing with false positives, consider the following key differences and solutions:

- Bot Fight Mode has limited control. You cannot bypass or skip Bot Fight Mode using the _Skip_ action in WAF custom rules or using Page Rules. Bot Fight Mode will be disabled if there are any IP Access rules present. If you turned on BFM during an attack, and the attack has subsided, we recommend either disabling the feature using IP Access rules to bypass BFM, or looking at [Bot Management for Enterprise](/bots/plans/bm-subscription/), which gives you the ability to precisely customize your security threshold and create exception rules as needed.
- Super Bot Fight Mode can be bypassed with IP Access _Allow_ action rules. You can use the _Skip_ action in [WAF custom rules](/waf/custom-rules/skip/) to specify where Super Bot Fight Mode should not run.

<Render file="flexible-sbfm" product="bots" />

You cannot bypass or skip Bot Fight Mode using the _Skip_ action in WAF custom rules or using Page Rules. _Skip_, _Bypass_, and _Allow_ actions apply to rules or rulesets running on the [Ruleset Engine](/ruleset-engine/). While Super Bot Fight Mode rules are implemented in the Ruleset Engine, Bot Fight Mode checks are not. This is why you can skip Super Bot Fight Mode, but not Bot Fight Mode. If you need to skip Bot Fight Mode, consider using [Super Bot Fight Mode](/bots/get-started/super-bot-fight-mode/).

Bot Fight Mode can still trigger if you have IP Access rules, but it cannot trigger if an IP Access rule matches the request. For example, the IP Access rule matches the connecting IP.

If you encounter persistent false positives, you can [disable the feature in the Cloudflare dashboard](/bots/get-started/bot-fight-mode/#disable-bot-fight-mode).

# Troubleshooting

import { DirectoryListing } from "~/components"

Refer to the following pages to troubleshoot issues with Cloudflare's bot solutions:

<DirectoryListing />

# Super Bot Fight Mode for WordPress

import { Steps, DashButton } from "~/components";

When users attempt to run diagnostics in the Site Status page for WordPress installations, loopback issues arise when our bot detection services block them.

WordPress relies on making loopback requests to monitor and occasionally administer its websites. Customers can opt-in to optimize Super Bot Fight Mode for WordPress. If this feature is enabled, automated loopback requests made by your WordPress site will be authorized even when Super Bot Fight Mode blocks other bots.

:::note
Loopback requests may also be blocked by [I’m Under Attack mode](/fundamentals/reference/under-attack-mode/) or certain [WAF custom rules](/waf/custom-rules/).
:::

## Enable Optimize for WordPress

<Steps>
  1. In the Cloudflare dashboard, go to the **Security Settings** page.

		<DashButton url="/?to=/:account/:zone/security/settings" />
  2. Filter by **Bot traffic**.
  3. Go to **Super Bot Fight Mode**.
  4. Under **Configurations**, select the edit icon for **Optimize for WordPress** and turn it on.
</Steps>

## Availability

This feature is available for all Super Bot Fight Mode customers.

# Delay action

import { TypeScriptExample } from "~/components";

Customers with a Bot Management and a [Workers](/workers/) subscription can use the template below to introduce a delay to requests that are likely from bots.

The template sets a minimum and maximum delay, and delays requests where the bot score is less than 30 and the URI path starts with `/exampleURI`.

<TypeScriptExample>

```ts title="Workers template"
// Configurable Variables
const PATH_START = '/exampleURI';
const DELAY_FROM = 5; // in seconds
const DELAY_TO = 10; // in seconds

export default {
  async fetch(request, env, ctx): Promise<Response> {
    const url = new URL(request.url);
    const botScore = request.cf.botManagement.score

    if (url.pathname.startsWith(PATH_START) && botScore < 30) {
      // Random delay between DELAY_FROM and DELAY_TO seconds
      const delay = Math.floor(Math.random() * (DELAY_TO - DELAY_FROM + 1)) + DELAY_FROM;
      await new Promise(resolve => setTimeout(resolve, delay * 1000));

      // Fetch the original request
      return fetch(request);
    }

    // Fetch the original request without delay
    return fetch(request);
  },
} satisfies ExportedHandler<Env>;
```

</TypeScriptExample>

# Workers templates

import { DirectoryListing } from "~/components"

Refer to the templates below to integrate Bot Management with [Cloudflare Workers](/workers/):

<DirectoryListing />