User Agent Blocking

User Agent Blocking allows you to block specific browser or web application User-Agent request headers ↗. User agent rules apply to the entire domain instead of individual subdomains.

User agent rules are applied after zone lockdown rules. If you allow an IP address via Zone Lockdown, it will skip any user agent rules.

Note

Cloudflare recommends that you use custom rules instead of user agent rules to block specific user agents.

For example, a custom rule equivalent to the user agent example rule provided in this page could have the following configuration:

• Expression: http.user_agent eq "BadBot/1.0.2 (+http://bad.bot)"
• Action: (a block or challenge action)

Availability

Cloudflare User Agent Blocking is available on all plans. However, this feature is only available in the new security dashboard if you have configured at least one user agent rule.

The number of available user agent rules depends on your Cloudflare plan.

	Free	Pro	Business	Enterprise
Availability	Yes	Yes	Yes	Yes
Number of rules	10	50	250	1,000

Create a User Agent Blocking rule

Old dashboard

1. Log in to the Cloudflare dashboard ↗ and select your account and domain.

2. Go to Security > WAF, and select the Tools tab.

3. Under User Agent Blocking, select Create blocking rule.

4. Enter a descriptive name for the rule in Name/Description.

5. In Action, select the action to perform: Managed Challenge, Block, JS Challenge, or Interactive Challenge.

6. Enter a user agent value in User Agent (wildcards such as * are not supported). For example, to block the Bad Bot web spider, enter BadBot/1.0.2 (+http://bad.bot).

7. Select Save and Deploy blocking rule.

New dashboard

Note

User Agent Blocking is only available in the new security dashboard if you have configured at least one user agent rule. Cloudflare recommends that you use custom rules instead of user agent rules.

1. Log in to the Cloudflare dashboard ↗ and select your account and domain.

2. Go to Security > Security rules, and select Create rule > User agent rules.

3. Enter a descriptive name for the rule in Name/Description.

4. In Action, select the action to perform: Managed Challenge, Block, JS Challenge, or Interactive Challenge.

5. Enter a user agent value in User Agent (wildcards such as * are not supported). For example, to block the Bad Bot web spider, enter BadBot/1.0.2 (+http://bad.bot).

6. Select Save and Deploy blocking rule.

API

Issue a POST request for the Create a User Agent Blocking rule operation similar to the following:

Required API token permissions

At least one of the following token permissions is required:

• Firewall Services Write

Create a User Agent Blocking rule

curl "https://api.cloudflare.com/client/v4/zones/$ZONE_ID/firewall/ua_rules" \
  --request POST \
  --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
  --json '{
    "description": "Block Bad Bot web spider",
    "mode": "block",
    "configuration": {
        "target": "ua",
        "value": "BadBot/1.0.2 (+http://bad.bot)"
    }
  }'

Related resources

• Secure your application
• Cloudflare Zone Lockdown