1# Bot Management Configuration
2 
3## Product Tiers
4 
5**Note:** Dashboard paths differ between old and new UI:
6- **New:** Security > Settings > Filter "Bot traffic"
7- **Old:** Security > Bots
8 
9Both UIs access same settings.
10 
11### Bot Score Groupings (Pro/Business)
12 
13Pro/Business users see bot score groupings instead of granular 1-99 scores:
14 
15| Score | Grouping | Meaning |
16|-------|----------|---------|
17| 0 | Not computed | Bot Management didn't run |
18| 1 | Automated | Definite bot (heuristic match) |
19| 2-29 | Likely automated | Probably bot (ML detection) |
20| 30-99 | Likely human | Probably human |
21| N/A | Verified bot | Allowlisted good bot |
22 
23Enterprise plans get granular 1-99 scores for custom thresholds.
24 
25### Bot Fight Mode (Free)
26- Auto-blocks definite bots (score=1), excludes verified bots by default
27- JavaScript Detections always enabled, no configuration options
28 
29### Super Bot Fight Mode (Pro/Business)
30```txt
31Dashboard: Security > Bots > Configure
32- Definitely automated: Block/Challenge
33- Likely automated: Challenge/Allow  
34- Verified bots: Allow (recommended)
35- Static resource protection: ON (may block mail clients)
36- JavaScript Detections: Optional
37```
38 
39### Bot Management for Enterprise
40```txt
41Dashboard: Security > Bots > Configure > Auto-updates: ON (recommended)
42 
43# Template 1: Block definite bots
44(cf.bot_management.score eq 1 and not cf.bot_management.verified_bot and not cf.bot_management.static_resource)
45Action: Block
46 
47# Template 2: Challenge likely bots
48(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)
49Action: Managed Challenge
50```
51 
52## JavaScript Detections Setup
53 
54### Enable via Dashboard
55```txt
56Security > Bots > Configure Bot Management > JS Detections: ON
57 
58Update CSP: script-src 'self' /cdn-cgi/challenge-platform/;
59```
60 
61### Manual JS Injection (API)
62```html
63<script>
64function jsdOnload() {
65  window.cloudflare.jsd.executeOnce({ callback: function(result) { console.log('JSD:', result); } });
66}
67</script>
68<script src="/cdn-cgi/challenge-platform/scripts/jsd/api.js?onload=jsdOnload" async></script>
69```
70 
71**Use API for**: Selective deployment on specific pages  
72**Don't combine**: Zone-wide toggle + manual injection
73 
74### WAF Rules for JSD
75```txt
76# NEVER use on first page visit (needs HTML page first)
77(not cf.bot_management.js_detection.passed and http.request.uri.path eq "/api/user/create" and http.request.method eq "POST" and not cf.bot_management.verified_bot)
78Action: Managed Challenge (always use Managed Challenge, not Block)
79```
80 
81### Limitations
82- First request won't have JSD data (needs HTML page first)
83- Strips ETags from HTML responses
84- Not supported with CSP via `<meta>` tags
85- Websocket endpoints not supported
86- Native mobile apps won't pass
87- cf_clearance cookie: 15-minute lifespan, max 4096 bytes
88 
89## __cf_bm Cookie
90 
91Cloudflare sets `__cf_bm` cookie to smooth bot scores across user sessions:
92 
93- **Purpose:** Reduces false positives from score volatility
94- **Scope:** Per-domain, HTTP-only
95- **Lifespan:** Session duration
96- **Privacy:** No PII—only session classification
97- **Automatic:** No configuration required
98 
99Bot scores for repeat visitors consider session history via this cookie.
100 
101## Static Resource Protection
102 
103**File 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  
104**Plus**: `/.well-known/` path (all files)
105 
106```txt
107# Exclude static resources from bot rules
108(cf.bot_management.score lt 30 and not cf.bot_management.static_resource)
109```
110 
111**WARNING**: May block mail clients fetching static images
112 
113## JA3/JA4 Fingerprinting (Enterprise)
114 
115```txt
116# Block specific attack fingerprint
117(cf.bot_management.ja3_hash eq "8b8e3d5e3e8b3d5e")
118 
119# Allow mobile app by fingerprint
120(cf.bot_management.ja4 eq "your_mobile_app_fingerprint")
121```
122 
123Only available for HTTPS/TLS traffic. Missing for Worker-routed traffic or HTTP requests.
124 
125## Verified Bot Categories
126 
127```txt
128# Allow search engines only
129(cf.verified_bot_category eq "Search Engine Crawler")
130 
131# Block AI crawlers
132(cf.verified_bot_category eq "AI Crawler")
133Action: Block
134 
135# Or use dashboard: Security > Settings > Bot Management > Block AI Bots
136```
137 
138| Category | String Value | Example |
139|----------|--------------|---------|
140| AI Crawler | `AI Crawler` | GPTBot, Claude-Web |
141| AI Assistant | `AI Assistant` | Perplexity-User, DuckAssistBot |
142| AI Search | `AI Search` | OAI-SearchBot |
143| Accessibility | `Accessibility` | Accessible Web Bot |
144| Academic Research | `Academic Research` | Library of Congress |
145| Advertising & Marketing | `Advertising & Marketing` | Google Adsbot |
146| Aggregator | `Aggregator` | Pinterest, Indeed |
147| Archiver | `Archiver` | Internet Archive, CommonCrawl |
148| Feed Fetcher | `Feed Fetcher` | RSS/Podcast updaters |
149| Monitoring & Analytics | `Monitoring & Analytics` | Uptime monitors |
150| Page Preview | `Page Preview` | Facebook/Slack link preview |
151| SEO | `Search Engine Optimization` | Google Lighthouse |
152| Security | `Security` | Vulnerability scanners |
153| Social Media Marketing | `Social Media Marketing` | Brandwatch |
154| Webhooks | `Webhooks` | Payment processors |
155| Other | `Other` | Uncategorized bots |
156 
157## Best Practices
158 
159- **ML Auto-Updates**: Enable on Enterprise for latest models
160- **Start with Managed Challenge**: Test before blocking
161- **Always exclude verified bots**: Use `not cf.bot_management.verified_bot`
162- **Exempt corporate proxies**: For B2B traffic via `cf.bot_management.corporate_proxy`
163- **Use static resource exception**: Improves performance, reduces overhead
164