Frequently Asked Questions (FAQ)

Everything you need to know about Routewarden architecture, threat mitigation, performance, and best practices.

---

Quick Navigation

🛡️ General & Architecture

What Routewarden is, how it compares to WAFs, and multi-gateway compatibility.

🔍 Detection & Patterns

Default blocklists, regex syntax, anti-evasion rules, and .well-known exemptions.

⚡ Response Modes

13 response actions, deceptive 404s, silent TCP drops, and gzip bombs.

🌐 IPs & Proxies

CIDR whitelists, Cloudflare integration, and preventing XFF header spoofing.

🔌 Layer 4 (TCP Warden)

SSH, SMTP, database protection, protocol inspection, and connection tarpits.

📊 Security Dashboard & CLI

Real-time SOC dashboard, GeoIP country resolution, and rwarden linting.

---

General & Architecture

What is Routewarden, and what problem does it solve?

Routewarden is a unified edge and protocol security suite designed to block scanner recon, credential stuffing, and sensitive data leaks at the perimeter before requests touch your application containers.

Every server on the public internet faces relentless automated scanners probing for:

• Configuration & secrets: /.env, /config.json, /wp-config.php, /settings.py
• VCS repositories & metadata: /.git/HEAD, /.svn/entries, /.DS_Store
• Backups & dumps: /backup.sql, /database.tar.gz, /site.zip
• Admin consoles & debug endpoints: /phpinfo.php, /_profiler, /actuator/env

Routewarden sits directly inside your edge gateway (Traefik, Caddy, or NGINX) or as an L4 proxy (TCP Warden), neutralizing these requests in less than 0.05 milliseconds before your backend processes, databases, or application servers ever see them.

---

How does Routewarden differ from a full WAF (ModSecurity, Coraza, Cloudflare)?

Dimension	Full WAF (ModSecurity / Coraza)	Cloudflare WAF	Routewarden
Primary Scope	Deep HTTP body inspection (SQLi, XSS, RCE)	Cloud-level DDoS, managed rule sets	Edge path defense (L7) & Protocol shielding (L4)
Inspection Latency	5ms – 25ms per request	Variable (cloud edge detour)	< 0.05ms (zero-alloc regex & byte scanning)
Memory Footprint	100MB – 500MB+ per process	Hosted / SaaS	< 15MB standalone binary / in-process middleware
Rule Complexity	Thousands of complex CRS rules	Managed / proprietary cloud rules	Curated high-signal dictionary + custom RE2 regex
False Positive Rate	High (often requires weeks of tuning)	Low-to-moderate	Near zero for sensitive paths & protocol handshakes
Layer 4 Coverage	No (HTTP/HTTPS only)	Spectrum (Enterprise tier only)	Native TCP Warden (SSH, SMTP, DBs, DNS, etc.)
Active Deception	Block (403) or Drop	Managed challenge page	13 actions: Gzip bombs, fake 404s, Captchas, Tarpits

TIP

Better Together: Routewarden is not an all-or-nothing replacement for a full WAF. Many production teams run Routewarden directly at their reverse proxy to instantly discard scanner garbage, drastically lowering load on heavier downstream WAF engines or application servers.

---

Can I run Routewarden alongside CrowdSec or Fail2ban?

Yes, absolutely. They serve complementary roles:

• Routewarden is an in-line enforcement gate: it inspects every packet/request live on the wire and acts instantly on the very first offending request (e.g., dropping or tarpitting before response generation).
• CrowdSec / Fail2ban are log analyzers: they monitor logs after the fact and push IP bans to firewalls or IP lists.

When combined, Routewarden emits structured JSON logs with normalized client IPs and exact threat verdicts, which CrowdSec or Fail2ban can ingest without fragile custom log parsers. See the CrowdSec Auto-Ban Shield Case Study for complete configuration blueprints.

---

Which reverse proxies and gateways are supported?

Routewarden provides native integrations for all major open-source web gateways and protocols:

1. Traefik Warden: Official Traefik middleware plugin written in Go (github.com/routewarden/route-warden), available in the Traefik Plugin Catalog.
2. Caddy Warden: Native Caddy v2 HTTP handler module (github.com/routewarden/caddy-warden) with full Caddyfile and JSON configuration support.
3. NGINX Warden: High-performance OpenResty/Lua module with resty.core string manipulation and optional shared dictionary caching.
4. TCP Warden: Standalone Layer 4 reverse proxy protecting non-HTTP protocols (SSH, databases, mail, DNS, game servers) with modular protocol plugins.

---

Does Routewarden add measurable latency?

No. Benchmarks across Traefik, Caddy, and NGINX show Routewarden introduces less than 50 microseconds (< 0.05ms) of overhead on standard HTTP requests:

• Regex patterns are pre-compiled at startup into optimized RE2 finite automata.
• Fast-path byte checking validates request methods and path prefixes before regex execution.
• IP allowlists use binary radix tree CIDR lookups ($O(1)$ complexity).
• No external network calls, database lookups, or thread locks occur during request evaluation.

---

Threat Detection & Patterns

What does Routewarden block by default?

When enableDefaultPatterns: true is active, Routewarden blocks over 250 common scanner targets grouped into 7 categories:

├── Environment Files     (.env, .env.local, .env.production, docker-compose.yml)├── Version Control       (.git, .svn, .hg, .bzr, .gitattributes, .gitmodules)├── Backups & Archives    (.bak, .backup, .old, .orig, .tar.gz, .sql.gz, dump.sql)├── Cloud & Credentials   (.aws/credentials, .kube/config, id_rsa, id_ed25519)├── Server Info & Debug   (phpinfo.php, server-status, _profiler, /actuator)├── OS & Editor Artifacts (.DS_Store, Thumbs.db, *~, #*#, .idea, .vscode)└── Database Management   (pma, phpmyadmin, adminer.php, myadmin)

●READONLY│UTF-8│PLAINTEXT

For the complete list and interactive tests, visit the Interactive Pattern Checker.

---

How does Anti-Evasion Normalization prevent bypasses?

Attackers frequently encode paths to sneak past basic reverse proxy rules. Routewarden runs all paths through a strict 5-stage anti-evasion normalization pipeline before pattern matching:

1. Recursive Percent-Decoding: Neutralizes multi-layered percent encoding (/%252e%252e/ $\to$ /../ $\to$ /).
2. Path Traversal Resolution: Resolves relative path segments (/static/../../.env $\to$ /.env).
3. Matrix Parameter Stripping: Removes path parameters (/;param=1/.env $\to$ /.env).
4. Separator Normalization: Converts backslashes to forward slashes (\admin\.env $\to$ /admin/.env) and collapses consecutive slashes (///.env $\to$ /.env).
5. Null-Byte & Control Character Stripping: Removes poison null bytes (/.env%00.png $\to$ /.env).

Learn more in the Anti-Evasion Normalization Deep Dive.

---

Will Routewarden block Let's Encrypt / ACME challenges (.well-known)?

No. Routewarden includes a built-in exemption for ACME certificate validation:

^/.well-known/acme-challenge/.*

●READONLY│UTF-8│PLAINTEXT

Legitimate requests from Let's Encrypt, ZeroSSL, or cert-manager to /.well-known/acme-challenge/* pass through unconditionally, ensuring automated TLS renewal is never disrupted.

---

How do I add custom block patterns or regexes?

You can supply custom rules via customBlockPatterns or blockPatterns. Select your gateway below:

File:

# traefik.yml (Dynamic Configuration)http:  middlewares:    my-shield:      plugin:        routewarden:          enabled: true          customBlockPatterns:            - "^/internal-api/.*"            - "(?i)\\.(log|conf|ini|key)$"            - "^/wp-login\\.php$"

●READONLY│UTF-8│YAML

---

How do I whitelist a false positive or legitimate public file?

Use allowPatterns (or customAllowPatterns). Rules in the allowlist are evaluated before block rules, guaranteeing that matching requests bypass inspection:

# traefik.yml (Dynamic Configuration)http:  middlewares:    my-shield:      plugin:        routewarden:          allowPatterns:            - "^/downloads/sample\\.env$"            - "^/public/documentation/.*\\.sql$"

●READONLY│UTF-8│YAML

---

Response Modes & Active Defense

What response modes does Routewarden support?

Routewarden provides 13 distinct response actions, ranging from standard HTTP rejections to active defense deceptions:

Mode	HTTP Status	Action / Behavior	Best Used For
block	403	Standard RFC 403 Forbidden with custom security headers.	Default public APIs and corporate gateways.
fake404	404	Returns a sterile Not Found page, concealing middleware existence.	Preventing reconnaissance and fingerprinting.
silentDrop	None	Instantly closes TCP socket with TCP RST (or 0 byte read).	Exhausting bot connection pools and socket limits.
delay	403	Sleeps for a configured duration (e.g., 5s) before returning 403.	Slowing down high-velocity automated scanners.
tarpit	200	Trickles single bytes every few seconds to keep scanner threads frozen.	Paralyzing single-threaded scanning scripts.
redirect	301/302	Sends the attacker to a honeypot, FBI warning, or Rickroll.	Psychological defense and threat diversion.
customJson	403	Emits a structured JSON error payload matching your API schema.	REST and GraphQL backends.
customHtml	403	Renders a branded HTML security barrier with support contacts.	User-facing web applications.
honeypot	200	Responds with realistic fake secrets (canary AWS/Stripe keys).	Attacker attribution and automated alerting.
ratelimit	429	Throttles excessive sensitive path probes with standard Retry-After.	Thwarting brute-force and dictionary attacks.
captchaTurnstile	200	Challenges client with Cloudflare Turnstile before allowing access.	Protecting admin panels without static IP limits.
captchaHcaptcha	200	Challenges client with hCaptcha interactive verification.	Privacy-focused bot verification.
gzipBomb	200	Emits a 10MB recursive gzip bomb that inflates to 10GB in client RAM.	Crashing aggressive vulnerability scrapers.

See the Response Modes Reference for setup syntax and configuration details for each mode.

---

How does the gzipBomb response mode work? Is it dangerous for my server?

The gzipBomb response serves an ultra-compressed 10 KB HTTP payload that inflates to over 10 GB of zeros when decompressed into the memory of an automated scraper or curl script.

• Server-side footprint: Minimal. The compressed 10 KB file is pre-generated in memory; your server streams the small byte slice without CPU spike or disk I/O.
• Client-side impact: Scanners running Python requests, Go HTTP clients, or headless browsers that automatically decode gzip responses will suffer immediate memory exhaustion (OOM kill) or CPU freeze.

WARNING

Use gzipBomb exclusively on paths that legitimate visitors never request (such as /.env, /backup.sql, or /.git/config).

---

IP Allowlisting & Trusted Proxies

How do I whitelist my office, VPN, or Docker internal network?

Add specific IP addresses or CIDR ranges to allowedIps:

# traefik.ymlhttp:  middlewares:    my-shield:      plugin:        routewarden:          allowedIps:            - "127.0.0.1"        # Localhost loopback            - "10.0.0.0/8"        # Internal corporate LAN            - "172.16.0.0/12"     # Docker bridge network            - "192.168.1.0/24"    # Office subnet            - "100.64.0.0/10"     # Tailscale / NetBird CGNAT

●READONLY│UTF-8│YAML

Requests from these addresses bypass all inspection rules immediately.

---

How does Routewarden prevent X-Forwarded-For spoofing?

Attackers frequently send headers like X-Forwarded-For: 127.0.0.1 hoping naive middlewares will treat them as local traffic.

Routewarden includes a Trusted Proxies Engine:

1. When trustedProxies is configured, Routewarden inspects the physical socket connection address (RemoteAddr).
2. If RemoteAddr belongs to a trusted proxy CIDR (such as Cloudflare or your internal load balancer), Routewarden parses X-Forwarded-For from right to left to locate the verified client IP.
3. If RemoteAddr is not in trustedProxies, Routewarden ignores all incoming forwarding headers and treats RemoteAddr as the authoritative client IP.

# traefik.ymlhttp:  middlewares:    my-shield:      plugin:        routewarden:          trustedProxies:            - "173.245.48.0/20"   # Cloudflare IP range            - "103.21.244.0/22"   # Cloudflare IP range            - "10.0.0.0/8"        # Internal Load Balancer

●READONLY│UTF-8│YAML

---

Layer 4 (TCP Warden)

What is TCP Warden, and how does it relate to HTTP Routewarden?

While Traefik, Caddy, and NGINX handle Layer 7 (HTTP/HTTPS) web applications, TCP Warden is a dedicated Layer 4 reverse proxy and protocol firewall designed for non-HTTP infrastructure.

It sits in front of ports like:

• :22 (SSH)
• :25, :587, :993 (SMTP, IMAP mail servers)
• :5432 (PostgreSQL), :3306 (MySQL), :6379 (Redis)
• :53 (DNS over UDP and TCP)
• :25565 (Minecraft and game servers)

It performs wire-level protocol handshake inspection, connection rate limiting, GeoIP fences, and tarpits before handoffs reach the underlying server. Read the TCP Warden Guide for architecture and plugin details.

---

What is a Tarpit in TCP Warden?

A Tarpit accepts an attacker's TCP connection but deliberately throttles data transmission to a crawl (e.g., sending 1 byte every 10 seconds).

Because bots and brute-force tools (like hydra, nmap, or SSH scanners) allocate connection threads and wait for responses, a tarpit holds their sockets open for minutes or hours, consuming the attacker's resources while using virtually zero CPU or memory on your server.

---

Security Dashboard

How does the Routewarden Security Dashboard work?

Routewarden provides a turnkey real-time SOC security dashboard powered by Routewarden's embedded Go server and SQLite persistence:

1. Container Auto-Discovery & Filtering: Automatically queries /var/run/docker.sock for running containers labeled with routewarden=true, multiplexes their logs concurrently, and allows filtering the SOC stream by individual nodes or containers.
2. In-Memory Analytics & SQLite Store: High-performance streaming parser tracking 403 blocks, 429 tarpits, unique IPs, and top target attack paths consuming only ~8MB RAM, backed by persistent SQLite storage with server-side pagination.
3. Password Protection & Access Control: Protect the dashboard UI and sensitive log streams with optional HTTP Basic Auth (--auth admin:secret).
4. Real-Time SOC Feed: Built-in HTTP and SSE server accessible at http://localhost:7890 featuring live pause/resume, keyboard navigation ([ / ]), and real-time threat charts.

Start the dashboard with a single command:

Terminalbash

# Launch Routewarden Security Dashboardrwarden dashboard# Launch with password protection & custom host/portrwarden dashboard up --host 127.0.0.1 --port 7890 --auth admin:supersecret

●READONLY│UTF-8│BASH

---

Does Routewarden scrape all Docker containers on my host?

No. Routewarden uses a strict opt-in model. It only ingests logs from containers that declare:

File:

# docker-compose.yml: Opt-in container logging for rwarden dashboardservices:  traefik:    image: traefik:latest    labels:      - "routewarden.logs=true"      - "traefik.enable=true"

●READONLY│UTF-8│YAML

Or containers monitored via the dedicated UDP syslog listener (127.0.0.1:1514). Unlabeled containers and host services are completely ignored.

---

CLI (rwarden) & CI/CD

What can I do with the rwarden CLI?

The rwarden CLI is a cross-platform command-line tool for developers and SecOps teams:

• Offline Pattern Testing: Test paths against Routewarden normalization without running a live server (rwarden check "/.env").
• Configuration Validation & Linting: Validate routewarden.json against the JSON schema (rwarden schema validate).
• Config Snippet Generation: Output production-ready Traefik, Caddy, NGINX, or Docker Compose snippets (rwarden generate --gateway traefik).
• Security Dashboard: Launch and monitor the local real-time security dashboard (rwarden dashboard).

Install it with the universal installer script or from source:

# macOS & Linux via Homebrewbrew install routewarden/tap/rwarden# Verify installationrwarden version

●READONLY│UTF-8│BASH

---

Can I run rwarden check in GitHub Actions or CI/CD?

Yes. You can integrate rwarden into pull request workflows to prevent developers from accidentally committing configurations that expose protected paths:

# .github/workflows/security-lint.ymlname: Security Linton: [push, pull_request]jobs:  routewarden:    runs-on: ubuntu-latest    steps:      - uses: actions/checkout@v4      - name: Install Routewarden CLI        run: curl -fsSL https://routewarden.github.io/install.sh | sh      - name: Verify Sensitive Endpoints Are Blocked        run: |          rwarden check "/.env" --expect-block          rwarden check "/.git/config" --expect-block          rwarden check "/backup.sql" --expect-block          rwarden check "/api/v1/health" --expect-allow

●READONLY│UTF-8│YAML

---

Troubleshooting & Support

A legitimate user request is getting blocked (403/404). How do I diagnose it?

1. Test the path with CLI and apply the allowlist fix:

File:

# Diagnose path normalization and pattern matchingrwarden check "/path/to/resource" --debug# Example output:# [NORMALIZED] /path/to/resource# [VERDICT]    BLOCK# [MATCH]      ^/path/to/.* (Rule ID: custom_01)# [RESPONSE]   403 Forbidden

●READONLY│UTF-8│BASH

2. Check the Live Security Feed: Open the dashboard (http://localhost:7890), or run rwarden monitor --verdict BLOCK, to view real-time blocked threats, client IPs, and matched rules.

---

Where do I ask questions, report bugs, or request features?

• GitHub Discussions & Issues: github.com/routewarden
• Product Hunt Community: Share feedback and engage with the maintainers.
• Security Advisories: To report a security vulnerability responsibly, please submit a private report via GitHub Security Advisories on the relevant repository or review our Security Policy.