TCP Warden

A lightweight, protocol-aware security proxy and firewall for non-HTTP services across TCP and UDP.

Most reverse proxies (like Traefik, Caddy, or NGINX) are built to protect web traffic (HTTP/HTTPS). But what protects your databases, SSH servers, DNS resolvers, message queues, and cache layers?

TCP Warden sits between the internet and your backend services. It intercepts raw TCP and UDP traffic, inspects protocol handshakes and datagrams, blocks brute-force attackers, rate-limits abusive clients, and optionally integrates with CrowdSec—all before malicious packets ever reach your servers.

What Does TCP Warden Do?

🛡️ Stop Brute-Force Logins

Automatically tracks authentication failures across SSH, databases, and mail servers. Abusive IPs are banned instantly.

⚡ Smooth Connection Spikes

Applies token-bucket rate limiting and global connection limits so sudden traffic bursts or DoS attempts never exhaust server memory.

🔍 Deep Protocol Inspection

Decodes and validates protocols like PostgreSQL, MySQL, Redis, MongoDB, and SSH rather than treating them as blind byte streams.

🌍 Restrict by IP & Geo-Location

Allow only your team's VPN or specific countries to reach sensitive administrative and database ports using MaxMind GeoIP.

🤝 Community Threat Defense (Optional)

Optional native CrowdSec integration pulls community-wide IP blocklists in real time and reports local attacks back to the network.

📊 Live Alerts & Observability

Stream security events live over Server-Sent Events (SSE) or query REST metrics on port :9091 for zero-blindspot monitoring.

How It Works: The 8-Stage Pipeline

Whenever a client connects, TCP Warden passes the socket through an 8-stage security pipeline. If a connection violates any rule, it is dropped or redirected to a high-latency tarpit before consuming backend resources:

[ Inbound Client Connection ]
               │
               ▼
[ Stage 1: Connection Limits ] ────► Drops if service is over capacity
               │
               ▼
[ Stage 2: Failure Tracker   ] ────► Drops or tarpits banned brute-force IPs
               │
               ▼
[ Stage 3: CrowdSec Sync (Opt) ] ────► Blocks globally known malicious IPs (if enabled)
               │
               ▼
[ Stage 4: Subnet Filtering  ] ────► Enforces allow / deny CIDR lists (e.g. VPN only)
               │
               ▼
[ Stage 5: Geo-Blocking      ] ────► Blocks traffic from restricted countries
               │
               ▼
[ Stage 6: Rate Limiting     ] ────► Throttles connection bursts per client IP
               │
               ▼
[ Stage 7: Protocol Engine   ] ────► Inspects protocol payloads & commands
               │                     (SSH, SMTP, Postgres, Redis, etc.)
               ▼
[ Stage 8: Audit Log & SSE   ] ────► Emits structured JSONL logs & live alerts
               │
               ▼
[ Forward to Upstream Server ]

Pipeline Stages Explained

Stage	Security Layer	What It Does In Plain English
Stage 1	Connection Limits	Caps total open connections to prevent memory exhaustion and denial-of-service attacks.
Stage 2	Failure Tracker	Automatically bans client IPs that fail authentication repeatedly within a configurable time window.
Stage 3	CrowdSec Sync (Optional)	Checks CrowdSec's local cache in real time to immediately drop IPs flagged across the global threat network (when enabled).
Stage 4	IP Filtering	Restricts access to trusted subnets or blocks specific bad actors (e.g., allow office IPs only).
Stage 5	Geo-Blocking	Blocks or allows connections based on client country code using MaxMind GeoIP databases.
Stage 6	Rate Limiting	Uses a token-bucket algorithm to throttle rapid connection bursts and automated scanners.
Stage 7	Protocol Inspection	Decodes protocol handshakes (e.g., verifying SSH protocol versions or inspecting database commands).
Stage 8	Audit Logging & SSE	Writes structured JSONL audit logs and streams real-time connection events over HTTP Server-Sent Events.

Supported Protocols

TCP Warden provides a high-performance Layer 4 transparent proxy core, plus on-demand modular plugins for deep protocol inspection:

Built-in Core Protocol (generic / tcp):
- Universal Layer 4 transparent bastion for any TCP socket or proprietary protocol.
- Token-bucket rate limiting, CIDR allow/deny filtering, GeoIP country blocking, max connection capping, tarpitting, and SQLite ban tracking without extra plugins.
Modular Protocol Plugins (Installed via tcp-warden plugins install <name> or AUTO_INSTALL_PLUGINS):
- DNS & P2P Protocols: DNS Guard (dns over UDP/TCP), BitTorrent Guard (bittorrent over TCP/DHT/uTP).
- Remote Access & Mail: SSH, SMTP, POP3, IMAP, FTP, VNC.
- Databases & Caches: PostgreSQL, MySQL / MariaDB, Redis / Valkey, MongoDB, Memcached.
- Messaging & Directory: AMQP (RabbitMQ), MQTT, LDAP / Active Directory.
- Web & Game Protection: HTTP & WebSocket Guard, TLS SNI Router, Minecraft.

30-Second Quick Start

Deploy and configure TCP Warden in three simple steps:

Launch with Docker Compose: Use host networking so TCP Warden can bind directly to your designated ports.
Configure tcp-warden.yaml: Define the services you want to protect and their upstream targets.
Verify and Monitor: Inspect connection health and watch live events with the CLI.

services:  tcp-warden:    image: ghcr.io/routewarden/tcp-warden:latest    container_name: tcp-warden    restart: unless-stopped    network_mode: host    volumes:      - tcp-warden-config:/etc/routewarden      - tcp-warden-data:/var/lib/routewarden      - tcp-warden-logs:/var/log/routewardenvolumes:  tcp-warden-config:  tcp-warden-data:  tcp-warden-logs:

Explore the Documentation

Guide	Description
🚀 Getting Started & Docker	Step-by-step setup with Docker Compose, named volumes, and first-run verification.
⚙️ Configuration Reference	Complete reference for `tcp-warden.yaml`, service definitions, and rate limits.
🌐 Network & Firewall Integrations	Production deployment topologies, iptables/nftables PREROUTING, Docker bridge, and port-swapping.
🔌 Modular Protocol Plugins	Browse, install, and configure official plugins for Postgres, Redis, MongoDB, and more.
🛠️ Plugin Development Guide	Learn how to build, test, and package custom Layer 4 protocol inspectors in Go.
🛡️ CrowdSec Integration (Optional)	Connect TCP Warden with CrowdSec LAPI for automated, community-driven threat remediation.
❓ FAQ & Comparisons	Plain-English answers, comparisons with CrowdSec, Fail2ban, and iptables, and synergy breakdown.
📡 Management API & SSE	Query health status, view active bans, and stream live security alerts over HTTP.
💻 CLI Reference	Full reference for `run`, `validate`, `plugins`, `ban`, and `status` commands.
📜 Changelog & Releases	Release notes, breaking changes, and migration history across TCP Warden versions.

TCP Warden ​

What Does TCP Warden Do? ​