caddy-waf/docs

🛡️ Caddy WAF Middleware

A robust, highly customizable, and feature-rich Web Application Firewall (WAF) middleware for the Caddy web server. This middleware provides advanced protection against a comprehensive range of web-based threats, seamlessly integrating with Caddy and offering flexible configuration options to secure your applications effectively.

📑 Table of Contents

1. • Configuration Options
2. • Rules Format
3. • Metrics
4. • Protected Attack Types
5. • Blacklist Formats
6. • Rate Limiting
7. • Country Blocking and Whitelisting
8. • Dynamic Updates
9. • Testing
10. • Docker Support
11. • Rule/Blacklist Population Scripts
12. • Prometheus Metrics

---

🚀 Installation

# Step 1: Clone the caddy-waf repository from GitHub
git clone https://github.com/fabriziosalmi/caddy-waf.git

# Step 2: Navigate into the caddy-waf directory
cd caddy-waf

# Step 3: Clean up and update the go.mod file
go mod tidy

# Step 4: Fetch and install the required Go modules
go get github.com/caddyserver/caddy/v2
go get github.com/caddyserver/caddy/v2/caddyconfig/caddyfile
go get github.com/caddyserver/caddy/v2/caddyconfig/httpcaddyfile
go get github.com/caddyserver/caddy/v2/modules/caddyhttp
go get github.com/oschwald/maxminddb-golang
go get github.com/fsnotify/fsnotify
go get -v github.com/fabriziosalmi/caddy-waf
go mod tidy

# Step 5: Download the GeoLite2 Country database (required for country blocking/whitelisting)
wget https://git.io/GeoLite2-Country.mmdb

# Step 6: Build Caddy with the caddy-waf module
xcaddy build --with github.com/fabriziosalmi/caddy-waf=./

# Step 7: Fix Caddyfile format
caddy fmt --overwrite

# Step 8: Run the compiled Caddy server
./caddy run

---

🛠️ Basic Configuration

Here's a minimal Caddyfile example to get started:

{
    auto_https off
    admin localhost:2019
}

:8080 {
    log {
        output stdout
        format console
        level INFO
    }

    handle {
        header -Server
    }

    route {
        # WAF Plugin runs on all requests first
        waf {
            metrics_endpoint /waf_metrics
            rule_file rules.json
            ip_blacklist_file ip_blacklist.txt
            dns_blacklist_file dns_blacklist.txt
        }

        # Match the waf metrics endpoint specifically and stop processing
        @wafmetrics path /waf_metrics
        handle @wafmetrics {
            # Do not respond here so it goes to the WAF plugin
        }

        # All other requests, respond with "Hello World"
        handle {
            respond "Hello world!" 200
        }
    }
}

For more detailed configuration options, rules format, and usage instructions, please refer to the Full Documentation.

---

📚 Full Documentation

The detailed documentation for this project is organized into the following sections:

• Configuration Options - Detailed description of all the WAF settings.
• Rules Format - Information on the rules syntax and structure.
• Metrics - How to use the metrics endpoint.
• Protected Attack Types - List of attacks the WAF protects against.
• Blacklist Formats - Explanation of the format for IP and DNS blacklist files.
• Rate Limiting - How to configure rate limits.
• Country Blocking and Whitelisting - How to use GeoIP for country filtering.
• Dynamic Updates - How to dynamically reload configurations.
• Testing - Instructions for testing the WAF setup.
• Docker Support - How to run the WAF in Docker.
• Rule/Blacklist Population Scripts - Information on the helper scripts.
  • Prometheus Metrics - How to use the prometheus endpoint.

---

📜 License

This project is licensed under the AGPLv3 License.

---

🙏 Contributing