Getting Started with RouteWarden

RouteWarden is a high-performance Traefik middleware plugin written in pure Go, designed to intercept and block unauthorized reconnaissance, directory probing, and access to sensitive files before requests ever hit your backend services.

---

Key Capabilities

• Automated Sensitive Asset Shielding: Blocks attempts to access environment configurations (.env), VCS repositories (.git, .svn), credentials (.aws, .ssh), database dumps (.sql, .bak), application configurations (.yaml, .conf, .ini), and debug panels (phpinfo.php, /actuator).
• Anti-Evasion Engine: Proactively detects and decodes layered URL encoding tricks (%252e%252e), semicolon path matrix parameters (/;param/.env), backslash separators (\..\), and null bytes (%00).
• IP & CIDR Subnet Allowlisting: Exempts internal networks, VPN gateways, and developer machines from path blocking.
• Custom Responses & Captcha: Return custom JSON error structures, custom branded HTML 404 pages, or challenge clients via Cloudflare Turnstile, hCaptcha, or reCAPTCHA.

---

Supported Traefik Versions

Traefik Version	Compatibility	Notes
Traefik v3.x (v3.0, v3.1, v3.2+)	Supported	Full support for Traefik v3 runtime, CLI flags, Docker Compose labels, and IngressRoute CRDs.
Traefik v2.x (v2.8 – v2.11+)	Supported	Fully compatible with Traefik v2 plugin mechanism.
Traefik v1.x	Not Supported	External Yaegi middleware plugins are not available in Traefik v1.

---

Installation & Traefik Setup

1. Static Configuration

Declare RouteWarden in Traefik's plugins configuration:

Diff

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

Local Development (localPlugins):

When testing locally without pulling from GitHub or Traefik Pilot, register the plugin in localPlugins:

Diff

# traefik.yml (Local Development)experimental:  localPlugins:    routewarden:      moduleName: github.com/routewarden/traefik-warden

---

2. Dynamic Configuration

In Traefik, middlewares, routers, and services are defined in dynamic configuration (via file provider or Docker labels), whereas plugins are declared in static configuration (traefik.yml or CLI flags).

To load dynamic configuration files into Traefik, enable the file provider in your static configuration:

# traefik.yml (Static Configuration)providers:  file:    filename: "/etc/traefik/dynamic_conf.yml"    watch: true

RouteWarden can be configured using routewarden.json as your universal security schema, or directly in Traefik dynamic file/label configurations.

How routewarden.json Maps to Dynamic Configuration

Because routewarden.json adheres to the official RouteWarden JSON Schema, every field in routewarden.json maps directly 1-to-1 to Traefik's plugin.routewarden middleware configuration keys:

Diff

{  "$schema": "https://routewarden.github.io/cli/schema.json",  "enabled": true,  "enableDefaultPatterns": true,  "enableDefaultAllowPatterns": true,  "checkQuery": false,  "checkHeaders": ["X-Forwarded-Uri", "X-Rewrite-URL"],  "allowedIps": ["127.0.0.1", "10.0.0.0/8"],  "methods": ["GET", "POST"],  "response": {    "mode": "json",    "statusCode": 403,    "body": "{\"error\":\"Forbidden\",\"message\":\"Sensitive route protected by RouteWarden\"}"  }}

Using routewarden.json Directly via Generate Pipeline

If you maintain routewarden.json as your single source of truth across Git repositories or multi-gateway environments, use the RouteWarden CLI (rwarden) to validate rules offline and compile directly into Traefik configurations during your deployment pipeline:

# 1. Validate schema compliance, regex patterns, and CIDRsrwarden validate --config routewarden.json# 2. Compile directly into Traefik dynamic YAMLrwarden generate --target traefik-yaml --config routewarden.json > dynamic_conf.yml# Or compile into Traefik dynamic TOMLrwarden generate --target traefik-toml --config routewarden.json > dynamic_conf.toml# Or compile into Docker Compose labels formatrwarden generate --target traefik-labels --config routewarden.json

---

3. Global Protection via EntryPoints (Protect All Services)

Instead of manually attaching routewarden to every individual router across dozens of microservices or containers, you can attach RouteWarden directly to Traefik's entryPoints (such as web on :80 and websecure on :443).

When attached to an entryPoint, RouteWarden enforces security inspection globally for all incoming requests before any router or service is reached:

Diff

# traefik.yml (Static Configuration: Attach to EntryPoints)entryPoints:  web:    address: ":80"    http:      middlewares:        - routewarden@file  websecure:    address: ":443"    http:      middlewares:        - routewarden@file

Why Use EntryPoint Protection?

• Zero-Touch Service Protection: Every newly deployed service or container inherits path traversal and asset protection automatically without modifying developer docker-compose.yml or Kubernetes manifests.
• Provider Syntax (@file vs @docker): When referencing middleware in static entryPoints, suffix the middleware name with the provider that defined it:
  • routewarden@file: Middleware defined in dynamic file configuration (dynamic.yml or dynamic.toml).
  • routewarden@docker: Middleware declared via Docker labels on the Traefik service itself.
• Defense in Depth: Even if an application router is misconfigured or a developer forgets security labels, the gateway blocks sensitive probing at the entryPoint edge.

Complete Global Shield Blueprint:

For full multi-container production recipes and docker-compose configurations, see Example 2: Global EntryPoint Shield.

---

Next Steps

• Explore Response Modes to customize block behaviors (HTML, JSON, Captcha, Gzip Bomb).
• Configure Anti-Evasion Engine for advanced normalization rules.
• Check out the Production Case Studies for real-world setups.
• Use the RouteWarden CLI (rwarden) for offline path testing and schema generation.
• Check the Examples & Wiki Cookbook for production Docker Compose & Kubernetes blueprints.