Quickstart Guide

Get up and running with Caddy Defender in just a few minutes. This guide will walk you through installation, basic configuration, and deploying your first protection strategy.

What is Caddy Defender?

Caddy Defender is a powerful middleware for Caddy that allows you to block or manipulate requests based on the client’s IP address. It’s particularly useful for:

Blocking AI scrapers from services like OpenAI, DeepSeek, and GitHub Copilot
Preventing unwanted traffic from specific cloud providers or IP ranges
Polluting AI training data by returning garbage responses
Rate limiting suspicious traffic
Protecting your content while serving legitimate users

Installation

Pull the Docker Image

The easiest way to use Caddy Defender is with the pre-built Docker image:

docker pull ghcr.io/jasonlovesdoggo/caddy-defender:latest

For other installation methods (building from source, using xcaddy, etc.), see the Installation Guide.

Create Your Caddyfile

Create a simple Caddyfile to block AI scrapers:

{
    order defender before basicauth
}

localhost:8080 {
    # Block requests from popular AI services
    defender block {
        ranges openai deepseek githubcopilot
    }

    respond "Welcome to our website!"
}

By default, if you don’t specify any ranges, Caddy Defender will block AWS, Google Cloud, Azure, OpenAI, DeepSeek, and GitHub Copilot.

Run Caddy with Docker

Start the Caddy server with your configuration:

docker run -d \
  --name caddy \
  -v $(pwd)/Caddyfile:/etc/caddy/Caddyfile \
  -p 8080:8080 \
  ghcr.io/jasonlovesdoggo/caddy-defender:latest

Replace $(pwd) with the full path to your Caddyfile directory if needed.

Verify It's Working

Test your setup by accessing the server:

curl http://localhost:8080

You should see: Welcome to our website!Requests from blocked IP ranges will receive a 403 Forbidden response.

Basic Configuration

The defender directive follows this syntax:

defender <responder> {
    ranges <ip_ranges...>
    message <custom message>
    url <redirect_url>
    whitelist <ip_addresses...>
}

Available Responders

Responder	Description	Required Fields
`block`	Returns `403 Forbidden` response	None
`custom`	Returns custom message with configurable status code	`message`
`drop`	Drops the connection without response	None
`garbage`	Returns random garbage data to pollute AI training	None
`redirect`	Returns `308 Permanent Redirect`	`url`
`ratelimit`	Marks requests for rate limiting (requires caddy-ratelimit)	None
`tarpit`	Streams data slowly to stall bots and waste resources	None

Predefined IP Ranges

Caddy Defender includes built-in IP ranges for popular services:

openai
deepseek
githubcopilot
mistral

For a complete list of available ranges and regional options (like aws-us-east-1), see the Configuration Reference.

Complete Example: Block AI Scrapers

Here’s a production-ready configuration that blocks AI scrapers while serving legitimate users:

{
    order defender before basicauth
}

example.com {
    # Block AI training scrapers
    defender block {
        ranges openai deepseek githubcopilot aws gcloud azurepubliccloud
    }

    # Serve your website
    root * /var/www/html
    file_server
}

Advanced Example: Multi-Strategy Protection

Combine multiple defense strategies for comprehensive protection:

{
    order defender before basicauth
}

example.com {
    # Strategy 1: Block known bad actors completely
    defender block {
        ranges 203.0.113.0/24
    }

    # Strategy 2: Return garbage data to AI scrapers
    defender garbage {
        ranges openai deepseek
    }

    # Strategy 3: Slow down cloud scrapers with tarpit
    defender tarpit {
        ranges aws gcloud azurepubliccloud
        tarpit_config {
            timeout 30s
            bytes_per_second 10
            response_code 200
        }
    }

    # Strategy 4: Redirect GitHub Copilot elsewhere
    defender redirect {
        ranges githubcopilot
        url "https://github.com/sponsors"
    }

    # Your actual content for legitimate users
    root * /var/www/html
    file_server
}

When using multiple defender directives, they are evaluated in order. The first matching range will handle the request.

Real-World Production Example

Here’s a complete configuration for a production website:

{
    # Global options
    email [email protected]
    order defender before basicauth
}

example.com {
    # Enable automatic HTTPS
    tls {
        protocols tls1.2 tls1.3
    }

    # Block AI scrapers from major services
    defender garbage {
        ranges openai deepseek githubcopilot mistral
        # But allow your own AWS EC2 instance
        whitelist 3.141.59.26
    }

    # Block known VPN and proxy services
    defender block {
        ranges vpn
    }

    # Rate limit cloud providers instead of blocking
    defender ratelimit {
        ranges aws gcloud azurepubliccloud
    }

    # Serve robots.txt to discourage crawlers
    handle /robots.txt {
        respond "User-agent: *\nDisallow: /"
    }

    # Your application
    reverse_proxy localhost:3000
}

Common Use Cases

Block AI Training

Prevent AI services from scraping your content for training data

Protect API Endpoints

Rate limit or block automated API access from cloud providers

Pollute Training Data

Return garbage data to confuse AI scrapers and waste their resources

Whitelist Trusted IPs

Allow specific IPs through while blocking entire ranges

Testing Your Configuration

Test from Allowed IP

Access your site normally:

curl http://localhost:8080

Expected: Your normal website content

Test Blocked Range (Simulation)

You can test blocking behavior by adding your IP to a custom range:

defender block {
    ranges 127.0.0.1/32
}

curl http://localhost:8080

Expected: 403 Forbidden response

Check Logs

Monitor Caddy logs to see which requests are being blocked:

docker logs caddy

Look for defender-related entries showing matched IP ranges.

Test Whitelisting

Verify that whitelisted IPs can still access blocked ranges:

defender block {
    ranges private
    whitelist 127.0.0.1
}

Your localhost should still have access.

Troubleshooting

Defender Not Blocking Requests

Check directive order

Ensure defender is ordered correctly in your global options:

{
    order defender before basicauth
}

The defender middleware must be processed before your content handlers.

Verify IP range syntax

IP ranges must be valid CIDR notation or predefined keys:

# Correct
ranges 192.168.1.0/24 openai

# Incorrect
ranges 192.168.1.* openai-gpt4

Use plugin.go:26 to see all predefined range keys.

Check client IP detection

If you’re behind a reverse proxy or CDN, Caddy might see the proxy’s IP instead of the client’s. Configure your reverse proxy to forward the real IP:

{
    servers {
        trusted_proxies static 10.0.0.0/8
    }
}

Accidentally Blocking Legitimate Users

Use whitelist for exceptions

If you need to block a range but allow specific IPs:

defender block {
    ranges aws
    whitelist 54.239.28.85 54.240.197.233
}

Use custom responder instead of block

Return a helpful message instead of blocking:

defender custom {
    ranges openai
    message "Please contact support for API access"
    status_code 403
}

Test before deploying

Always test your configuration locally before deploying to production to avoid locking out legitimate traffic.

Performance Issues

IP matching is highly optimized

Caddy Defender uses bart, a high-performance routing table implementation, so IP matching is extremely fast even with thousands of ranges.

Avoid excessive tarpit usage

While tarpit is great for wasting bot resources, too many concurrent tarpit connections can consume server resources:

defender tarpit {
    ranges scrapers
    tarpit_config {
        timeout 10s  # Shorter timeout
        bytes_per_second 100  # Faster to reduce connections
    }
}

Next Steps

Configuration Reference

Explore all configuration options and advanced features

All Examples

See more examples including tarpit, rate limiting, and combinations

Responder Types

Learn about all available response strategies in detail

IP Ranges

Complete list of predefined IP ranges and how to add custom ones

Need help? Check out the GitHub repository or open an issue.

Get Started

Core Concepts

Configuration

Guides

Examples

What is Caddy Defender?

Installation

Basic Configuration

Available Responders

Predefined IP Ranges

Complete Example: Block AI Scrapers

Advanced Example: Multi-Strategy Protection

Real-World Production Example

Common Use Cases

Block AI Training

Protect API Endpoints

Pollute Training Data

Whitelist Trusted IPs

Testing Your Configuration

Troubleshooting

Defender Not Blocking Requests

Accidentally Blocking Legitimate Users

Performance Issues

Next Steps

Configuration Reference

All Examples

Responder Types

IP Ranges

Build docs developers (and LLMs) love

Get Started

Core Concepts

Configuration

Guides

Examples

​What is Caddy Defender?

​Installation

​Basic Configuration

​Available Responders

​Predefined IP Ranges

​Complete Example: Block AI Scrapers

​Advanced Example: Multi-Strategy Protection

​Real-World Production Example

​Common Use Cases

Block AI Training

Protect API Endpoints

Pollute Training Data

Whitelist Trusted IPs

​Testing Your Configuration

​Troubleshooting

​Defender Not Blocking Requests

​Accidentally Blocking Legitimate Users

​Performance Issues

​Next Steps

Configuration Reference

All Examples

Responder Types

IP Ranges

Build docs developers (and LLMs) love

What is Caddy Defender?

Installation

Basic Configuration

Available Responders

Predefined IP Ranges

Complete Example: Block AI Scrapers

Advanced Example: Multi-Strategy Protection

Real-World Production Example

Common Use Cases

Testing Your Configuration

Troubleshooting

Defender Not Blocking Requests

Accidentally Blocking Legitimate Users

Performance Issues

Next Steps