Caddy Defender Plugin

The Caddy Defender plugin is a middleware for Caddy that allows you to block or manipulate requests based on the client's IP address. It is particularly useful for preventing unwanted traffic or polluting AI training data by returning garbage responses.

---

Features

• IP Range Filtering: Block or manipulate requests from specific IP ranges.
• Embedded IP Ranges: Predefined IP ranges for popular AI services (e.g., OpenAI, DeepSeek, GitHub Copilot).
• Custom IP Ranges: Add your own IP ranges via Caddyfile configuration.
• Multiple Responder Backends:
  • Block: Return a 403 Forbidden response.
  • Garbage: Return garbage data to pollute AI training.
  • Custom: Return a custom message.

---

Installation

Using Docker

The easiest way to use the Caddy Defender plugin is by using the pre-built Docker image.

1. Pull the Docker Image:

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

2. Run the Container: Use the following command to run the container with your Caddyfile:

   docker run -d \
     --name caddy \
     -v /path/to/Caddyfile:/etc/caddy/Caddyfile \
     -p 80:80 -p 443:443 \
     ghcr.io/jasonlovesdoggo/caddy-defender:latest

   Replace /path/to/Caddyfile with the path to your Caddyfile.

---

Using xcaddy

You can also build Caddy with the Caddy Defender plugin using xcaddy, a tool for building custom Caddy binaries.

1. Install xcaddy:

   go install github.com/caddyserver/xcaddy/cmd/xcaddy@latest

2. Build Caddy with the Plugin: Run the following command to build Caddy with the Caddy Defender plugin:

   xcaddy build --with github.com/jasonlovesdoggo/caddy-defender

   This will produce a caddy binary in the current directory.

3. Run Caddy: Use the built binary to run Caddy with your configuration:

   ./caddy run --config Caddyfile

---

Configuration

Caddyfile Syntax

The defender directive is used to configure the Caddy Defender plugin. It has the following syntax:

defender <responder> {
    message <custom message>
    range <ip_ranges...>
}

• <responder>: The responder backend to use. Supported values are:
  • block: Returns a 403 Forbidden response.
  • garbage: Returns garbage data to pollute AI training.
  • custom: Returns a custom message (requires responder_args).
• <ip_ranges...>: A list of CIDR ranges or predefined range keys (e.g., openai, localhost) to match against the client's IP.
• <custom message>: A custom message to return when using the custom responder.

Ordering the Middleware

To ensure the defender middleware runs before other middleware (e.g., basicauth), add the following to your global configuration:

{
    order defender before basicauth
}

---

Examples

Block Requests

Block requests from specific IP ranges:

localhost:8080 {
    defender block {
        range 203.0.113.0/24 openai 198.51.100.0/24 
    } 
    respond "Hello, world!" # what humans see
}

Return Garbage Data

Return garbage data for requests from specific IP ranges:

localhost:8081 {
    defender garbage {
        range 192.168.0.0/24 
    }
    respond "Hello, world!" # what humans see
}

Custom Response

Return a custom message for requests from specific IP ranges:

localhost:8082 {
    defender custom {
        message "Custom response message"
        range 10.0.0.0/8
    } 
    respond "Hello, world!" # what humans see
} 

---

Embedded IP Ranges

The plugin includes predefined IP ranges for popular AI services. These ranges are embedded in the binary and can be used without additional configuration.

Service	IP Ranges
OpenAI	openai.go
DeepSeek	deepseek.go
GitHub Copilot	github.go
Microsoft Azure	azure.go
Localhost (testing)	localhost.go

More are welcome! for a precompiled list, see the embedded results

Contributing

We welcome contributions! Here’s how you can get started:

Adding New IP Ranges

To add new IP ranges, you need to create a new fetcher in the ranges/fetchers package. Follow the steps in the Contributing Guide.

Adding a New Responder

To add a new responder, you need to create a new responder in the responders package and update the UnmarshalCaddyfile method in the Defender struct to handle the new responder. Follow the steps in the Contributing Guide.

---

License

This project is licensed under the MIT License. See the LICENSE file for details.

---

Acknowledgments

• The inspiration for this project.
• Built with ❤️ using Caddy.

Star History