System Architecture

RouteWarden operates as an in-line HTTP middleware within Traefik's proxy pipeline. Every incoming request undergoes a strict, multi-stage inspection lifecycle before being either passed downstream or intercepted.

---

Architectural Flow

TraefikCaddyNGINXRouteWarden CLI

---

Modular Component Design

RouteWarden is constructed with clean, decoupled Go components adhering to Yaegi interpreter specifications:

1. ip_filter.go (IPFilter):
   • Parses exact IPv4 (127.0.0.1), IPv6 (::1), and CIDR networks (10.0.0.0/8).
   • Resolves client IP by prioritizing proxy headers (X-Forwarded-For, X-Real-IP) and falling back to socket RemoteAddr.
2. path_normalizer.go (PathNormalizer):
   • Extracts URL paths, unescapes recursive percent-encoding (%252e%252e ➔ ..), strips semicolon matrix parameters (/;param/.env), normalizes Windows backslashes (\), and generates canonical candidate paths.
3. config.go (Config):
   • Defines plugin parameters, default sensitive regex sets, allowlist patterns, compiler factories, and security logging settings.
4. response_handler.go (ResponseHandler):
   • Manages HTTP response emission for custom JSON, HTML, redirect codes, and embedded Captcha challenges (Turnstile, hCaptcha, reCAPTCHA).
5. routewarden.go (RouteWarden) / caddywarden.go:
   • Implements gateway interface (http.Handler for Traefik, caddyhttp.MiddlewareHandler for Caddy).
   • Coordinates candidate normalization, allow/block evaluation, and emits structured JSON audit events (logSecurityEvent) on blocked requests for CrowdSec and SIEM log shippers.
6. lib/resty/routewarden/init.lua (RouteWarden Lua):
   • Implements the OpenResty / NGINX Lua equivalent of the RouteWarden pipeline.
   • Runs in LuaJIT during access_by_lua with zero external dependencies, providing feature parity (anti-evasion, CIDR allowlists, 13 response modes, and CrowdSec security logging) for NGINX workloads.