Skip to main content

​
Introduction to Caddy Defender

Caddy Defender is a middleware plugin for Caddy that allows you to block or manipulate requests based on the client’s IP address. It’s particularly useful for preventing unwanted traffic from AI scrapers, bots, and specific IP ranges while maintaining legitimate user access.

IP Range Filtering

Block or manipulate requests from specific IP ranges using CIDR notation or predefined service keys

AI Service Blocking

Pre-configured IP ranges for popular AI services like OpenAI, DeepSeek, GitHub Copilot, and more

Multiple Response Strategies

Choose from block, custom messages, drop connections, garbage data, redirects, rate limiting, or tarpit

Custom IP Ranges

Add your own IP ranges via Caddyfile configuration alongside predefined ranges

​
Key Features

​
Embedded IP Ranges

Caddy Defender includes predefined IP ranges for popular AI services and cloud providers. These ranges are embedded in the binary and can be used without additional configuration:
  • AI Services: OpenAI, DeepSeek, GitHub Copilot, Mistral
  • Cloud Providers: AWS (including regional filters), Google Cloud, Azure, Oracle Cloud, Alibaba Cloud
  • CDNs & Hosting: Cloudflare, DigitalOcean, Vultr, Linode
  • Special Ranges: VPNs, Tor exit nodes, private networks, all IPs
The default ranges (if none specified) are: aws, gcloud, azurepubliccloud, openai, deepseek, and githubcopilot.

​
Response Strategies

Caddy Defender supports multiple responder backends to handle blocked requests:
ResponderDescription
blockReturn a 403 Forbidden response
customReturn a custom message with configurable status code
dropDrop the connection immediately
garbageReturn random garbage data to pollute AI training
redirectReturn a 308 Permanent Redirect to a custom URL
ratelimitMark requests for rate limiting (requires caddy-ratelimit)
tarpitStream data slowly to stall bots and waste resources

​
Whitelisting Support

You can whitelist specific IP addresses to bypass blocking rules, even if they’re within a blocked range. This is useful for allowing your own infrastructure while blocking the rest of a cloud provider’s IPs.

​
Use Cases

Prevent AI Training Data Theft

Block AI scrapers from crawling your content or return garbage data to pollute their training datasets

Reduce Cloud Costs

Block unnecessary traffic from cloud providers and reduce bandwidth costs

Protect Private Content

Restrict access to specific IP ranges for internal or region-specific content

Slow Down Bots

Use tarpit to waste bot resources by streaming data at extremely slow rates

​
Quick Navigation

Installation

Get started with Docker, xcaddy, or binary downloads

Quickstart

Set up your first Caddy Defender configuration in minutes

Examples

Browse real-world configuration examples and use cases

​
How It Works

Caddy Defender operates as an HTTP middleware handler that:
  1. Extracts the client’s IP address from incoming requests
  2. Checks if the IP matches any configured ranges (CIDR or predefined keys)
  3. Applies whitelist rules to allow specific IPs to bypass blocking
  4. Executes the configured responder strategy for matched IPs
  5. Allows the request to proceed normally if no rules match
Caddy Defender uses bart, a highly efficient routing table implementation based on Balanced ART, enabling high-performance IP matching even with large IP range lists.

​
Configuration Overview

The defender directive uses this basic syntax: 
defender <responder> {
    ranges <ip_ranges...>
    message <custom message>  # For 'custom' responder
    url <url>                 # For 'redirect' responder
    whitelist <ips...>        # Optional IP whitelist
}
For detailed configuration options, see the Configuration page.

​
Performance

Caddy Defender is designed for high performance:
  • IP range matching uses an optimized Balanced ART data structure
  • Predefined IP ranges are embedded at build time
  • Minimal overhead on requests that don’t match any rules
  • Efficient memory usage even with thousands of IP ranges

​
Next Steps

1

Install Caddy Defender

Follow the Installation guide to add Caddy Defender to your Caddy server
2

Try the Quickstart

Complete the Quickstart to block AI scrapers in under 5 minutes
3

Explore Advanced Features

Check out Examples and Advanced Build for more complex use cases

Build docs developers (and LLMs) love

Get started for freeTalk to us