1# Bot Management API
2 
3## Workers: BotManagement Interface
4 
5```typescript
6interface BotManagement {
7  score: number;              // 1-99 (Enterprise), 0 if not computed
8  verifiedBot: boolean;       // Is verified bot
9  staticResource: boolean;    // Serves static resource
10  ja3Hash: string;            // JA3 fingerprint (Enterprise, HTTPS only)
11  ja4: string;                // JA4 fingerprint (Enterprise, HTTPS only)
12  jsDetection?: {
13    passed: boolean;          // Passed JS detection (if enabled)
14  };
15  detectionIds: number[];     // Heuristic detection IDs
16  corporateProxy?: boolean;   // From corporate proxy (Enterprise)
17}
18 
19// DEPRECATED: Use botManagement.score instead
20// request.cf.clientTrustScore (legacy, duplicate of botManagement.score)
21 
22// Access via request.cf
23import type { IncomingRequestCfProperties } from '@cloudflare/workers-types';
24 
25export default {
26  async fetch(request: Request): Promise<Response> {
27    const cf = request.cf as IncomingRequestCfProperties | undefined;
28    const botMgmt = cf?.botManagement;
29    
30    if (!botMgmt) return fetch(request);
31    if (botMgmt.verifiedBot) return fetch(request); // Allow verified bots
32    if (botMgmt.score === 1) return new Response('Blocked', { status: 403 });
33    if (botMgmt.score < 30) return new Response('Challenge required', { status: 429 });
34    
35    return fetch(request);
36  }
37};
38```
39 
40## WAF Fields Reference
41 
42```txt
43# Score fields
44cf.bot_management.score                    # 0-99 (0 = not computed)
45cf.bot_management.verified_bot             # boolean
46cf.bot_management.static_resource          # boolean
47cf.bot_management.ja3_hash                 # string (Enterprise)
48cf.bot_management.ja4                      # string (Enterprise)
49cf.bot_management.detection_ids            # array
50cf.bot_management.js_detection.passed      # boolean
51cf.bot_management.corporate_proxy          # boolean (Enterprise)
52cf.verified_bot_category                   # string
53 
54# Workers equivalent
55request.cf.botManagement.score
56request.cf.botManagement.verifiedBot
57request.cf.botManagement.ja3Hash
58request.cf.botManagement.ja4
59request.cf.botManagement.jsDetection.passed
60request.cf.verifiedBotCategory
61```
62 
63## JA4 Signals (Enterprise)
64 
65```typescript
66import type { IncomingRequestCfProperties } from '@cloudflare/workers-types';
67 
68interface JA4Signals {
69  // Ratios (0.0-1.0)
70  heuristic_ratio_1h?: number;  // Fraction flagged by heuristics
71  browser_ratio_1h?: number;    // Fraction from real browsers  
72  cache_ratio_1h?: number;      // Fraction hitting cache
73  h2h3_ratio_1h?: number;       // Fraction using HTTP/2 or HTTP/3
74  // Ranks (relative position in distribution)
75  uas_rank_1h?: number;         // User-Agent diversity rank
76  paths_rank_1h?: number;       // Path diversity rank
77  reqs_rank_1h?: number;        // Request volume rank
78  ips_rank_1h?: number;         // IP diversity rank
79  // Quantiles (0.0-1.0, percentile in distribution)
80  reqs_quantile_1h?: number;    // Request volume quantile
81  ips_quantile_1h?: number;     // IP count quantile
82}
83 
84export default {
85  async fetch(request: Request): Promise<Response> {
86    const cf = request.cf as IncomingRequestCfProperties | undefined;
87    const ja4Signals = cf?.ja4Signals as JA4Signals | undefined;
88    
89    if (!ja4Signals) return fetch(request); // Not available for HTTP or Worker routing
90    
91    // Check for anomalous behavior
92    // High heuristic_ratio or low browser_ratio = suspicious
93    const heuristicRatio = ja4Signals.heuristic_ratio_1h ?? 0;
94    const browserRatio = ja4Signals.browser_ratio_1h ?? 0;
95    
96    if (heuristicRatio > 0.5 || browserRatio < 0.3) {
97      return new Response('Suspicious traffic', { status: 403 });
98    }
99    
100    return fetch(request);
101  }
102};
103```
104 
105## Common Patterns
106 
107See [patterns.md](./patterns.md) for Workers examples: mobile app allowlisting, corporate proxy exemption, datacenter detection, conditional delay, and more.
108 
109## Bot Analytics
110 
111### Access Locations
112- Dashboard: Security > Bots (old) or Security > Analytics > Bot analysis (new)
113- GraphQL API for programmatic access
114- Security Events & Security Analytics
115- Logpush/Logpull
116 
117### Available Data
118- **Enterprise BM**: Bot scores (1-99), bot score source, distribution
119- **Pro/Business**: Bot groupings (automated, likely automated, likely human)
120- Top attributes: IPs, paths, user agents, countries
121- Detection sources: Heuristics, ML, AD, JSD
122- Verified bot categories
123 
124### Time Ranges
125- **Enterprise BM**: Up to 1 week at a time, 30 days history
126- **Pro/Business**: Up to 72 hours at a time, 30 days history
127- Real-time in most cases, adaptive sampling (1-10% depending on volume)
128 
129## Logpush Fields
130 
131```txt
132BotScore              # 1-99 or 0 if not computed
133BotScoreSrc           # Detection engine (ML, Heuristics, etc.)
134BotTags               # Classification tags
135BotDetectionIDs       # Heuristic detection IDs
136```
137 
138**BotScoreSrc values:**
139- `"Heuristics"` - Known fingerprint
140- `"Machine Learning"` - ML model
141- `"Anomaly Detection"` - Baseline anomaly
142- `"JS Detection"` - JavaScript check
143- `"Cloudflare Service"` - Zero Trust
144- `"Not Computed"` - Score = 0
145 
146Access via Logpush (stream to cloud storage/SIEM), Logpull (API to fetch logs), or GraphQL API (query analytics data).
147 
148## Testing with Miniflare
149 
150Miniflare provides mock botManagement data for local development:
151 
152**Default values:**
153- `score: 99` (human)
154- `verifiedBot: false`
155- `corporateProxy: false`
156- `ja3Hash: "25b4882c2bcb50cd6b469ff28c596742"`
157- `staticResource: false`
158- `detectionIds: []`
159 
160**Override in tests:**
161```typescript
162import { getPlatformProxy } from 'wrangler';
163 
164const { cf, dispose } = await getPlatformProxy();
165// cf.botManagement is frozen mock object
166expect(cf.botManagement.score).toBe(99);
167```
168 
169For custom test data, mock request.cf in your test setup.
170