Caddy-Warden for Caddy

Caddy-Warden (github.com/routewarden/caddy-warden) is the official Caddy v2 security module. It provides native sensitive path protection, path anti-evasion normalization, IP allowlisting, and active deception defenses to Caddy web servers.

---

Capabilities Overview

• Native Caddy v2 Handler: Implements Caddy's caddyhttp.MiddlewareHandler interface with zero-allocation path inspection.
• Zero-Config File Shielding: Blocks .env, .git, .aws, .ssh, .sql, database dumps, and server diagnostic endpoints out-of-the-box (enable_default_patterns).
• Anti-Evasion Normalization: Transparently strips semicolon parameters (/;param/.env), resolves percent-encoded dots (%252e), normalizes Windows backslashes (\), and strips null bytes.
• Dual Configuration Support: Fully configurable via standard Caddyfile directives or Caddy's dynamic JSON REST API (/load or /config/apps/http/servers).
• Active Defense Modes: Respond with custom JSON errors, branded HTML, interactive Turnstile/hCaptcha challenges, silent drops, or bot-neutralizing Gzip Bombs.

---

Quick Navigation

Guide	Description
Getting Started	Build Caddy with xcaddy or run with Docker.
Caddyfile Reference	Directive ordering, syntax schema, and configuration options.
JSON API Reference	Native Caddy REST API schema and zero-downtime reconfiguration.
Caddy Recipes & Examples	Real-world Caddyfile recipes (Honeypot bombs, Turnstile, VPN allowlists).

---

Installation & Setup

Build a custom Caddy binary with caddy-warden or run via Docker:

Diff

# docker-compose.ymlservices:  caddy:    build:      context: .      dockerfile_inline: |        FROM caddy:2-builder AS builder        RUN xcaddy build --with github.com/routewarden/caddy-warden@v1.2.1        FROM caddy:2-alpine        COPY --from=builder /usr/bin/caddy /usr/bin/caddy    ports:      - "80:80"      - "443:443"    volumes:      - ./Caddyfile:/etc/caddy/Caddyfile:ro      - caddy_data:/data      - caddy_config:/configvolumes:  caddy_data:  caddy_config:

---

30-Second Quick Start

Add RouteWarden directives to your Caddyfile or JSON API:

Diff

{    order route_warden before reverse_proxy}example.com {    route_warden {        enable_default_patterns true    }    reverse_proxy localhost:8080}