Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 8 additions & 1 deletion src/content/docs/api-shield/index.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,14 @@ Identify and address your API vulnerabilities.

## Why care about API security?

<Render file="why-care" product="api-shield" />
APIs have become the [backbone of popular web services](https://blog.postman.com/intro-to-apis-history-of-apis/), helping the Internet become more accessible and useful.

As APIs have become more prevalent, however, so have their problems:

- Many companies have [thousands of APIs](/api-shield/security/api-discovery/), including ones they do not even know about.
- To support a large base of users, many APIs are protected by a negative security model that makes them vulnerable to credential-stuffing attacks and automated scanning tools.
- With so many endpoints and users, it’s difficult to recognize brute-force attacks against [specific endpoints](/api-shield/security/volumetric-abuse-detection/).
- Sophisticated attacks are even harder to recognize, often because even development teams are unaware of common and uncommon [usage patterns](/api-shield/security/sequence-analytics/).

Refer to the [Get started](/api-shield/get-started/) guide to set up API Shield.

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ sidebar:

---

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

API Shield Routing enables customers to create a unified external-facing API that routes requests to different back-end services that may have different paths and hosts than the existing zone and DNS configuration.

Expand All @@ -18,15 +18,62 @@ The term **Source Endpoint** refers to the endpoint managed by API Shield in End

## Process

<Render file="source-endpoints" />

You must add Source Endpoints to Endpoint Management through established methods, including [uploading a schema](/api-shield/security/schema-validation/#add-validation-by-uploading-a-schema), via [API Discovery](/api-shield/security/api-discovery/), or by [adding manually](/api-shield/management-and-monitoring/#add-endpoints-manually), before creating a route.

To create a route, you will need the operation ID of the Source Endpoint. To find the operation ID in the dashboard:

<Tabs syncKey="dashNewNav">
<TabItem label="Old dashboard">
<Steps>
1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com/), and select your account and domain.
2. Select **Security** > **API Shield**.
3. Filter the endpoints to find your **Source Endpoint**.
4. Expand the row for your Source Endpoint and note the **operation ID** field.
5. Select the copy icon to copy the operation ID to your clipboard.
</Steps>
</TabItem>
<TabItem label="New dashboard" icon="rocket">
<Steps>
1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com/login), and select your account and domain.
2. Select **Security** > **Web assets**.
3. Filter the endpoints to find your **Source Endpoint**.
4. Expand the row for your Source Endpoint and note the **operation ID** field.
5. Select the copy icon to copy the operation ID to your clipboard.
</Steps>
</TabItem>
</Tabs>

Once your Source Endpoints are added to Endpoint Management, use the following steps to create and verify routes on any given operation ID:

### Create a route

<Render file="routing" />
<Tabs syncKey="dashNewNav">
<TabItem label="Old dashboard">
<Steps>
1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com/), and select your account and domain.
2. Go to **Security** > **API Shield**.
3. In **Endpoint Management**, select an existing endpoint and expand its details.
4. Under **Routing**, select **Create route**.
5. Enter the target URL or IP address to route your endpoint to.
6. Select **Deploy route**.
</Steps>
</TabItem>
<TabItem label="New dashboard" icon="rocket">
<Steps>
1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com/login), and select your account and domain.
2. Go to **Security** > **Web assets**.
3. In **Endpoints**, select an existing endpoint and expand its details.
4. Under **Routing**, select **Create route**.
5. Enter the target URL or IP address to route your endpoint to.
6. Select **Deploy route**.
</Steps>
</TabItem>
</Tabs>

<Render file="routing-path-variables" />
:::note
You can reorder path variables if they are present. For example, you can route `/api/{var1}/users/{var2}` to `/{var2}/users/{var1}`. Segments of the path that are not variables may be added or omitted entirely.
:::

You can also edit or delete a route by selecting **Edit route** on an existing route.

Expand All @@ -47,4 +94,8 @@ API Shield Routing is currently in an open beta and is only available for Enterp

## Limitations

<Render file="routing-limitations" />
The Target Endpoint cannot be routed to a Worker if the route is to the same zone.

You cannot change the method of a request. For example, a `GET` Source Endpoint will always send a `GET` request to the Target Endpoint.

You must use all of the variables in the Target Endpoint that appear in the Source Endpoint. For example, routing `/api/{var1}/users/{var2}` to `/api/users/{var2}` is not allowed and will result in an error since `{var1}` is present in the Source Endpoint but not in the Target Endpoint.
Original file line number Diff line number Diff line change
Expand Up @@ -48,7 +48,9 @@ Use managed labels to identify endpoints by use case. Cloudflare may automatical
`cf-rss-feed`: Add this label to endpoints that expect traffic from RSS clients.

:::note
<Render file="rss-labels" product="bots" />
[Bot Fight Mode](/bots/get-started/bot-fight-mode/) will not block requests to endpoints labeled as `cf-rss-feed`.

[Super Bot Fight Mode rules](/bots/get-started/super-bot-fight-mode/#ruleset-engine) will not match or challenge requests labeled as `cf-rss-feed`.
:::

### Risk labels
Expand Down
2 changes: 1 addition & 1 deletion src/content/docs/api-shield/security/api-discovery.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -43,7 +43,7 @@ jp-api.example.com/api/v1/users/{var1}

We will consolidate to `{hostVar1}.example.com/api/v1/users/{var1}`.

<Render file="blog-post" />
For more technical details, see our [blog post](https://blog.cloudflare.com/ml-api-discovery-and-schema-learning/).

### Inbox view

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -16,10 +16,10 @@ To enable [AI Labyrinth](/bots/additional-configurations/ai-labyrinth):
<Tabs syncKey="dashNewNav">
<TabItem label="Old dashboard">
<Steps>
<Render
file="ai-labyrinth-enable"
params={{ one: "Bot Fight Mode" }}
/>
1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com/), and select your account and domain.
2. Go to **Security** > **Bots**.
3. Select **Configure Bot Fight Mode**.
4. Enable **AI Labyrinth**.
</Steps>
</TabItem>
<TabItem label="New dashboard" icon="rocket">
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ sidebar:

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

<Render file="detection-ids" />
Detection IDs are static rules used to detect predictable bot behavior with no overlap with human traffic. Detection IDs refer to the precise [detection](/bots/concepts/bot-detection-engines/) used to identify a bot, which could be from heuristics, verified bot detections, or anomaly detections. For example, a detection ID can identify if you sent your headers in a different order than what was expected of your browser.

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.

Expand Down Expand Up @@ -101,7 +101,13 @@ and not any(cf.bot_management.detection_ids[*] in {3355446 12577893})

## Account takeover detections

<Render file="account-takeover-detections" />
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/).

| Detection ID | Description |
| ------------ | ---------------------------------------- |
| `201326592` | Observes all login failures to the zone. |
| `201326593` | Observes all login traffic 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 2 and [anomaly detection](/bots/concepts/bot-detection-engines/#anomaly-detection-enterprise) as its score source. |

### Challenges for account takeover detections

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -8,9 +8,9 @@ sidebar:

import { Render } from "~/components"

<Render file="ja3-fingerprint" />
[**JA3**](https://github.com/salesforce/ja3) and [**JA4**](https://github.com/FoxIO-LLC/ja4) **fingerprints** help you profile specific SSL/TLS clients across different destination IPs, Ports, and X509 certificates.

<Render file="ja4-fingerprint" />
JA4 fingerprint adds new functionality by sorting ClientHello extensions and reducing the total number of unique fingerprints for modern browsers.

:::note

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -50,10 +50,10 @@ To implement a `robots.txt` file on your domain:
<Tabs syncKey="dashNewNav">
<TabItem label="Old dashboard">
<Steps>
<Render
file="enable-managed-robots-txt"
params={{ one: "Bot Fight Mode" }}
/>
1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com/), and select your account and domain.
2. Go to **Security** > **Bots**.
3. Select **Configure Bot Fight Mode**.
4. Turn **Manage bot traffic with robots.txt** on.
</Steps>
</TabItem>
<TabItem label="New dashboard" icon="rocket">
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -46,10 +46,12 @@ The **Static Resource Protection** setting will only activate if at least one of

## Bot Management for Enterprise

<Render file="static-resources-bm" /> <br/>
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?

<Render file="static-resources-list" />
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`
38 changes: 33 additions & 5 deletions src/content/docs/bots/concepts/bot-score.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,9 @@ sidebar:

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

<Render file="bot-score-definition" />
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.

Bot scores are available to be used in rule expressions and with Workers to customize application behavior. For more details, refer to [Bot Management variables](/bots/reference/bot-management-variables/).

Expand All @@ -20,7 +22,13 @@ Granular bot scores are only available to Enterprise customers who have purchase

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

<Render file="bot-groupings" />
| 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

Expand All @@ -34,15 +42,35 @@ Bot scores are not computed for requests to paths that are handled by Cloudflare
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/).
:::

<Render file="bm-bot-detection-engines" />
### Heuristics

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

The Heuristics engine immediately gives automated requests a score of 1.

### Machine learning

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

The ML engine produces scores 2 through 99.

### Anomaly detection

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

### JavaScript detections

<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

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

### Not computed

<Render file="bots-nc" />
A bot score of 0 means Bot Management did not run on the request. Cloudflare does not run Bot Management on internal service requests that Bot Management has no interest in blocking.

### Notes on detection

Expand Down
18 changes: 15 additions & 3 deletions src/content/docs/bots/concepts/bot-tags.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -7,9 +7,9 @@ sidebar:

---

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

<Render file="bot-tags" />
<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.

Expand All @@ -22,7 +22,19 @@ Bot tags are only available to Enterprise customers who have purchased Bot Manag

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).

<Render file="bot-tags-values" />
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

## Enable bot tags

Expand Down
23 changes: 21 additions & 2 deletions src/content/docs/bots/concepts/bot/index.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ learning_center:

import { Render } from "~/components";

<Render file="what-is-a-bot" />
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).

Expand All @@ -36,7 +36,26 @@ You can opt into a managed rule that will block bots that we categorize as artif

### Which bots are blocked

<Render file="list-ai-bots" />
When you enable this feature, Cloudflare will block the following bots:

- `Amazonbot` (Amazon)
- `Applebot` (Apple)
- `Bytespider` (ByteDance)
- `ClaudeBot` (Anthropic)
- `DuckAssistBot` (DuckDuckGo)
- `Google-CloudVertexBot` (Google)
- `GoogleOther` (Google)
- `GPTBot` (OpenAI)
- `Meta-ExternalAgent` (Meta)
- `PetalBot` (Huawei)
- `TikTokSpider` (ByteDance)
- `CCBot` (Common Crawl)

In addition to this list, [verified bots](https://radar.cloudflare.com/bots#verified-bots) that are classified in AI-related categories such as `AI Crawler` or an `Archiver`, as well as a number of unverified bots that behave similarly, are included in the rule. This rule does not include verified bots that fall into the `Search Engine` categories.

These categories, and the bots classified in these categories, may change from time to time.

If you are a bot operator and feel your bot may have been incorrectly categorized, [add your bot to the list of verified bots](https://dash.cloudflare.com/?to=/:account/configurations/verified-bots).

### How it works

Expand Down
27 changes: 25 additions & 2 deletions src/content/docs/bots/get-started/bot-fight-mode.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -11,15 +11,38 @@ head:

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

<Render file="bot-fight-mode-definition" />
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 in response to these bots
- Notifies [Bandwidth Alliance](https://cloudflare.com/bandwidth-alliance/) partners (if applicable) to disable bots

## Considerations

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

## Enable Bot Fight Mode

<Render file="bot-fight-mode-enable" />
To start using Bot Fight Mode:

<Tabs syncKey="dashNewNav">
<TabItem label="Old dashboard">
<Steps>
1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com/login), and select your account and domain.
2. Go to **Security** > **Bots**.
3. For **Bot Fight Mode**, select **On**.
</Steps>
</TabItem>
<TabItem label="New dashboard" icon="rocket">
<Steps>
1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com/login), and select your account and domain.
2. Go to **Security** > **Settings**.
3. Filter by **Bot traffic**.
4. Go to **Bot Fight Mode**.
5. Turn **Bot Fight Mode** on.
</Steps>
</TabItem>
</Tabs>

<Render file="sbfm-upgrade" />

Expand Down
Loading
Loading