Overview
Caddy Defender uses IP ranges to determine which requests to block. You can specify IP ranges in two ways:- Predefined ranges: Named collections of IPs for popular cloud providers, AI services, and networks
- Custom CIDR ranges: Manual CIDR notation for specific IP blocks
ranges directive and can be mixed together in any combination.
Default Ranges
If you don’t specify any ranges, Caddy Defender uses these defaults:plugin.go:27
These defaults are designed to block common AI scrapers and cloud provider IPs by default. Explicitly specify
ranges to override this behavior.How IP Matching Works
When a request arrives, Caddy Defender:- Extracts the client IP from the request’s
RemoteAddr - Checks the whitelist - if the IP is whitelisted, the request is immediately allowed
- Checks blocked ranges - looks up the IP in a BART table containing all configured ranges
- Uses caching - IP lookup results are cached for 10 minutes for performance
- Handles IPv4-mapped IPv6 - automatically normalizes IPv4 addresses in IPv6 format
matchers/ip/ip.go:65-82
Predefined Ranges
Predefined ranges are automatically fetched and embedded at build time. They’re stored inranges/data/generated.go and updated by running the generator in ranges/main.go.
Cloud Providers
AWS
Key:
awsGlobal Amazon Web Services IP ranges across all regions and services.Source: AWS IP ranges APIGoogle Cloud
Key:
gcloudGoogle Cloud Platform IP ranges globally.Source: Google Cloud JSON feedsAzure
Key:
azurepubliccloudMicrosoft Azure public cloud IP ranges.Source: Azure service tagsCloudflare
Key:
cloudflareCloudflare edge network IPs.DigitalOcean
Key:
digitaloceanDigitalOcean cloud infrastructure IPs.Linode
Key:
linodeLinode/Akamai cloud IPs.Oracle Cloud
Key:
oracleOracle Cloud Infrastructure IPs.Vultr
Key:
vultrVultr cloud hosting IPs.Alibaba Cloud
Key:
aliyunAlibaba Cloud (Aliyun) IP ranges.Huawei Cloud
Key:
huaweiHuawei Cloud IP ranges.AI Services
OpenAI
Key:
openaiOpenAI services including ChatGPT, GPTBot, and SearchBot.Source: openai.com/searchbot.json, chatgpt-user.json, gptbot.jsonFrom ranges/fetchers/openai.go:20-36DeepSeek
Key:
deepseekDeepSeek AI crawler IP ranges.Mistral AI
Key:
mistralMistral AI service IPs.GitHub Copilot
Key:
githubcopilotGitHub Copilot service IPs from GitHub’s meta API.Source: api.github.com/metaFrom ranges/fetchers/github.go:23-24Network Types
Tor Exit Nodes
Key:
torKnown Tor exit node IP addresses.Source: CDN-hosted Tor exit list (CSV format)Converts individual IPs to /32 (IPv4) or /128 (IPv6) CIDR notation.From ranges/fetchers/tor.go:23-24VPN Services
Key:
vpnKnown VPN service provider IP ranges.Source: Community-maintained VPN IP listFrom ranges/fetchers/vpn.go:22Private Networks
Key:
privateRFC 1918 private network ranges:127.0.0.0/8(loopback)::1/128(IPv6 loopback)10.0.0.0/8172.16.0.0/12192.168.0.0/16fd00::/8(IPv6 private)
ranges/fetchers/private.go:13-20All IPs
Key:
allEvery IP address in existence:0.0.0.0/0(all IPv4)::/0(all IPv6)
ranges/fetchers/all.go:12-16Custom CIDR Ranges
You can specify custom IP ranges using standard CIDR notation alongside predefined ranges.CIDR Validation
Custom CIDR ranges are validated during configuration: Source Code:config.go:228-240
Examples
- Caddyfile
- JSON
ASN-Based Blocking
You can block entire Autonomous System Numbers (ASNs) using the ASN fetcher: Source Code:ranges/fetchers/asn.go:24-62
ASN blocking requires creating a custom fetcher. It’s not available as a predefined range key because ASNs must be specified individually.
AS followed by the number (e.g., AS15169 for Google).
Regional Cloud Blocking
Some cloud providers support region-specific blocking:AWS Regions
aws key fetches all global ranges.
Range Storage and Updates
Predefined ranges are:- Fetched at build time by running
go run ranges/main.go - Embedded in the binary at
ranges/data/generated.go - Loaded into memory as a map during plugin initialization
- Expanded into a BART table for efficient lookups
ranges/data/generated.go:5:
To update predefined ranges, rebuild the plugin after running the range generator. This ensures you have the latest IP ranges from all providers.
Performance Considerations
BART Table Indexing
Ranges are loaded into a BART (Binary Address Routing Table) for O(log n) lookup performance: Source Code:matchers/ip/ip.go:99-121
Caching
IP lookups are cached using sturdyc with:- Capacity: 10,000 entries
- TTL: 10 minutes
- Sharding: 10 shards for concurrency
- Early refresh: Prevents thundering herd
matchers/ip/ip.go:26-34
IPv4-Mapped IPv6
The system automatically handles IPv4 addresses in IPv6 format:matchers/ip/ip.go:123-147
Complete Range List
Available predefined range keys:| Key | Type | Description |
|---|---|---|
all | Special | All IPv4 and IPv6 addresses |
aliyun | Cloud | Alibaba Cloud |
aws | Cloud | Amazon Web Services (global) |
azurepubliccloud | Cloud | Microsoft Azure |
cloudflare | Cloud | Cloudflare network |
deepseek | AI | DeepSeek AI |
digitalocean | Cloud | DigitalOcean |
gcloud | Cloud | Google Cloud Platform |
githubcopilot | AI | GitHub Copilot |
huawei | Cloud | Huawei Cloud |
linode | Cloud | Linode/Akamai |
mistral | AI | Mistral AI |
openai | AI | OpenAI (GPTBot, ChatGPT, SearchBot) |
oracle | Cloud | Oracle Cloud |
private | Network | RFC 1918 private networks |
tor | Network | Tor exit nodes |
vpn | Network | Known VPN services |
vultr | Cloud | Vultr hosting |
Source: All fetchers in
ranges/fetchers/ directory