1# Bot Management Patterns
2 
3## E-commerce Protection
4 
5```txt
6# High security for checkout
7(cf.bot_management.score lt 50 and http.request.uri.path in {"/checkout" "/cart/add"} and not cf.bot_management.verified_bot and not cf.bot_management.corporate_proxy)
8Action: Managed Challenge
9```
10 
11## API Protection
12 
13```txt
14# Protect API with JS detection + score
15(http.request.uri.path matches "^/api/" and (cf.bot_management.score lt 30 or not cf.bot_management.js_detection.passed) and not cf.bot_management.verified_bot)
16Action: Block
17```
18 
19## SEO-Friendly Bot Handling
20 
21```txt
22# Allow search engine crawlers
23(cf.bot_management.score lt 30 and not cf.verified_bot_category in {"Search Engine Crawler"})
24Action: Managed Challenge
25```
26 
27## Block AI Scrapers
28 
29```txt
30# Block training crawlers only (allow AI assistants/search)
31(cf.verified_bot_category eq "AI Crawler")
32Action: Block
33 
34# Block all AI-related bots (training + assistants + search)
35(cf.verified_bot_category in {"AI Crawler" "AI Assistant" "AI Search"})
36Action: Block
37 
38# Allow AI Search, block AI Crawler and AI Assistant
39(cf.verified_bot_category in {"AI Crawler" "AI Assistant"})
40Action: Block
41 
42# Or use dashboard: Security > Settings > Bot Management > Block AI Bots
43```
44 
45## Rate Limiting by Bot Score
46 
47```txt
48# Stricter limits for suspicious traffic
49(cf.bot_management.score lt 50)
50Rate: 10 requests per 10 seconds
51 
52(cf.bot_management.score ge 50)
53Rate: 100 requests per 10 seconds
54```
55 
56## Mobile App Allowlisting
57 
58```txt
59# Identify mobile app by JA3/JA4
60(cf.bot_management.ja4 in {"fingerprint1" "fingerprint2"})
61Action: Skip (all remaining rules)
62```
63 
64## Datacenter Detection
65 
66```typescript
67import type { IncomingRequestCfProperties } from '@cloudflare/workers-types';
68 
69// Low score + not corporate proxy = likely datacenter bot
70export default {
71  async fetch(request: Request): Promise<Response> {
72    const cf = request.cf as IncomingRequestCfProperties | undefined;
73    const botMgmt = cf?.botManagement;
74    
75    if (botMgmt?.score && botMgmt.score < 30 && 
76        !botMgmt.corporateProxy && !botMgmt.verifiedBot) {
77      return new Response('Datacenter traffic blocked', { status: 403 });
78    }
79    
80    return fetch(request);
81  }
82};
83```
84 
85## Conditional Delay (Tarpit)
86 
87```typescript
88import type { IncomingRequestCfProperties } from '@cloudflare/workers-types';
89 
90// Add delay proportional to bot suspicion
91export default {
92  async fetch(request: Request): Promise<Response> {
93    const cf = request.cf as IncomingRequestCfProperties | undefined;
94    const botMgmt = cf?.botManagement;
95    
96    if (botMgmt?.score && botMgmt.score < 50 && !botMgmt.verifiedBot) {
97      // Delay: 0-2 seconds for scores 50-0
98      const delayMs = Math.max(0, (50 - botMgmt.score) * 40);
99      await new Promise(r => setTimeout(r, delayMs));
100    }
101    
102    return fetch(request);
103  }
104};
105```
106 
107## Layered Defense
108 
109```txt
1101. Bot Management (score-based)
1112. JavaScript Detections (for JS-capable clients)
1123. Rate Limiting (fallback protection)
1134. WAF Managed Rules (OWASP, etc.)
114```
115 
116## Progressive Enhancement
117 
118```txt
119Public content: High threshold (score < 10)
120Authenticated: Medium threshold (score < 30)
121Sensitive: Low threshold (score < 50) + JSD
122```
123 
124## Zero Trust for Bots
125 
126```txt
1271. Default deny (all scores < 30)
1282. Allowlist verified bots
1293. Allowlist mobile apps (JA3/JA4)
1304. Allowlist corporate proxies
1315. Allowlist static resources
132```
133 
134## Workers: Score + JS Detection
135 
136```typescript
137import type { IncomingRequestCfProperties } from '@cloudflare/workers-types';
138 
139export default {
140  async fetch(request: Request): Promise<Response> {
141    const cf = request.cf as IncomingRequestCfProperties | undefined;
142    const botMgmt = cf?.botManagement;
143    const url = new URL(request.url);
144    
145    if (botMgmt?.staticResource) return fetch(request); // Skip static
146    
147    // API endpoints: require JS detection + good score
148    if (url.pathname.startsWith('/api/')) {
149      const jsDetectionPassed = botMgmt?.jsDetection?.passed ?? false;
150      const score = botMgmt?.score ?? 100;
151      
152      if (!jsDetectionPassed || score < 30) {
153        return new Response('Unauthorized', { status: 401 });
154      }
155    }
156    
157    return fetch(request);
158  }
159};
160```
161 
162## Rate Limiting by JWT Claim + Bot Score
163 
164```txt
165# Enterprise: Combine bot score with JWT validation
166Rate limiting > Custom rules
167- Field: lookup_json_string(http.request.jwt.claims["{config_id}"][0], "sub")
168- Matches: user ID claim
169- Additional condition: cf.bot_management.score lt 50
170```
171 
172## WAF Integration Points
173 
174- **WAF Custom Rules**: Primary enforcement mechanism
175- **Rate Limiting Rules**: Bot score as dimension, stricter limits for low scores
176- **Transform Rules**: Pass score to origin via custom header
177- **Workers**: Programmatic bot logic, custom scoring algorithms
178- **Page Rules / Configuration Rules**: Zone-level overrides, path-specific settings
179 
180## See Also
181 
182- [gotchas.md](./gotchas.md) - Common errors, false positives/negatives, limitations
183