High-Performance Edge Defense for Traefik, Caddy & NGINX

---

RouteWarden Documentation

This repository contains the documentation, deployment guides, examples, and release references for RouteWarden across Traefik, Caddy, and NGINX & OpenResty.

• Documentation Portal: https://routewarden.github.io/docs/
• Interactive Playground: https://routewarden.github.io/docs/?playground=open

---

Ecosystem Links

Resource	Link	Description
Interactive Playground	routewarden.github.io/docs/?playground=open	Test URLs against normalization rules and generate gateway configs
Traefik Plugin (traefik-warden)	github.com/routewarden/traefik-warden	Pure Go Traefik plugin with Yaegi compatibility
Caddy Plugin (caddy-warden)	github.com/routewarden/caddy-warden	Official Caddy v2 security module and Caddyfile directive
NGINX Plugin (nginx-warden)	github.com/routewarden/nginx-warden	High-performance Lua security module for NGINX & OpenResty
Traefik Plugin Catalog	plugins.traefik.io	Official Traefik Plugin listing
Documentation Portal	routewarden.github.io/docs	Installation guides, architecture, and configuration options
Examples Cookbook	Documentation Examples	Ready-to-use Docker Compose and Kubernetes configurations
Issue Tracker	RouteWarden Issues	Bug reports and feature discussions

---

What is RouteWarden?

RouteWarden is a lightweight, zero-dependency security middleware for Traefik, Caddy v2, and NGINX / OpenResty. It inspects incoming HTTP requests at the reverse proxy layer and blocks unauthorized attempts to reach sensitive files, hidden directories, or administrative endpoints before requests reach your application containers:

• Sensitive Path Protection: Blocks access to .env, .git, .aws, .ssh, .sql, database dumps, and server configuration files (enableDefaultPatterns: true / enable_default_patterns).
• Anti-Evasion Normalization: Resolves multi-layer URL encoding (%252e%252e), semicolon matrix parameters (/;param/.env), backslashes (\), and null bytes (%00) before evaluating rules.
• IP and Subnet Allowlisting: Lets corporate VPNs, internal networks, or trusted IP addresses bypass checks using X-Forwarded-For, X-Real-IP, or client socket addresses.
• 13 Configurable Response Modes: Returns custom JSON, static HTML error pages, Cloudflare Turnstile / hCaptcha challenges, immediate TCP resets (silentDrop), gzip bombs, or honeypot redirects.
• Interactive Playground: Test URL patterns, inspect anti-evasion transformations, and generate gateway configurations directly in your browser.

Interactive Playground Deeplinks

You can test how RouteWarden processes and normalizes requests using these sample links:

• Double URL-Encoded Traversal (/%252e%252e/.env)
• Matrix Semicolon Evasion (/static;p=1/.git/config)
• Allowlist Override (/robots.txt)
• Gzip Bomb Active Response (/backup.sql)
• IP Allowlist Bypass (/.env from 10.5.0.25)

Quick Usage

Traefik

# traefik.yml (Static Configuration)
experimental:
  plugins:
    routewarden:
      moduleName: github.com/routewarden/traefik-warden
      version: v1.2.1

# dynamic_conf.yml (Dynamic Configuration)
http:
  middlewares:
    shield:
      plugin:
        routewarden:
          enabled: true
          enableDefaultPatterns: true
          response:
            mode: json
            statusCode: 404
            body: '{"error":"Not Found"}'

Caddy

Build Caddy with xcaddy:

xcaddy build --with github.com/routewarden/caddy-warden@v1.2.1

Configure Caddyfile:

{
    order route_warden before reverse_proxy
}

:80 {
    route_warden {
        enable_default_patterns
        response {
            mode json
            status_code 404
            body "{\"error\":\"Not Found\"}"
        }
    }
    reverse_proxy app:8080
}

NGINX & OpenResty

Configure nginx.conf:

http {
    lua_package_path "/usr/local/openresty/site/lualib/?.lua;/etc/nginx/lua/lib/?.lua;;";

    init_by_lua_block {
        local routewarden = require("resty.routewarden")
        warden = routewarden.new({
            enabled = true,
            enable_default_patterns = true,
            response = {
                mode = "json",
                status_code = 404,
                body = '{"error":"Not Found"}'
            }
        })
    }

    server {
        listen 80;

        access_by_lua_block {
            warden:check()
        }

        location / {
            proxy_pass http://app:8080;
        }
    }
}

---

Developing Documentation Locally

The documentation is powered by VitePress.

Prerequisites

• Node.js 18+ (Node.js 22 recommended)
• npm 9+

Quick Start

# 1. Clone the docs repository
git clone https://github.com/routewarden/docs.git routewarden-docs
cd routewarden-docs

# 2. Install dependencies
npm install

# 3. Start local development server
npm run docs:dev

Open http://localhost:5173/docs/ in your browser.

Available Scripts

Command	Description
npm run docs:dev	Starts the VitePress live-reload development server
npm run docs:build	Validates markdown links and compiles the static site into docs/.vitepress/dist
npm run docs:preview	Locally previews the compiled production build
npm run sync-version	Syncs docs/version.json with repository package.json
npm run docs:release <version>	Generates a versioned snapshot (e.g. npm run docs:release v0.3.0)
npm test	Runs internal Node.js unit tests for scripts

---

Contributing

Contributions to improve RouteWarden's documentation, case studies, and guides are welcomed.

1. Fork this repository.
2. Create your feature branch (git checkout -b feature/new-case-study).
3. Validate tests and build locally:

   npm test
   npm run docs:build

4. Commit your changes and open a Pull Request against develop.

---

License

This documentation and RouteWarden are open-source software licensed under the MIT License.