HTTP API & Live Events

TCP Warden includes a built-in HTTP server listening on port 9091 (configurable via api.listen or ROUTEWARDEN_API_LISTEN) and optionally an IPC Unix domain socket (e.g. /var/run/routewarden/tcp-warden.sock via api.socket or ROUTEWARDEN_API_SOCKET).

Use it to:

• Check daemon health and uptime (/health, /ping).
• List configured services and protocols (/api/services).
• View real-time traffic and connection counts per service (/stats or /api/stats).
• View, add, or remove active IP bans (/banlist, /ban, /unban).
• Stream live security events directly in your terminal (/events or /api/events).

Unix Domain Socket Support

For secure local IPC without exposing TCP ports, query the daemon directly via Unix domain socket:

curl --unix-socket /var/run/routewarden/tcp-warden.sock http://localhost/stats
curl -N --unix-socket /var/run/routewarden/tcp-warden.sock http://localhost/events

Dual Route Prefixes

All endpoints are available both at the root (e.g. /stats, /banlist, /events) and under the /api/ prefix (e.g. /api/stats, /api/banlist, /api/events).

Endpoints

1. Health Check (GET /health)

A quick check to confirm the daemon is up and running. Perfect for Docker health checks or Kubernetes probes.

curl -s http://127.0.0.1:9091/health

---

2. Traffic & Connection Stats (GET /stats)

Shows how many connections are active, total allowed and blocked requests, and bytes transferred for each service.

curl -s http://127.0.0.1:9091/stats

---

3. Configured Services List (GET /services)

Lists all active services, their protocol inspectors, listening ports, and upstream destinations.

curl -s http://127.0.0.1:9091/services

---

4. View Banned IPs (GET /banlist)

Lists all currently banned IPs, why they were banned, and when the ban expires.

curl -s http://127.0.0.1:9091/banlist

---

5. Manually Ban an IP (POST /ban)

Block an offending IP address across all services:

curl -X POST http://127.0.0.1:9091/ban \  -H "Content-Type: application/json" \  -d '{"ip": "203.0.113.50", "duration": "24h", "reason": "suspicious port scan"}'

---

6. Unban an IP (POST /unban)

Remove a ban immediately if an IP was blocked by mistake:

curl -X POST http://127.0.0.1:9091/unban \  -H "Content-Type: application/json" \  -d '{"ip": "203.0.113.50"}'

---

7. Live Security Events Stream (GET /events)

Watch security decisions live as they happen using Server-Sent Events (SSE). You can pipe this into monitoring tools, Slack bots, or simply watch in your terminal:

curl -N http://127.0.0.1:9091/events