Cloudflare Workers
One Worker in front of your site checks each visitor and tells your origin what it found.
Setup
Or use the Deploy button above.
git clone https://github.com/ipscanner/ipscanner-cloudflare
cd ipscanner-cloudflare
npm install
npx wrangler deploynpx wrangler secret put IPSCANNER_API_KEYOn a custom domain or workers.dev, set ORIGIN_URL to your backend instead.
"routes": [{
"pattern": "example.com/*",
"zone_name": "example.com"
}]How it works
The Worker reads the visitor's IP, User-Agent and JA4, when Cloudflare provides it.
Agentscan and IP Detection run in parallel, cached per visitor, and fail open after 1.5 seconds.
Monitor mode sends verdict headers to your origin. Enforce mode also answers a blocked visitor with a 403.
Verified crawlers always pass, and X-IPScanner-* headers sent by the client are stripped.
Headers
When a check fails or is skipped, only X-IPScanner-Status is set.
| Header | From | Example |
|---|---|---|
| X-IPScanner-ClassAgentscan | Agentscan | human |
| X-IPScanner-ActionAgentscan | Agentscan | allow |
| X-IPScanner-ConfidenceAgentscan | Agentscan | 0.92 |
| X-IPScanner-Network-ClassIP Detection | IP Detection | residential_clean |
| X-IPScanner-AnonymizedBoth | Both | false |
| X-IPScanner-RiskIP Detection | IP Detection | 12 |
| X-IPScanner-CountryIP Detection | IP Detection | DE |
| X-IPScanner-StatusWorker | Worker | ok |
Settings
Set these in the vars block of wrangler.jsonc.
| Variable | Default | What it does |
|---|---|---|
| MODEmonitor adds headers, enforce also blocks | monitor | monitor adds headers, enforce also blocks |
| CHECK_AGENTRuns Agentscan | true | Runs Agentscan |
| CHECK_IPRuns IP Detection | true | Runs IP Detection |
| BLOCK_CLASSESAgentscan classes to block in enforce mode | malicious_automation | Agentscan classes to block in enforce mode |
| BLOCK_ANONYMIZEDAlso blocks VPN, proxy and Tor in enforce mode | false | Also blocks VPN, proxy and Tor in enforce mode |
| TIMEOUT_MSPer call, then the request goes through | 1500 | Per call, then the request goes through |
| AGENT_TTLSeconds to cache an Agentscan verdict | 600 | Seconds to cache an Agentscan verdict |
| IP_TTLSeconds to cache an IP lookup | 3600 | Seconds to cache an IP lookup |
| SKIP_PATHSPath regex that skips the check | Static assets | Path regex that skips the check |
| ORIGIN_URLBackend to forward to when not on a route | Empty | Backend to forward to when not on a route |
Questions