Knocker, a knock based access control system for your homelab

Summary

Knocker is a configurable, and self-hosted service that provides an HTTP based "knock-knock" single-packet authorization (SPA) gateway for your Homelab with web, cli and android clients. it can be used as authentication for your reverse proxy like Caddy, or even on the firewall level using the FirewallD integration. It allows you to keep your services completely private, opening them up on-demand only for authorized IP addresses. This is ideal for homelab environments where you want to expose services to the internet without a persistent VPN connection, while minimizing your public-facing attack surface. Sequence diagram sequenceDiagram participant User participant Caddy as Reverse Proxy (Caddy) participant Knocker participant Service as Protected Service User->>Caddy: HTTP request to protected service Caddy->>Knocker: GET /verify (copies X-Forwarded-For) Knocker-->>Knocker: check always_allowed_ips / excluded_paths / whitelist alt IP whitelisted Knocker-->>Caddy: 200 OK (empty body) Caddy->>Service: forward request Service-->>Caddy: 200 OK Caddy-->>User: 200 OK else IP not whitelisted Knocker-->>Caddy: 401 Unauthorized (empty body) Caddy-->>User: 401 Unauthorized end Note over User,Knocker: Performing a "knock" (to add whitelist entry) User->>Knocker: POST /knock (X-Api-Key, optional ip_address, ttl) Knocker->>Knocker: validate API key, determine client IP Knocker->>Knocker: update whitelist.json with expiry Knocker-->>User: 200 OK (whitelisted_entry, expires_at, expires_in_seconds) Loading Features API Key Authentication : Secure your knock endpoint with multiple, configurable API keys. : Secure your knock endpoint with multiple, configurable API keys. Configurable TTL : Each API key can have its own Time-To-Live (TTL), defining how long a whitelisted IP remains active. : Each API key can have its own Time-To-Live (TTL), defining how long a whitelisted IP remains active. Remote Whitelisting : Grant specific admin keys permission to whitelist any IP or CIDR range, ...