Cloudflare Bot Filter Worker

Cloudflare Bot Filter Worker

A production-ready Cloudflare Worker that scores every incoming request against a multi-signal heuristic and blocks malicious bots before they reach your origin. Legitimate crawlers pass through automatically. Scoring thresholds, allowlists, and blocklists are all configurable via Cloudflare KV — update rules instantly without redeploying.

What's Included

• Bot Scoring Engine — Multi-signal request scoring: User-Agent fingerprint, known bot signatures, ASN reputation, header anomaly detection, and request pattern analysis
• Crawler Allowlist — Pre-configured to pass Googlebot, Bingbot, DuckDuckBot, Slack, and other legitimate crawlers with optional IP verification for Google and Bing
• KV-Based Configuration — Scoring thresholds, custom allowlists, blocklists, and per-path rules stored in Cloudflare KV; update in real time without redeployment
• Structured Logging — Every request logs its score breakdown, action taken, and client metadata for debugging and analytics

How Scoring Works

• Each request starts at a neutral score of 0
• Signals add or subtract points: missing Accept headers (+15), known bad UA patterns (+30), residential ASN (-10), verified crawler (-100)
• Requests exceeding the block threshold (default 50) get a 403; requests between warn and block thresholds are challenged or logged
• All thresholds and signal weights are configurable in KV — tune for your traffic patterns

What You Get

• src/index.js — Main Worker entry point with request handling and routing
• src/scoring.js — Scoring engine with all signal evaluators
• src/crawlers.js — Legitimate crawler definitions and IP verification logic
• src/config.js — Default thresholds and signal weights (overridden by KV at runtime)
• wrangler.toml — Pre-configured Wrangler deployment config with KV namespace bindings
• scripts/seed-kv.js — Seeds your KV namespace with default config, allowlists, and blocklists
• package.json — Wrangler CLI dependency and deploy/dev/seed scripts
• .env.example — Cloudflare account ID and API token placeholders
• README.md — Setup guide, KV config reference, scoring tuning walkthrough, and deployment instructions

Deployment

Requirements

A Cloudflare account with Workers enabled (free tier supports 100k requests/day). Node.js 20+ for the Wrangler CLI. One KV namespace (created automatically by wrangler on first deploy).