Skip to main content
Some IP range fetchers are not enabled by default in the standard Caddy Defender build. This guide shows you how to build custom binaries with additional features like Tor exit node blocking and ASN-based filtering.

​
Why Advanced Builds?

By default, Caddy Defender includes IP ranges for major cloud providers and AI services. However, some features require build-time configuration:
  • Tor exit nodes: Dynamic list of Tor network exit points
  • ASN filtering: Block entire Autonomous System Numbers (ISPs, hosting providers)
These features are optional because:
  • They can significantly increase binary size
  • They require user-specific configuration (ASN numbers)
  • They may impact build time

​
Build-Time IP Range Fetchers

Caddy Defender uses a Go program at ranges/main.go to fetch and embed IP ranges at build time. This ensures fast runtime performance without external API calls.

​
Available Fetchers

Tor Exit Nodes

Block traffic from Tor network exit points

ASN Ranges

Block entire autonomous systems by ASN number

​
Building with Tor Support

1

Clone the Repository

First, clone the Caddy Defender source code:
git clone https://github.com/JasonLovesDoggo/caddy-defender.git
cd caddy-defender
2

Run IP Range Generator with Tor

Execute the range generator with the --fetch-tor flag:
go run ranges/main.go --fetch-tor
This regenerates ranges/data/generated.go with Tor exit node IP ranges included under the tor key.
The Tor fetcher converts individual node IPs to IP ranges for efficient storage and lookup.
3

Build with xcaddy

Build the Caddy binary with your custom-generated data:
xcaddy build --with pkg.jsn.cam/caddy-defender=$(pwd)
The $(pwd) tells xcaddy to use your local copy with the regenerated IP ranges.
4

Use in Caddyfile

Now you can use the tor key in your configuration:
example.com {
    defender block {
        ranges tor openai
    }
    respond "Protected from Tor and AI crawlers!"
}

​
Building with ASN Support

ASN (Autonomous System Number) filtering allows you to block entire networks operated by specific organizations.
1

Identify Target ASNs

Determine which ASNs you want to block. Common examples:
  • AS15169: Google
  • AS13335: Cloudflare
  • AS16509: Amazon AWS
  • AS8075: Microsoft
  • AS14061: DigitalOcean
Use Hurricane Electric’s BGP Toolkit to look up ASNs for specific organizations.
2

Run Generator with ASN List

Use the --asn flag with a comma-separated list of ASNs:
go run ranges/main.go --asn "AS15169,AS13335"
This adds IP ranges for Google and Cloudflare to the asn key in the generated data.
3

Build the Binary

xcaddy build --with pkg.jsn.cam/caddy-defender=$(pwd)
4

Configure in Caddyfile

Use the asn key to block the specified autonomous systems:
example.com {
    defender block {
        ranges asn
    }
    respond "ASN-based blocking enabled"
}

​
Combining Multiple Fetchers

You can enable both Tor and ASN fetchers in a single build: 
go run ranges/main.go --fetch-tor --asn "AS15169,AS13335,AS16509"
This generates data with both tor and asn keys available: 
example.com {
    defender block {
        ranges tor asn openai aws
    }
    respond "Maximum protection enabled!"
}

​
Building with Docker

For production deployments, build a custom Docker image with your desired fetchers: 
FROM caddy:builder AS builder

# Install xcaddy
RUN go install github.com/caddyserver/xcaddy/cmd/xcaddy@latest

# Clone the repository
WORKDIR /app
RUN git clone https://github.com/JasonLovesDoggo/caddy-defender.git

# Generate IP ranges with Tor support
WORKDIR /app/caddy-defender
RUN go run ranges/main.go --fetch-tor

# Build Caddy with custom data
RUN xcaddy build --with pkg.jsn.cam/caddy-defender=/app/caddy-defender

# Final image
FROM caddy:latest
COPY --from=builder /app/caddy-defender/caddy /usr/bin/caddy
Build and run the custom image: 
# Build the image
docker build -t caddy-defender-custom .

# Run the container
docker run -d \
  --name caddy \
  -v /path/to/Caddyfile:/etc/caddy/Caddyfile \
  -p 80:80 -p 443:443 \
  caddy-defender-custom

​
Generator Command Reference

The ranges/main.go program supports several flags:
FlagDescriptionExample
--fetch-torEnable Tor exit node fetching--fetch-tor
--asnComma-separated ASN list--asn "AS15169,AS13335"
--formatOutput format (go or json)--format json
--outputOutput file path--output custom.go

​
Output Formats

Go format (default): 
go run ranges/main.go --fetch-tor --format go
Generates ranges/data/generated.go for embedding in the binary. JSON format: 
go run ranges/main.go --asn "AS15169" --format json --output ranges.json
Generates a JSON file for external consumption or inspection.

​
Performance Considerations

Enabling Tor and ASN fetchers increases binary size and build time. Consider the trade-offs for your use case.

​
Binary Size Impact

  • Standard build: ~45-50 MB
  • With Tor: +5-10 MB
  • With ASN (5 ASNs): +2-5 MB per ASN
  • With both: Varies based on ASN count

​
Build Time Impact

  • Standard build: 1-2 minutes
  • With Tor: +30-60 seconds (fetching exit node list)
  • With ASN: +10-30 seconds per ASN (fetching BGP data)

​
Runtime Performance

Runtime performance is not affected by additional IP ranges. All lookups use the high-performance BART (Balanced ART) data structure, maintaining O(log n) complexity regardless of range count.

​
When to Use Advanced Builds

​
Use Tor Blocking When:

  • You need to prevent anonymous access
  • Your service is targeted by Tor-based scrapers
  • Compliance requires blocking anonymizing networks
  • You operate a regional service with geo-restrictions

​
Use ASN Blocking When:

  • You want to block entire hosting providers
  • You need to prevent datacenter-based scraping
  • You have specific ASN-based threat intelligence
  • You want granular control over cloud provider access

​
Skip Advanced Builds If:

  • You only need to block major AI services (use default build)
  • Binary size is a critical constraint
  • You need fast CI/CD build times
  • You prefer runtime-configurable IP lists

​
Updating IP Ranges

IP ranges change over time. To update:
1

Pull Latest Source

cd caddy-defender
git pull origin main
2

Regenerate Ranges

go run ranges/main.go --fetch-tor --asn "AS15169,AS13335"
3

Rebuild Binary

xcaddy build --with pkg.jsn.cam/caddy-defender=$(pwd)
4

Deploy Updated Binary

sudo systemctl stop caddy
sudo mv caddy /usr/local/bin/
sudo systemctl start caddy
Automate this process with a monthly cron job to keep IP ranges current.

​
Troubleshooting

​
Generator Fails to Fetch Data

If the range generator fails: 
# Check your internet connection
ping 8.8.8.8

# Verify Go can fetch modules
go env -w GOPROXY=https://proxy.golang.org,direct

# Retry with verbose output
go run ranges/main.go --fetch-tor -v

​
Invalid ASN Format

ASNs must be prefixed with “AS”: 
# Correct
go run ranges/main.go --asn "AS15169,AS13335"

# Incorrect
go run ranges/main.go --asn "15169,13335"

​
Generated File Not Found

Ensure you’re building from the repository root: 
cd caddy-defender
ls ranges/data/generated.go  # Should exist after running generator
xcaddy build --with pkg.jsn.cam/caddy-defender=$(pwd)

​
Next Steps

Configuration

Learn how to configure the Defender plugin

Examples

See real-world configuration examples

Build docs developers (and LLMs) love

Get started for freeTalk to us