Updated 16 September 2026
01 · why the usual options run out here
Why the usual options run out here
There are three ordinary ways to put a classifier in front of a site, and being on Cloudflare removes two of them.
Pointing the domain at another edge is the first, and it is not available: the A record already points at Cloudflare, and moving it means leaving. The origin agent is the second, and it needs the origin to be PHP with somewhere to put a load directive — true of a great many sites and not of the ones sitting behind Cloudflare in front of a static build or a serverless function.
That leaves a script tag, which runs in the browser. It reports what visits and cannot refuse anything, because nothing is routed through it. For a site that came looking for enforcement, that is not the same product.
02 · what a worker changes
What a Worker changes
A Worker runs in the one place such a site still controls: its own Cloudflare zone, on every request, before the origin sees it. So the decision happens where it has to happen, and the response to a refused request is ours rather than a page the origin had to render first.
The part worth being precise about is that this is not a separate product with its own rules. It pulls the same site configuration and the same agent catalogue the origin agent pulls, from the same endpoints, and runs the same decision ladder — which is held to that by a shared set of test vectors rather than by good intentions. A policy written once in the panel means the same thing whichever enforcement point sees the request.
03 · getting it running
Getting it running
- 1 Download the Worker from the Cloudflare tab of the connect screen in your panel.
- 2 Store the site ID, API key and secret as Cloudflare secrets. They are never written into the file you would commit.
- 3 Set the route to your zone, so the Worker sees every request rather than a sample of them.
- 4 Deploy, and leave the site in observe mode until the first figures arrive.
04 · what the worker verifies without a lookup
What the Worker verifies without a lookup
| Bot | Operator | Default policy | Verifiable |
|---|---|---|---|
| 360Spider | Qihoo 360 | Allow | By user agent |
| Alexa Archive | Alexandria.org | Allow | By user agent |
| alexa site audit | Amazon | Allow | By user agent |
| AlexandriaOrgBot | Alexandria.org | Allow | By user agent |
| Algolia | Algolia | Allow | By user agent |
| All Africa Crawler | AllAfrica Global Media | Allow | By user agent |
| Atom Feed Robot | RSSMicro | Allow | By user agent |
| Baidu ADS Server Proxy | Baidu | Allow | By user agent |
| Baiduspider | Baidu | Allow | By user agent |
| Baiduspider-render | Baidu | Allow | By user agent |
Read live from the Botscope crawler catalogue. Default policy is the catalogue default; every agent can be overridden per site.
05 · two things cloudflare answers before we are asked
Two things Cloudflare answers before we are asked
The country a request came from is resolved by Cloudflare itself, so a geographic policy needs no database of ours and no lookup on the request path.
The network is the more useful one. Cloudflare reports the originating network on every plan, which is most of what a threat feed is consulted for — whether this request came from hosting rather than from a consumer connection. That is why the Worker does not need to carry the several megabytes of address ranges the origin agent holds in memory, and why it stays small enough to run inside a request budget measured in milliseconds.
06 · where it is weaker than the origin agent
Where it is weaker than the origin agent
Matching on a TLS fingerprint needs Cloudflare's own bot-management subscription. Without one the Worker still classifies, on a coarser TLS signal — cipher, extension digest and protocol rather than a full fingerprint.
A solved browser check is recorded in Cloudflare's key-value store, which is eventually consistent. The origin agent keeps that record in memory and rejects a replay immediately; here a replay from another location within about a second can still pass, inside its own five-minute window, by somebody who already did the work.
Two behavioural checks that need state carried between requests — the subnet tarpit and session staleness — are not part of it yet.
All of which is worth reading before choosing this over DNS. It is the method for a site that cannot take DNS, and it is honestly a little less than DNS.
Questions
Do I have to leave Cloudflare to use Botscope?
No, and that is the reason this exists. The DNS method needs the A record, which Cloudflare already holds; the Worker runs inside your zone instead and needs no DNS change at all.
Does this replace Cloudflare’s own bot management?
They answer different questions. Cloudflare scores a request; this names the agent, says which check decided the outcome, and keeps that record per request so a disputed block can be looked up afterwards. Sites run both.
What does it cost in Cloudflare terms?
One Worker invocation per request, and a small number of key-value reads. Verification that needs a reverse lookup is cached for six hours, and crawler traffic repeats from the same addresses, so almost all of it is served from cache.
Can I run the Worker and the origin agent together?
Yes, and they are built to share a secret so that a visitor who completed a check at one is not asked again by the other.
Is it in the Cloudflare Apps catalogue?
That catalogue was retired — new installs stopped in January 2024 and no replacement shipped. The Worker is deployed from your own account with Cloudflare’s command-line tool.
What happens if Botscope is unreachable?
The request goes to your origin. Every failure path in the Worker passes traffic through, because it sits in front of the whole site and an outage would be worse than the traffic it was installed to stop.
See which of these reach your site
Free plan, no card: 100,000 events a month with every feature on. Nothing is blocked until you turn enforcement on.