1# Cloudflare Bot Management
2 
3Enterprise-grade bot detection, protection, and mitigation using ML/heuristics, bot scores, JavaScript detections, and verified bot handling.
4 
5## Overview
6 
7Bot Management provides multi-tier protection:
8- **Free (Bot Fight Mode)**: Auto-blocks definite bots, no config
9- **Pro/Business (Super Bot Fight Mode)**: Configurable actions, static resource protection, analytics groupings
10- **Enterprise (Bot Management)**: Granular 1-99 scores, WAF integration, JA3/JA4 fingerprinting, Workers API, Advanced Analytics
11 
12## Quick Start
13 
14```txt
15# Dashboard: Security > Bots
16# Enterprise: Deploy rule template
17(cf.bot_management.score eq 1 and not cf.bot_management.verified_bot) → Block
18(cf.bot_management.score le 29 and not cf.bot_management.verified_bot) → Managed Challenge
19```
20 
21## What Do You Need?
22 
23```txt
24├─ Initial setup → configuration.md
25│   ├─ Free tier → "Bot Fight Mode"
26│   ├─ Pro/Business → "Super Bot Fight Mode"
27│   └─ Enterprise → "Bot Management for Enterprise"
28├─ Workers API integration → api.md
29├─ WAF rules → patterns.md
30├─ Debugging → gotchas.md
31└─ Analytics → api.md#bot-analytics
32```
33 
34## Reading Order
35 
36| Task | Files to Read |
37|------|---------------|
38| Enable bot protection | README → configuration.md |
39| Workers bot detection | README → api.md |
40| WAF rule templates | README → patterns.md |
41| Debug bot issues | gotchas.md |
42| Advanced analytics | api.md#bot-analytics |
43 
44## Core Concepts
45 
46**Bot Scores**: 1-99 (1 = definitely automated, 99 = definitely human). Threshold: <30 indicates bot traffic. Enterprise gets granular 1-99; Pro/Business get groupings only.
47 
48**Detection Engines**: Heuristics (known fingerprints, assigns score=1), ML (majority of detections, supervised learning on billions of requests), Anomaly Detection (optional, baseline traffic analysis), JavaScript Detections (headless browser detection).
49 
50**Verified Bots**: Allowlisted good bots (search engines, AI crawlers) verified via reverse DNS or Web Bot Auth. Access via `cf.bot_management.verified_bot` or `cf.verified_bot_category`.
51 
52## Platform Limits
53 
54| Plan | Bot Scores | JA3/JA4 | Custom Rules | Analytics Retention |
55|------|------------|---------|--------------|---------------------|
56| Free | No (auto-block only) | No | 5 | N/A (no analytics) |
57| Pro/Business | Groupings only | No | 20/100 | 30 days (72h at a time) |
58| Enterprise | 1-99 granular | Yes | 1,000+ | 30 days (1 week at a time) |
59 
60## Basic Patterns
61 
62```typescript
63// Workers: Check bot score
64export default {
65  async fetch(request: Request): Promise<Response> {
66    const botScore = request.cf?.botManagement?.score;
67    if (botScore && botScore < 30 && !request.cf?.botManagement?.verifiedBot) {
68      return new Response('Bot detected', { status: 403 });
69    }
70    return fetch(request);
71  }
72};
73```
74 
75```txt
76# WAF: Block definite bots
77(cf.bot_management.score eq 1 and not cf.bot_management.verified_bot)
78 
79# WAF: Protect sensitive endpoints
80(cf.bot_management.score lt 50 and http.request.uri.path in {"/login" "/checkout"} and not cf.bot_management.verified_bot)
81```
82 
83## In This Reference
84 
85- [configuration.md](./configuration.md) - Product tiers, WAF rule setup, JavaScript Detections, ML auto-updates
86- [api.md](./api.md) - Workers BotManagement interface, WAF fields, JA4 Signals
87- [patterns.md](./patterns.md) - E-commerce, API protection, mobile app allowlisting, SEO-friendly handling
88- [gotchas.md](./gotchas.md) - False positives/negatives, score=0 issues, JSD limitations, CSP requirements
89 
90## See Also
91 
92- [waf](../waf/) - WAF custom rules for bot enforcement
93- [workers](../workers/) - Workers request.cf.botManagement API
94- [api-shield](../api-shield/) - API-specific bot protection
95