Traefik Warden: Getting Started

Traefik Warden is a high-performance Traefik middleware plugin written in pure Go. It intercepts and blocks reconnaissance, directory probing, and unauthorized access to sensitive files before requests reach your backend services.

---

Key Capabilities

• Automatic Sensitive Asset Shielding: Blocks attempts to access environment configs (.env), git repos (.git), credentials (.aws, .ssh), database dumps (.sql), and debug panels (phpinfo.php, /actuator).
• Anti-Evasion Engine: Decodes and normalizes nested URL encodings (%252e%252e), semicolon matrix parameters (/;param/.env), backslashes (\..\), and null bytes (%00).
• IP & CIDR Allowlisting: Exempts internal networks, VPN gateways, and developer IPs from blocking.
• Flexible Responses & Captcha: Return custom JSON/HTML errors, silent drops, gzip bombs, or challenge visitors 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: Plugin Declaration

Choose between two installation methods depending on your environment:

Method A: Traefik Plugin Catalog (Online / Standard)

For standard deployments with internet connectivity, Traefik automatically downloads the verified release from plugins.traefik.io at startup:

Diff

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

Method B: Local & Air-Gapped Installation (localPlugins via /plugins-local)

For air-gapped networks, private enterprise environments without internet access, or local development, Traefik can load RouteWarden directly from disk without external downloads using localPlugins.

Traefik strictly requires the plugin directory inside the container to match the Go module path under /plugins-local/src/:

/plugins-local/
└── src/
    └── github.com/
        └── routewarden/
            └── traefik-warden/
                ├── .traefik.yml
                ├── config.go
                ├── routewarden.go
                └── ...

Mount the repository and declare it in your static configuration:

Diff

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

TIP

When using localPlugins, no Git tag or version property is required. Traefik's built-in Yaegi interpreter compiles the Go source files directly from /plugins-local/src/github.com/routewarden/traefik-warden on startup. For an in-depth walkthrough, see Local & Air-Gapped Deployment.

---

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/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.