Modular Protocol Plugins

The core tcp-warden binary is a ultra-lightweight, high-performance Layer 4 transparent security proxy (generic / tcp).

All protocol-specific security inspectors (ssh, smtp, pop3, imap, postgres, mysql, redis, http, etc.) are modular plugins maintained in the dedicated routewarden/plugins repository. This modular architecture ensures the core daemon remains minimal, zero-bloat, and rock-solid, while allowing operators to install only the protocols their infrastructure requires.

---

Official Plugins

TCP Warden provides 21 official plugins in the routewarden/plugins repository, covering DNS resolvers, P2P networks, database servers, mail systems, remote access, web services, caches, message brokers, and game servers. All plugins can be installed instantly with tcp-warden plugins install <name>.

Plugin	Protocol(s)	Documentation	What it does
dns	dns	DNS Guide	High-performance DNS firewall for UDP & TCP. Blocks malicious domains, restricts query types (ANY/AXFR), and prevents DNS rebinding attacks.
bittorrent	bittorrent, bittorrent-tcp, bittorrent-dht, bittorrent-utp	BitTorrent Guide	Multi-transport BitTorrent guard inspecting Peer Wire (TCP), DHT (UDP), and uTP (UDP) with info-hash filtering and anti-amplification.
ssh	ssh	SSH Guide	SSH handshake inspector with banner validation, version checks, and SSH_MSG_USERAUTH_FAILURE brute-force detection.
postgres	postgres, postgresql	PostgreSQL Guide	Catches failed password attempts (28P01) and automatically bans brute-force bots targeting PostgreSQL.
mysql	mysql, mariadb	MySQL Guide	Detects Access Denied errors (1045) and mitigates credential brute-forcing against MySQL and MariaDB.
redis	redis, resp	Redis Guide	Command firewall: blocks dangerous commands (FLUSHALL, CONFIG, SHUTDOWN) and bans repeated wrong passwords (-WRONGPASS). Supports RESP2 & RESP3.
mongodb	mongodb, mongo	MongoDB Guide	Wire protocol firewall: blocks destructive commands (drop, dropDatabase, shutdown) and bans failed authentications.
http	http	HTTP Guide	Blocks vulnerability scanners (User-Agent), regex path attacks (e.g. /.env, /admin), and validates Host headers. Transparent WebSocket pass-through.
tls_sni	tls, tls-sni, https	TLS SNI Guide	Inspects domain names (SNI) at Layer 4 to allow, block, or route domains without needing TLS certificates or decryption.
smtp	smtp, mail	SMTP Guide	SMTP mail transfer inspector with recipient limits, spam sender domain blocking, and authentication failure monitoring.
pop3	pop3	POP3 Guide	POP3 mail retrieval guard detecting auth brute-force attacks (-ERR Authentication failed) and STLS enforcement.
imap	imap	IMAP Guide	IMAP4rev1 mail retrieval guard tracking tagged authentication failures (NO/BAD [AUTHENTICATIONFAILED]).
generic	tcp, generic, raw	Generic Proxy Guide	Universal Layer 4 transparent proxy with rate limiting, CIDR allow/deny filtering, geo-blocking, and tarpitting for any custom TCP socket or protocol.
ftp	ftp	FTP Guide	Monitors control connections, restricts anonymous logins, and blocks repeated FTP authentication failures (530 Login incorrect).
ldap	ldap	LDAP Guide	Detects failed LDAP bind attempts (resultCode: 49) to protect Active Directory and OpenLDAP from credential stuffing.
amqp	amqp, rabbitmq	AMQP Guide	Protects RabbitMQ and AMQP brokers by tracking SASL authentication failures and malicious connection frames.
memcached	memcached	Memcached Guide	Protects caches by blocking administrative wipe commands (flush_all) and tracking unauthorized attempts.
mqtt	mqtt	MQTT Guide	Protects IoT brokers by enforcing valid client IDs and blocking scanner or bot prefixes.
vnc	vnc, rfb	VNC Guide	Protects remote desktop servers by detecting and banning VNC brute-force login attempts.
minecraft	minecraft, mc	Minecraft Guide	Protects game servers from ping floods, malformed handshake packets, and unsupported client versions.
echo_filter	echo, stream-filter	Echo Filter Guide	Example bidirectional stream filter that inspects and sanitizes text keywords in real time.

---

Installation & Management

Install, configure, and manage modular plugins either via the CLI or declaratively in your configuration file.

1. Command Line Installation

Install any plugin using its official short name, a Git repository URL, or a local source directory:

# Install by short name from the official routewarden/plugins repositorytcp-warden plugins install httptcp-warden plugins install redistcp-warden plugins install postgres

4-Step Safety Verification Pipeline

When you install any plugin, TCP Warden automatically runs four safety checks to protect your proxy:

1. [1/4] Validating manifest: Checks that plugin.yaml has valid YAML and required fields (name, version, manifest_version, protocols).
2. [2/4] Checking manifest compatibility: Confirms that manifest_version matches the supported SDK format (1.0.0).
3. [3/4] Compiling plugin: Verifies that the plugin compiles cleanly without Go syntax or package errors.
4. [4/4] Running tests: Runs go test -race -count=1 ./... inside the plugin. If any unit tests fail or race conditions are detected, installation is safely aborted.

2. Declarative Configuration (tcp-warden.yaml)

Declare required plugins directly in your configuration file. On startup, the daemon automatically pulls and registers any missing plugins:

# tcp-warden.yamlplugins:  http:    enabled: true    source: "https://github.com/routewarden/plugins/http"  redis:    enabled: true    source: "https://github.com/routewarden/plugins/redis"  mongodb:    enabled: true    source: "https://github.com/routewarden/plugins/mongodb"

3. Managing Installed Plugins

Use built-in CLI subcommands to inspect active plugins, enable or disable inspectors, or cleanly uninstall them:

# List all installed plugins and their current statustcp-warden plugins list

---

Plugin Configuration Examples

Below are common service configurations using official plugins:

DNS Firewall (dns)

Protects DNS resolvers across UDP and TCP against malicious domains, query amplification, and DNS rebinding:

services:  dns_firewall:    listen: ":53"    upstream: "1.1.1.1:53"    transport: "both"         # Intercepts both UDP and TCP DNS queries    protocol: "dns"    rate_limit:      connections_per_minute: 1200      burst: 200    udp:      session_timeout: "15s"      max_sessions: 20000    plugin_config:      blocked_domains:        - "*.badware.test"        - "c2.threat.org"      blocked_qtypes:        - "ANY"               # Stop ANY query amplification floods        - "AXFR"              # Block unauthorized zone transfers      block_private_ips: true # Prevent DNS rebinding attacks

BitTorrent Guard (bittorrent)

Enforces info-hash filtering, verified peer ID formats, and anti-amplification controls across TCP and UDP:

services:  torrent_guard:    listen: ":6881"    upstream: "10.0.0.50:6881"    transport: "both"         # Peer Wire (TCP) + DHT/uTP (UDP)    protocol: "bittorrent"    plugin_config:      blocked_info_hashes:        - "aabbccddeeff00112233445566778899aabbccdd"      require_peer_id_format: true      allowed_peer_id_prefixes:        - "-qB-"              # qBittorrent        - "-TR-"              # Transmission        - "-DE-"              # Deluge      blocked_dht_methods:        - "announce_peer"     # Mitigate DHT poisoning      max_dht_packet_size: 1500

HTTP Guard (http)

Protects HTTP applications with Host header validation, User-Agent filtering, and regex path blocking:

services:  web_guard:    listen: ":8080"    upstream: "127.0.0.1:80"    protocol: "http"    rate_limit:      connections_per_minute: 120      burst: 30    plugin_config:      allowed_hosts:        - "api.example.com"        - "app.example.com"      blocked_paths:        - "^/admin(/.*)?$"        - "\.(env|git|bak|sql)$"      blocked_headers:        User-Agent: "(?i)(sqlmap|nikto|acunetix|masscan)"

Database Protection (postgres & mongodb)

Tracks failed authentication attempts and blocks destructive operations:

services:  pg_bastion:    listen: ":5432"    upstream: "10.0.0.15:5432"    protocol: "postgres"    max_auth_failures: 3    ban_duration: "2h"

In-Memory Cache Firewall (redis)

Blocks dangerous administrative commands while allowing application queries:

services:  redis_proxy:    listen: ":6380"    upstream: "127.0.0.1:6379"    protocol: "redis"    plugin_config:      blocked_commands:        - "FLUSHALL"        - "FLUSHDB"        - "CONFIG"        - "SHUTDOWN"

Transparent TLS SNI Routing (tls_sni)

Inspects the TLS ClientHello Server Name Indication (SNI) at Layer 4 and filters traffic by domain name without terminating TLS certificates:

services:  sni_proxy:    listen: ":443"    upstream: "10.0.0.10:443"    protocol: "tls_sni"    plugin_config:      allowed_domains:        - "*.example.com"        - "example.com"      blocked_domains:        - "internal.example.com"

---

Docker Persistence & Caching

When running in Docker, mount the named volume tcp-warden-data to /var/lib/routewarden. This preserves:

1. Installed plugin sources and manifests in /var/lib/routewarden/plugins.
2. Recompiled daemon binary in /var/lib/routewarden/bin/tcp-warden (so subsequent container restarts are instant without re-compiling).
3. SQLite bans database in /var/lib/routewarden/bans.db.

services:  tcp-warden:    image: ghcr.io/routewarden/tcp-warden:latest    container_name: tcp-warden    restart: unless-stopped    network_mode: host    environment:      - AUTO_INSTALL_PLUGINS=ssh postgres redis # Auto-install & compile on first launch    volumes:      - tcp-warden-config:/etc/routewarden      - tcp-warden-data:/var/lib/routewarden    # Caches compiled binary & plugins across restarts      - tcp-warden-logs:/var/log/routewardenvolumes:  tcp-warden-config:  tcp-warden-data:  tcp-warden-logs:

---

Next Steps

• Routing Traffic: Learn how to divert live traffic into TCP Warden via nftables, iptables, port swapping, or Docker networks in the Network & Firewall Integrations Guide.
• Developing Plugins: Want to create your own protocol inspector? Follow the Plugin Development & Integration Guide.
• Configuration Details: Learn more about proxy listeners and port ranges in the Configuration Reference.