Skip to content
KitploitKITPLOIT
ToolsBlog
Einreichen
ToolsBlog
Einreichen

Hacking-, PenTest- und Cybersicherheits-Tools für Ihr Sicherheitsarsenal!

Kitploit ist ein Verzeichnis von Hacking-, Cybersicherheits- und Pentesting-Tools. Entdecken Sie die neuesten Projekt-Updates, um Schwachstellen zu finden, Systeme zu analysieren, Tests zu automatisieren und Ihre Sicherheit zu stärken.

··Feeds·Kontakt·Datenschutz·© 2026 Kitploit

Tool-Verzeichnis

Kategorien

Alle Kategorien anzeigen
Loading categories
knocker — Knocker, ein knock-basierter Zugangskontrolldienst für dein Homelab | Kitploit
Tools/GitHubGitHub/fariszr/knocker
NetzwerksicherheitCloud-SicherheitDevSecOpsAuthentifizierungAPI-Sicherheit
GitHubfariszr/knocker

knocker

Knocker, ein knock-basierter Zugangskontrolldienst für dein Homelab

Repository anzeigen
1354vor 13 TagenVon Kitploit geprüft

Beliebteste

Alle anzeigen →

Entdecken Sie die meistgenutzten Tools unserer Community.

Alle Tools erkunden

Durchsuchen Sie unsere Tool-Sammlung

Alle Tools anzeigen →
Teilen

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.
Tool herunterladen
  • 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

    root@kitploit:~
    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.

    1. 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.

    2. Dienst starten:

      root@kitploit:~
      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.

    1. Ein wiederverwendbares Snippet definieren: Es ist bewährte Praxis, ein Snippet in deiner Caddyfile für die Auth-Prüfung zu definieren.

    2. Dienste schützen: Importiere das Snippet für jeden Dienst, den du schützen möchtest.

    Beispiel Caddyfile:

    root@kitploit:~
    # 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)

    root@kitploit:~
    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)

    Note over Client,Knocker: User performs a knock to whitelist their IP
    Client->>Knocker: POST /knock (X-Api-Key, optional ip_address, ttl)
    Knocker->>Knocker: validate API key & determine client IP
    Knocker->>Firewall: add rich accept rule for client IP on port 22 with timeout
    Firewall-->>Knocker: success

    Note over Firewall,Client: New rule overrides DROP due to higher priority
    Client->>Firewall: TCP SYN to Service:22
    Firewall->>Service: forward packet
    Service-->>Client: TCP SYN-ACK (connection established)
    Knocker->>Knocker: update whitelist.json with expiry

    Knocker benötigt FirewallD 2.0+ wegen der Abhängigkeit von der Zonen-Prioritätsfunktion. Es ist in Debian 13, Ubuntu 24.04 LTS und anderen aktuellen stabilen Distributionen verfügbar.

    Warum FirewallD?

    FirewallD wurde gewählt, weil es die CLI-Schnittstelle vom Daemon trennt. Dies ermöglicht es Knocker, firewalld von einem Docker-Container aus zu steuern, indem der D-Bus-Socket des Systems eingebunden wird. Außerdem unterstützt FirewallD zeitgesteuerte Regeln, sodass Knocker-Regeln automatisch am Ende der TTL verfallen.

    FIREWALLD FUNKTIONIERT NICHT MIT DOCKER-PUBLISHED-PORTS, siehe dieses Issue für weitere Details.

    Funktionsweise

    1. Erstellt eine dedizierte firewalld-Zone mit hoher Priorität
    2. Fügt DROP/REJECT-Regeln für überwachte Ports hinzu, um unbefugten Zugriff zu blockieren
    3. Fügt dynamisch ALLOW-Regeln für IPs auf der Whitelist hinzu, die die Blockierungsregeln überschreiben
    4. Löscht Regeln automatisch basierend auf der TTL mittels des Timeout-Mechanismus von firewalld
    5. Stellt Regeln beim Start wieder her, indem whitelist.json mit den aktiven firewalld-Regeln verglichen wird

    Aktivieren der FirewallD-Integration

    1. Voraussetzungen

      • FirewallD 2.0+ installiert und auf dem Hostsystem ausgeführt
      • Docker-Container muss als Root laufen (für D-Bus-Zugriff)

    2. Konfiguration

    • Aktiviere FirewallD in der knocker.yaml-Konfiguration. Die Einstellungen sind bereits in der Beispielkonfiguration vorhanden.
    • Binde den Dbus-Socket in den Docker-Container ein und stelle sicher, dass er als Root läuft. Die erforderlichen Einträge sind in der docker-compose.yml auskommentiert.

    Testen und Fehlerbehebung

    Aktive Regeln überwachen:

    root@kitploit:~
    # Knock-Zone prüfen
firewall-cmd --zone=knocker --list-all

# Rich Rules anzeigen
firewall-cmd --zone=knocker --list-rich-rules

# Regeländerungen überwachen
journalctl -u firewalld -f

    Ausführliche Informationen zur Konfiguration, Architektur und Fehlerbehebung finden sich im vollständigen FirewallD-Integrationsleitfaden.

    Probleme mit Userland-Proxy

    Wenn du Knocking für IPs hinter Tailscale oder anderen IPs aktivierst, können Probleme aufgrund der Funktionsweise des Userland-Proxys auftreten; die Anfrage-IP kann von der tatsächlichen IP-Adresse abweichen.

    Das Deaktivieren des Userland-Proxys sollte das Problem beheben, aber teste deine Einrichtung unbedingt. Du kannst auch das Host-Netzwerk verwenden.

    API-Nutzung

    /knock (POST)

    Dieser Endpunkt validiert einen API-Schlüssel und setzt eine IP auf die Whitelist.

    • Header:

      • X-Api-Key: Dein geheimer API-Schlüssel.

    • Body (Optional):

      • Zum Whitelisten einer entfernten IP/eines CIDR (erfordert allow_remote_whitelist: true):
        root@kitploit:~
        {"ip_address": "YOUR_TARGET_IP_OR_CIDR"}

    • Beispiel (Whitelisting der eigenen IP):

      root@kitploit:~
      curl -i -H "X-Api-Key: YOUR_SECRET_KEY" https://knock.your-domain.com/knock

    • Erfolgsantwort (200 OK):

      root@kitploit:~
      {
  "whitelisted_entry": "1.2.3.4",
  "expires_at": 1672534800,
  "expires_in_seconds": 3600
}

    /verify (GET)

    Dieser Endpunkt wird von Caddys forward_auth verwendet, um zu prüfen, ob die IP des Clients auf der Whitelist steht. Er gibt bei Erfolg 200 OK und bei Misserfolg 401 Unauthorized zurück. X-Forwarded-For, X-Forwarded-Host und X-Forwarded-Uri werden nur als vertrauenswürdig eingestuft, wenn die Anfrage von server.trusted_proxies stammt.

    Caddy leitet die relevanten X-Forwarded-*-Request-Header bereits an Knocker weiter, sodass /verify die Auth-Entscheidung treffen kann.

    Tests

    Das Projekt enthält eine vollständige Testsuite.

    Werkzeuge

    Dieses Projekt verwendet Astral's Python-Toolchain:

    • uv für Abhängigkeitsverwaltung, Umgebungen und Befehlsausführung
    • ruff für Linting und Formatierung
    • ty für Typprüfung

    Unit-Tests

    So führst du die Tests lokal aus:

    1. uv installieren:

      root@kitploit:~
      curl -LsSf https://astral.sh/uv/install.sh | sh

    2. Projektumgebung synchronisieren:

      root@kitploit:~
      uv sync --all-groups

    3. Überprüfungen ausführen:

      root@kitploit:~
      uv run pytest
uv run --group lint ruff check .
uv run --group lint ruff format --check .
uv run --group type ty check

    Integrationstests

    Es gibt eine Entwicklungsumgebung unter dev, mit Bash-Skripten für Integrationstests mit Caddy und getrennt davon mit firewalld. Die Standard-Test-Stacks sind dev/docker-compose.yml und dev/docker-compose.ci.yml; beide exponieren Caddy auf http://localhost:18080 und https://localhost:18443. Der CI führt die Caddy-Tests aus, aber firewalld benötigt einen privilegierten Runner, weshalb es lokal ausgeführt werden muss und nicht Teil des CI ist.

    Docs

    Interaktive Dokumentationsendpunkte (/docs, /redoc, /openapi.json) sind standardmäßig deaktiviert. Um sie zu aktivieren, setze Folgendes in knocker.yaml:

    root@kitploit:~
    documentation:
  enabled: true
  openapi_output_path: "openapi.json"

    Wenn die Dokumentation deaktiviert ist (Standard), entfernt Knocker diese Endpunkte und löscht alle zuvor generierten Schema-Dateien, um veraltete Artefakte zu vermeiden.

    Eine formelle API-Spezifikation und eine Zusammenfassung der architektonischen Entscheidungen findest du in der Dokumentation.

    Vollständig vibe-coded

    Knocker wurde vollständig vibe-coded. Die anfängliche Implementierung erfolgte mit Gemini 2.5 Pro, dank der Token, die im Roo Code/Requesty-Hackathon zur Verfügung gestellt wurden.

    Weitere Funktionen wurden größtenteils mit dem GitHub Copilot Agent (Sonnet 4/später 4.5) erstellt, der viele Korrekturen benötigte, die hauptsächlich von GPT-5 mini/CODEX in Roo Code, Opencode und der Standard-Copilot-Erweiterung durchgeführt wurden.

    Ich habe mein Bestes gegeben, Änderungen stets geplant und nach jeder Änderung getestet. Aber wenn du Anti-KI bist, werde ich deine Meinung dazu wahrscheinlich nicht ändern können.