How-to
Bot Score Detector
How the Bot Score detector uses Cloudflare Bot Management scores to identify automated traffic from specific networks.
Jump to section
What is Bot Score?
Cloudflare Bot Management assigns every request a score from 1 to 99. Scores below 30 indicate likely automated traffic. The scoring engine incorporates dozens of signals internally — including TLS fingerprinting (JA3), browser behaviour, IP reputation, and machine learning models.
The SFCC eCDN exposes the BotScore field in Logpush, giving Edge access to Cloudflare's own bot detection intelligence.
Why it matters
Rather than relying on a single signal (like a TLS fingerprint hash), the Bot Score aggregates many signals into one verdict. An ASN where 50%+ of traffic scores below 30 is almost certainly sending automated requests — even if the user agents look legitimate, IPs rotate, and request patterns vary.
How it works
The detector runs hourly and queries Workers Analytics Engine for bot score distribution per ASN:
- Groups traffic by (ASN, bot score bucket) — buckets are "bot" (1-29), "suspicious" (30-49), "human" (50+), and "unscored"
- For each ASN, calculates the ratio of "bot" traffic to total scored traffic
- Trips when the bot ratio exceeds the threshold AND total requests exceed a floor
Only scored traffic is considered — "unscored" requests (where BotScore is absent) are excluded from the ratio calculation.
The bypass qualifier
Being bot-scored is not the same as being a problem. Googlebot indexing your catalogue, or a SaaS vendor pulling from a static CDN path, can score 99% bot and still cost your origin nothing because the edge serves almost all of it from cache. Alerting on those wastes everyone’s time.
So the detector adds a second gate: of an ASN’s bot-scored traffic, a minimum share (default 30%) must be bypassing the cache and hitting your origin to count as abuse. Credential stuffing from a datacentre at close to 100% cache bypass clears the gate easily; a near-100%-cache-hit crawler never does. It reads the cache status already in your Logpush, which is why the detector stays quiet on the benign automation other tools flag.
Default thresholds
| Parameter | Default | Description |
|---|---|---|
window_minutes | 60 | Time window to evaluate |
bot_ratio_threshold | 0.5 (50%) | Trip when this % of scored traffic is bot-scored |
min_requests | 1000 | Volume floor to suppress noise |
bot_bypass_ratio_threshold | 0.3 (30%) | Min share of an ASN’s bot traffic that must bypass cache (hit origin) |
Severity
- Warning: bot ratio exceeds the threshold (default 50%)
- Critical: bot ratio exceeds 2x the threshold or 80%, whichever is lower
Requirements
This detector requires the BotScore field in your Logpush job. If the field is not included, all traffic is bucketed as "unscored" and the detector won't fire. Add BotScore and BotScoreSrc to your Logpush field selection for full coverage.