Cloudflare Edge Sensor

The edge sensor is a Cloudflare Worker that reports automated clients which never execute JavaScript. It runs in front of your origin, so it sees requests a browser never makes.

Create a free account → · Compare all install methods

Install in about 5 minutes

In WebDecoy, select the site that receives traffic through Cloudflare.
Open Integrations → Cloudflare and choose Connect with Cloudflare.
Approve the four requested Cloudflare scopes on Cloudflare’s consent screen.
Open Edge Sensor, choose the zone and route, and select Deploy edge sensor.
Open Sensors and confirm the Edge Worker row appears, then fire a test request.

No code, package, or manual Worker upload is required. WebDecoy uploads the Worker, binds the route, and enables reporting for you.

For coverage, architecture, and deployment context, see the Cloudflare Edge Sensor product overview.

Why you need it

WebDecoy’s detection script runs in the visitor’s browser. That is the right place to fingerprint a real browser, and it is the wrong place (the impossible place) to see a client that never opens one.

Googlebot’s crawl pass does not run your JavaScript. Neither does GPTBot, ClaudeBot, CCBot, PerplexityBot, curl, or most scrapers. On a JavaScript-only install, your Citation Monitor can only ever show browser extensions and LLM referrals. It cannot show you a crawler, ever. That is not a tuning problem or a bug; it is what a page tag is.

The edge sensor closes that gap and nothing else. It does not replace the detection script. They see different populations.

What it does and does not do

It inspects each request, decides whether it looks automated, and sends a small beacon to WebDecoy when it does.

Sensing never blocks, challenges, or modifies a response. Detection and enforcement are two jobs of the same Worker (Cloudflare runs one Worker per matched route, so shipping two would mean one of them silently not running), but they are separate paths through it. Enforcement acts only on clients you have already denied; sensing only reports.

On any internal error it fails open: ingest being unreachable, a malformed config, an oversized beacon, or an unexpected exception all result in your visitor’s request being served exactly as it would have been.

Install

One click, from the app

Integrations → Cloudflare → Edge Sensor. Pick your Zone, check the Route pattern, and press Deploy edge sensor. WebDecoy uploads the Worker, binds the route, and switches reporting on.

You need a connected Cloudflare integration first. There are two ways to get one, and the one-click install works with either.

Connect with Cloudflare (recommended)

Press Connect with Cloudflare on the Cloudflare integration panel and approve WebDecoy on Cloudflare’s own consent screen. Nothing to create, no permissions to tick, nothing to paste. WebDecoy asks for exactly four scopes and no others:

Scope	For
`zone.read`	Listing your zones
`workers-scripts.write`	Uploading the Worker
`workers-routes.write`	Binding the sensor to your traffic
`firewall-services.write`	Pushing WAF rules for Response Actions

If your Cloudflare login can see more than one account, the install form adds a Cloudflare account picker (“Where the Worker is uploaded”). With a single account it is chosen for you.

Or connect with an API token

The token path is still there if you prefer it. The token needs:

Permission	For
Zone → Zone → Read	Listing your zones
Zone → Workers Routes → Edit	Binding the sensor to your traffic
Account → Workers Scripts → Edit	Uploading the Worker
Zone → DNS → Read (optional)	Confirming your record is proxied before installing

Scope the token to both Zone Resources and Account Resources. Workers Scripts is an account-level permission, so a token scoped only to a zone fails the upload with an error that reads like a missing permission.

DNS → Read is the one capability consent cannot give you. See Your zone must be proxied.

Which site the detections land under

A Cloudflare integration belongs to one site, not to your whole organization. Before you deploy, the form states where the sensor’s detections will be filed: “Detections from this zone will be filed under <site>. Switch sites in the header to change it.” If WebDecoy cannot work out which site a zone belongs to, it asks instead, with a Report detections under picker.

Deploy it yourself

If you would rather own the deployment, the Worker is published at github.com/WebDecoy/edge with a “Deploy to Cloudflare” button. It is byte-identical to what the one-click installer uploads.

You bind the route yourself in that path. Deploying a Worker without a route means it runs for nothing.

Adopting a Worker you deployed by hand

If a WebDecoy Worker you deployed yourself already owns the route, the installer no longer refuses. It tells you what it found and what pressing deploy again would do:

<script> is already on this route, a WebDecoy Worker that was deployed by hand. Deploying again replaces it with the managed sensor and takes over the route.

Pressing Deploy edge sensor a second time is the confirmation. The old Worker stays on your Cloudflare account but stops running, since nothing will be routed to it. It may still serve other routes.

This applies only to a Worker WebDecoy recognises as its own. A route owned by an unrelated Worker is still refused, because taking it over would silently stop yours.

Your zone must be proxied

Worker routes only fire on proxied (orange-cloud) DNS records. On a DNS-only record, Cloudflare accepts the route and the Worker never runs: the install reports success and produces nothing, indefinitely.

Whether WebDecoy can check this for you depends on how you connected:

Connection	Proxied check
API token with `Zone > DNS > Read`	Checked before installing; a DNS-only record is refused with a specific error
API token without it	Install proceeds and warns that it could not verify
Consent (OAuth)	Not available (see below)

Cloudflare’s OAuth permissions do not cover reading DNS records. There is no scope that works: dns_records.read is rejected at the consent screen, and dns.read and dns.write are both accepted at consent and then still refused by the DNS records API. WebDecoy therefore stopped asking for a DNS scope at all, rather than showing you a permission request that buys nothing.

So if you connected by pressing Connect with Cloudflare, the install will tell you it could not verify the record. That is expected and not a misconfiguration: confirm the orange cloud yourself in DNS → Records. Everything else about the install is unaffected.

The installer does still catch the coarser version of this. If Cloudflare is not proxying the zone at all, the form says so before you deploy: “Cloudflare is not proxying this zone, so a Worker on it never runs. Turn the orange cloud on for the records you want covered.”

Invocations and billing

The sensor consumes a Worker invocation on your Cloudflare account for every request it runs on. Workers’ free tier is 100,000 requests/day.

The installer reduces this by binding negating routes: routes bound to no script, which stop any Worker running on a more specific path, since Cloudflare matches most-specific-first:

/_astro/*   /_next/*   /_nuxt/*   /_app/*   /assets/*   /static/*
/build/*    /dist/*    /wp-content/*   /wp-includes/*   /cdn-cgi/*

These affect every Worker on those paths, not only the sensor. If you already run a Worker that must serve them, install with negating routes disabled and manage the patterns yourself.

Keeping the sensor current

WebDecoy ships new sensor builds. A sensor you installed through the app can be brought up to date in place, without touching your routes.

Sensors (in the sidebar, under Countermeasures) is the page for this. Each sensor row shows the build it is running, and when yours is behind the one we ship it says so:

Running 780b409a81fb; we ship daadab99a7f1.

Press Update next to that line. It replaces the deployed Worker with the current build; your routes are not touched and traffic keeps flowing. The button appears only for a sensor WebDecoy installed (tagged managed on the row), because those are the ones it can safely replace.

The same control appears on the integration panel as Update available, and the deployed build is shown there under Worker. Both display the first twelve characters of the bundle hash, which is enough to compare two builds at a glance.

Checking that it is reporting

The Sensors page is also where you confirm the install is doing something. It lists everything reporting traffic for each site: edge workers, the WordPress plugin, the SDKs, detection scripts, decoy links, and tripwires. Per sensor it shows when it was last seen and its detection counts over 24h and 7d, and it states plainly which of these it is:

Row says	Means
Reporting	Detections are arriving
Nothing reported yet	Installed, nothing has come in
Quiet	It has reported before, but not recently
Deployed but switched off, the edge is not reporting	The Worker is there and no enabled config is being served

The integration panel states the same thing as Reporting: On or Off.

Fire a test detection

The fastest end-to-end proof: send one request through your zone with the reserved test User-Agent. The sensor always beacons it (sampling and burst limits never drop it), and it shows up labeled Test in the dashboard, excluded from stats and billing:

curl -A "WebDecoy-Test/1.0" https://your-site.example/

If no Test detection appears within a minute, the Worker is not seeing your traffic: check that the zone is proxied (orange cloud) and that the sensor shows Reporting: On. Workers deployed before this feature honor it after their next update (see Keeping the sensor current).

Troubleshooting

It says installed but reports nothing

Start on the Sensors page: it distinguishes “installed and silent” from “never installed” without you having to guess. Then, in order of how often each is the cause:

Reporting is off. The card shows Reporting: On or Off. Off means the Worker is deployed but no enabled configuration is being served, so it classifies traffic and sends none of it.
The record is not proxied. Check for the orange cloud in Cloudflare DNS → Records. This is the most common cause of a silent install.
The route does not match your traffic. example.com/* does not cover www.example.com/*. Check the bound pattern against the hostname visitors actually use.
Nothing has crawled you yet. Crawler traffic is bursty. Give it an hour before treating silence as a fault.

The install refused

Refusals are deliberate and each names its fix:

“already bound to the Worker …”: another Worker owns that route pattern. Cloudflare runs one Worker per matched route, so taking it over would silently stop yours. Remove or change that route, then install again. (A WebDecoy Worker you deployed by hand is the exception: that one you can adopt, see Adopting a Worker you deployed by hand.)
“Cloudflare is paused on …”: the zone is not proxying at all.
“the DNS record for … is DNS-only”: switch the record to Proxied.
“we cannot tell which one the sensor’s detections belong to”: your organization has several properties and none is named for the zone. Choose one; detections are filed against that property.

Detections appear under the wrong property

The sensor reports against one scanner, which belongs to one property. Re-installing and choosing a different property does not move detections that already landed.

Uninstall

From the app: Integrations → Cloudflare → Edge Sensor → Uninstall. It confirms first (“Remove the Worker and all n routes from this zone? Detections from the edge stop immediately”), then removes every route the installer created and then the Worker.

If you deployed it yourself, delete the route first, then the Worker. Deleting the Worker while a route still points at it leaves the route referencing a script that no longer exists, and your visitors are what discovers that.

Cloudflare Integration: WAF enforcement and credentials
Detection Sources: how edge_worker rows differ