Cloudflare Workers

Bot and VPN checks in a Cloudflare Worker

One Worker in front of your site sorts every visitor: people, real search crawlers, AI crawlers like GPTBot, and bots on VPNs or data centers.

Speed

Decided before your visitor blinks.

Every check answers in 50 to 100 ms, so your pages and signups never wait on it.

IPScanner checkmedian, at your edge
~85 ms
A blinkhuman eye
300 ms
A fast page loadGoogle's “good” mark
2.5 s

The short version

What it catches

AI crawlers like GPTBot and ClaudeBot, scrapers, fake Googlebots and bots on VPNs, Tor or data centers. People and real search crawlers get in.

No code to write

Click Deploy to Cloudflare, paste your API key and Site ID, add a route. About 10 minutes.

You decide per class

Each kind of visitor is set to Allow, Flag or Block. Flag lets it in and marks it, so you can switch that class to Block later in one click.

What it costs

Monitoring costs nothing up to 10,000 site checks a month, with no card. Blocking uses prepaid credits: 1 per visitor check, cached for 10 minutes, packs from $20. The 5,000 free credits to start need a card (nothing is charged until you buy a pack) and last 30 days.

Who sees your data

Servers in Denmark (EU). For each visitor we receive the IP address, the user agent and a few request headers. Security and data handling

Already using Cloudflare's AI bot settings?

Keep them. IPScanner adds VPN, Tor and data-center checks and shows every visitor before you block more than Tor and bot scripts.

Setup

Live in four steps

  1. 1

    Deploy the Worker

    Or use the Deploy button above.

    shell
    git clone https://github.com/ipscanner/ipscanner-cloudflare
    cd ipscanner-cloudflare
    npm install
    npx wrangler deploy
  2. 2

    Add your API key

    shell
    npx wrangler secret put IPSCANNER_API_KEY
  3. 3

    Create a site and set SITE_ID

    Add it under Sites in your dashboard, which shows its traffic and holds its policy.

    wrangler.jsonc
    "vars": {
      "SITE_ID": "site_4fQ8nZ2kLm7xR1vT9cBw"
    }
  4. 4

    Put it in front of your site

    On a custom domain or workers.dev, set ORIGIN_URL to your backend instead.

    wrangler.jsonc
    "routes": [{
      "pattern": "example.com/*",
      "zone_name": "example.com"
    }]

Set it and forget it

Deploy once, the Worker handles every request

Policy changes reach the edge without a redeploy, and if we are ever slow, the request goes through untouched.

Policy updatedLive at the edge, no redeploy
Origin protectedOnly allowed traffic gets through

How it works

What happens on each request

  1. 1

    The Worker reads the visitor's IP, User-Agent and JA4, when Cloudflare provides it.

  2. 2

    Agentscan and IP Detection run in parallel, cached per visitor, and fail open after 1.5 seconds.

  3. 3

    Monitor mode sends verdict headers to your origin. Block mode also answers a blocked visitor with a 403.

  4. 4

    Verified crawlers always pass, and X-IPScanner-* headers sent by the client are stripped.

Headers

Headers your origin receives

When a check fails or is skipped, only X-IPScanner-Status is set.

HeaderExample
X-IPScanner-ClassAgentscanhuman
X-IPScanner-ActionAgentscanallow
X-IPScanner-ConfidenceAgentscan0.92
X-IPScanner-Network-ClassIP Detectionresidential_clean
X-IPScanner-AnonymizedBothfalse
X-IPScanner-RiskIP Detection12
X-IPScanner-CountryIP DetectionDE
X-IPScanner-StatusWorkerok

Settings

Settings

Set these in the vars block of wrangler.jsonc.

VariableDefault
MODEmonitor adds headers, enforce also blocksmonitor
SITE_IDYour site id. Set it and the dashboard policy appliesEmpty
CHECK_AGENTRuns Agentscantrue
CHECK_IPRuns IP Detectiontrue
BLOCK_CLASSESAgentscan classes to block in enforce modemalicious_automation
BLOCK_ANONYMIZEDAlso blocks VPN, proxy and Tor in enforce modefalse
TIMEOUT_MSPer call, then the request goes through1500
AGENT_TTLSeconds to cache an Agentscan verdict600
IP_TTLSeconds to cache an IP lookup3600
POLICY_TTLSeconds a fetched policy stays fresh30
SKIP_PATHSPath regex that skips the checkStatic assets
ORIGIN_URLBackend to forward to when not on a routeEmpty

Questions

Cloudflare Worker FAQ

One credit for each uncached visitor. Repeat visits within the cache TTL use none.

Start in monitor mode

Watch the headers for a week before you block anything.

    Cloudflare Worker for Bot and VPN Checks | IPScanner