Directive Syntax
Thedefender directive configures the Caddy Defender plugin to protect your site from AI scrapers, bots, and unwanted traffic. The basic syntax is:
Responder Types
The<responder> argument is required and must be one of:
block- Returns a403 Forbiddenresponse with “Access denied” messagecustom- Returns a custom message with configurable status codedrop- Drops the connection immediately (aborts handler)garbage- Returns random garbage data to pollute AI trainingratelimit- Marks requests for rate limiting (requires caddy-ratelimit)redirect- Returns a308 Permanent Redirectresponsetarpit- Streams data at a slow, configurable rate to stall bots
Configuration Options
ranges
Specifies IP ranges to block. Supports both CIDR notation and predefined service keys.Default:
["aws", "gcloud", "azurepubliccloud", "openai", "deepseek", "githubcopilot"]Examples:- CIDR:
192.168.1.0/24,10.0.0.0/8 - Predefined:
openai,aws,gcloud,vpn,tor
whitelist
IP addresses to exclude from blocking. Only supports individual IP addresses, not ranges.Default:
[]Whitelisted IPs bypass all range checks, even if they fall within blocked ranges.
message
Custom response message for the
custom responder type.Required when: Using custom responderstatus_code
HTTP status code for the
custom responder type.Default: 200Valid values: Any HTTP status code (200, 403, 404, 451, 503, etc.)url
Redirect URL for the
redirect responder type.Required when: Using redirect responderserve_ignore
Serves a robots.txt file with
Disallow: / directive to discourage crawlers.Default: falseNote: This is a flag directive with no arguments.tarpit_config
Configuration for the
tarpit responder. Controls how data is streamed to slow down bots.Required when: Using tarpit respondertarpit_config.headers
Custom HTTP headers to include in the tarpit response.Default:
{}tarpit_config.content
Content source for the tarpit response in the format
<protocol>://<path>.Supported protocols:file- Read from a local filehttp/https- Fetch from a URL (cached)- Empty - Hold connection without sending content
tarpit_config.timeout
Maximum duration before forcefully closing the connection.Default:
30sFormat: Duration string (e.g., 30s, 5m, 1h30m)Validation: Must be greater than 0tarpit_config.bytes_per_second
Number of bytes to stream per second. Lower values slow down bots more effectively.Default:
24Validation: Must be greater than 10tarpit_config.response_code
HTTP response code for the tarpit response.Default:
200Complete Examples
Block OpenAI and AWS
Custom Message with 403 Status
Tarpit Configuration with File Content
Redirect with Whitelist
Multiple Defenders for Different Strategies
Serve robots.txt Disallow
Predefined IP Ranges
See the IP Ranges documentation for a complete list of predefined service keys including:- Cloud providers:
aws,gcloud,azurepubliccloud,oci,aliyun - AI services:
openai,deepseek,githubcopilot,mistral - VPN/Privacy:
vpn,tor(requires build-time configuration) - CDNs:
cloudflare,digitalocean,linode,vultr - Special:
all,private
Source Code Reference
The Caddyfile configuration is parsed inconfig.go:39-159 (UnmarshalCaddyfile function).