Knocker ist ein selbst gehosteter Dienst, der ein HTTP-basiertes „Klopf-Klopf“-Single-Packet-Authorization (SPA)-Gateway für dein Homelab bereitstellt, mit Clients für das Web, die CLI (inkl. GNOME) und Android. Es kann als Authentifizierung für deinen Reverse-Proxy wie Caddy oder sogar auf Firewall-Ebene mittels der FirewallD-Integration verwendet werden. Es ermöglicht dir, deine Dienste vollständig privat zu halten und sie nur auf Anfrage für autorisierte IP-Adressen freizuschalten.

Dies ist ideal für Homelab-Umgebungen, in denen du Dienste ohne dauerhafte VPN-Verbindung für das Internet freigeben möchtest und gleichzeitig deine öffentliche Angriffsfläche minimierst.

Funktionen

API-Key-Authentifizierung: Sichere deinen Knock-Endpunkt mit mehreren, konfigurierbaren API-Schlüsseln.
Konfigurierbare TTL: Jeder API-Schlüssel kann seine eigene Time-To-Live (TTL) haben, die festlegt, wie lange eine freigegebene IP aktiv bleibt.
Remote-Whitelisting: Bestimmte Admin-Schlüssel können berechtigt werden, jede IP oder jeden CIDR-Bereich freizuschalten, nicht nur die eigene.
Statisches IP/CIDR-Whitelisting: Bestimmte IP-Adressen oder -Bereiche werden immer erlaubt und umgehen die dynamische Whitelist.
Pfadbasierte Ausnahmen: Bestimmte URL-Pfade (z. B. Health Checks oder öffentliche APIs) können vollständig von der Authentifizierung ausgeschlossen werden.
IPv6 als erstklassiger Bürger: Volle Unterstützung für IPv6 und IPv4 beim Whitelisting, bei vertrauenswürdigen Proxys und in Docker-Netzwerken.
Firewalld-Integration: Erweiterte Firewall-Steuerung mit zeitgesteuerten Regeln, die automatisch basierend auf der TTL verfallen. Erstellt dynamische Firewall-Regeln mittels Firewalld-Rich-Rules für erhöhte Sicherheit. (Optional, erfordert Root-Zugriff im Container)

Knocker-Clients

Knocker-Web Statische PWA-Web-App, die beim Neuladen einen Knock (Whitelisting) unterstützt.
Knocker-CLI Ein CLI in Go geschrieben, mit Unterstützung für Hintergrund-Knocks, optional ausgelöst durch IP-Änderungen.
Knocker-gnome – eine GNOME-Erweiterung auf Basis des Knocker-CLI.
Knocker-EXPO Eine experimentelle Android-App in React EXPO, mit Unterstützung für Hintergrund-Knock-Anfragen.

Sequenzdiagramm

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)

Bereitstellung

Dieses Projekt ist für die Bereitstellung als Docker-Container mit der bereitgestellten docker-compose.yml konzipiert. Es verwendet die vorgebauten Docker-Images mit Unterstützung für AMD64, ARMv8 und ARMv7.

Docker-Image-Tags

Knocker bietet verschiedene Image-Tags für unterschiedliche Anwendungsfälle:

latest – Neuestes stabiles Release (empfohlen für die Produktion)
v1.2.3 – Bestimmte Versions-Tags (festgepinnte Versionen)
main – Entwicklungsbranch (fortlaufende Updates, möglicherweise instabil)

Registries

oci.fariszr.com (quay.io)
ghcr.io

1. Voraussetzungen

Docker und Docker Compose installiert.
Ein öffentlich erreichbarer Server zum Ausführen der Container (muss nicht einmal derselbe Server sein, auf dem die Dienste laufen! IM PROXY-MODUS)
(Optional) Firewalld 2.0+ installiert und auf dem Host ausgeführt für erweiterte Firewall-Integration.

Konfiguration:
- Benenne knocker.example.yaml in knocker.yaml um.
- Ändere unbedingt die Standard-API-Schlüssel in knocker.yaml in eigene, sichere, zufällige Zeichenfolgen.
- Überprüfe die Liste der trusted_proxies in knocker.yaml. Sie sollte dem Subnetz des Reverse-Proxy-Netzwerks entsprechen (docker network inspect xxx).
- Belasse whitelist.storage_path im Arbeitsverzeichnis der App, unter /data oder /tmp.
- (Optional) Konfiguriere die Firewalld-Integration, indem du firewalld.enabled: true setzt und die zugehörigen Einstellungen anpasst. Hinweis: Dies erfordert, dass der Container als Root läuft.
Dienst starten:
```
docker compose up -d
```
Dies zieht das vorgebaute knocker-Image und startet sowohl den knocker- als auch den caddy-Dienst.

Knocker mit einem Reverse-Proxy verwenden

Knocker fungiert als Authentifizierungs-Gateway für deinen Reverse-Proxy. Es bietet einen Verify-Endpunkt, um zu prüfen, ob die anfragende IP auf der Whitelist steht. Falls nicht, antwortet es mit 401, und der Reverse-Proxy lehnt die Verbindung ab.

Caddy

Caddy hat die Direktive forward_auth, um Verbindungen über einen Auth-Endpunkt zu prüfen.

Ein wiederverwendbares Snippet definieren: Es ist bewährte Praxis, ein Snippet in deiner Caddyfile für die Auth-Prüfung zu definieren.
Dienste schützen: Importiere das Snippet für jeden Dienst, den du schützen möchtest.

Beispiel Caddyfile:

# Caddyfile

# Definiere ein wiederverwendbares Snippet für die Knock-Klopf-Prüfung.
# Es zeigt auf den Knocker-Dienst über Docking's internes DNS.
(knocker_auth) {
  forward_auth knocker:8000 {
    uri /verify
  }
}

# Der öffentliche Endpunkt zum Durchführen des Knocks.
# Stelle sicher, dass diese Domain auf die IP deines Caddy-Servers zeigt.
knock.your-domain.com {
  reverse_proxy knocker:8000
}

# Ein Beispiel eines geschützten Dienstes.
jellyfin.your-domain.com {
  import knocker_auth  # Wendet die forward_auth-Prüfung an
  reverse_proxy jellyfin_service_name:8096
}

Autorisierungsfehler

Wenn ein Benutzer nicht auf der Whitelist steht, gibt die forward_auth-Direktive von Caddy eine 401 Unauthorized-Antwort mit leerem Körper zurück.

Wichtiger Hinweis: Die handle_errors-Direktive von Caddy funktioniert nicht mit forward_auth-Antworten. Die Fehlerantwort kommt direkt vom Authentifizierungsdienst (Knocker), nicht von Caddy selbst, daher kann handle_errors diese Antworten nicht abfangen oder ändern.

FirewallD-Integration

Knocker bietet eine erweiterte Firewall-Integration über firewalld, die dynamische, zeitbasierte Firewall-Regeln erstellt, die automatisch basierend auf der in den Knock-Anfragen angegebenen TTL verfallen. Diese Funktion arbeitet auf Netzwerkebene und ermöglicht es dir, Knocker für nicht-HTTP-Dienste wie SSH oder Gameserver zu verwenden.

Sequenzdiagramm (firewalld)

sequenceDiagram
    participant Client as User
    participant Firewall as Firewalld (knocker zone)
    participant Knocker
    participant Service as Protected Service (port 22)

    Note over Client,Firewall: Initial state — monitored port is blocked by default
    Client->>Firewall: TCP SYN to Service:22
    Firewall-->>Client: DROP (no response)

knocker

Beliebteste