Caddy Plugin

Caddy v2 Plugin (Zero-Code)

Das offizielle Caddy v2 Plugin für Hansestack ermöglicht Decoupled Security: Du hängst den k-Anonymity Leak-Check direkt in deinen Reverse Proxy, ohne auch nur eine Zeile Code in deinem Backend anfassen zu müssen.

Das Plugin fängt Requests ab, prüft enthaltene Passwörter datenschutzkonform und reichert den Request oder die Response mit dem Ergebnis an. Dein Backend benötigt keinen eigenen API-Client.

Ressourcen & Hands-on

🐙 Source Code: Quellcode, Releases und den Issue-Tracker findest du im caddy-hansestack Repository.
👾 Sandbox testen: Willst du das Plugin in Aktion sehen? Clone unser Demo-Repo, tippe docker-compose up und verfolge im mitgelieferten Grafana-Dashboard live, wie der Leak-Check (und das Fail-Open) unter Last reagiert.

Installation

Es gibt zwei Wege, das Plugin in deiner Infrastruktur zu nutzen.

Option A: Build mit xcaddy (Empfohlen)

Wenn du deine Caddy-Binaries selbst baust, nutze xcaddy:

xcaddy build --with github.com/hansestack/caddy-hansestack

Option B: Pre-built Docker Image

Wir stellen ein fertiges Docker-Image (basierend auf dem offiziellen Caddy-Image) zur Verfügung:

# docker-compose.yml
services:
  caddy:
    image: ghcr.io/hansestack/caddy-hansestack:latest
    ports:
      - "80:80"
      - "443:443"

(Tipp: Pinne in Produktion eine feste Version statt :latest, z.B. :v1.0.0)

Konfiguration (Caddyfile)

Die Konfiguration erfolgt nativ im Caddyfile. Das Plugin registriert sich automatisch so, dass es in der Aufrufreihenfolge vor dem reverse_proxy ausgeführt wird.

:443 {
    hansestack /login* leakcheck {
        api_key {$HANSESTACK_API_KEY}
        mode enrich_response
        password_field "password"
        
        # Optionale Circuit Breaker Konfiguration für hohe Resilienz
        timeout 500ms
        circuit_breaker_threshold 5
        circuit_breaker_cooldown 30s
    }

    reverse_proxy backend:8080
}

Konfigurations-Parameter

Direktive	Standardwert	Beschreibung
`api_key`	(Pflichtfeld)	Dein Hansestack API-Key. (Nutze `{$ENV_VAR}` für Umgebungsvariablen).
`mode`	`enrich_request`	Modus: `enrich_request`, `enrich_response` oder `block`.
`password_field`	`password`	Der Key im JSON oder Form-Data, der das Passwort enthält.
`header_leaked`	`X-Hansestack-Leaked`	Header, der das Ergebnis (true/false) enthält.
`header_count`	`X-Hansestack-Leak-Count`	Header mit der Anzahl der gefundenen Leaks.
`block_status`	`401`	HTTP Status-Code, wenn `mode=block` greift.
`timeout`	`500ms`	Maximale Wartezeit für den API-Aufruf (Fail-Open greift danach).
`circuit_breaker_threshold`	deaktiviert (0)	Anzahl aufeinanderfolgender Fehler, bevor der Breaker auslöst.
`circuit_breaker_cooldown`	`30s`	Dauer, für die der Breaker neue Requests lokal sofort durchwinkt.

Operations-Modi

Je nach Architektur deines Auth-Flows bietet das Plugin drei verschiedene Modi:

enrich_response (Empfohlen): Asynchron. Der Leak-Check läuft parallel zur Verarbeitung deines Backends. Es fügt absolut keine spürbare Latenz zum Login hinzu. Die Leak-Header werden der ausgehenden Response (auf dem Weg zum Client) hinzugefügt.

    sequenceDiagram
    participant C as Client
    participant P as Caddy (Plugin)
    participant B as Dein Backend
    participant H as Hansestack API

    C->>P: POST /login (Credentials)
    
    par Asynchroner Leak-Check
        P->>H: Sende Hash-Präfix
        H-->>P: Suffix-Liste (Kein Leak)
    and Normaler Login-Flow
        P->>B: POST /login (Original Body)
        Note over B: Backend verifiziert Login
        B-->>P: HTTP 201 (Session Token)
    end
    
    P-->>C: HTTP 201 + X-Hansestack-Leaked Header

enrich_request: Synchron. Wartet auf die API (max. timeout) und fügt die Leak-Header dem eingehenden Request hinzu. Dein Backend kann diese Header lesen und selbst entscheiden, was zu tun ist.
block: Synchron. Die einzige Methode, die den Request abweisen kann. Nur wenn ein Leak zweifelsfrei bestätigt wurde, wird der Request direkt vom Caddy mit z.B. HTTP 401 abgelehnt. Dein Backend wird in diesem Fall nie aufgerufen.

Fail-Open by Design
In allen Modi gilt: Bei API-Timeouts, Rate-Limits oder Netzwerkfehlern wird der Request immer unverändert durchgelassen. Der Login-Flow deiner echten Nutzer wird durch einen Ausfall des Leak-Checks niemals blockiert.

Metriken (Prometheus)

Wenn du Caddys globale metrics-Option aktivierst, stellt das Plugin eigene Metriken am Admin-Endpunkt bereit. Diese eignen sich ideal für Grafana-Dashboards, um Angriffe sichtbar zu machen:

hansestack_leakcheck_checks_total{result="leaked|not_leaked"}
hansestack_leakcheck_check_outcomes_total{outcome="..."} (Zeigt detailliert, ob ein Check erfolgreich war oder ob Timeouts/Circuit Breaker gegriffen haben)
hansestack_leakcheck_check_errors_total

Quickstart Integrations-Workflows