Knocker è un servizio self-hosted che fornisce un gateway HTTP di single-packet authorization (SPA) "knock-knock" per il tuo Homelab, con client web, cli + gnome e android. Può essere utilizzato come autenticazione per il tuo reverse proxy come Caddy, o persino a livello di firewall tramite l'integrazione con FirewallD. Ti permette di mantenere i tuoi servizi completamente privati, aprendoli on-demand solo per indirizzi IP autorizzati.

Questo è ideale per ambienti homelab in cui vuoi esporre servizi su internet senza una connessione VPN persistente, riducendo al minimo la tua superficie di attacco pubblica.

Funzionalità

Autenticazione con API Key: Proteggi il tuo endpoint di knock con più API key configurabili.
TTL Configurabile: Ogni API key può avere il proprio Time-To-Live (TTL), che definisce per quanto tempo un IP in whitelist rimane attivo.
Whitelisting Remoto: Concedi a specifiche admin key il permesso di inserire in whitelist qualsiasi IP o range CIDR, non solo il proprio.
Whitelisting IP/CIDR Statico: Consenti sempre a determinati indirizzi IP o range di bypassare la whitelist dinamica.
Esclusione per Host: Mantieni i percorsi intenzionalmente pubblici limitati al virtual host corretto.
IPv6 Cittadino di Prima Classe: Supporto completo per IPv6 e IPv4 nel whitelisting, nei trusted proxy e nel networking Docker.
Integrazione Firewalld: Controllo avanzato del firewall con regole temporizzate che scadono automaticamente in base al TTL. Crea regole firewall dinamiche usando le rich rule di firewalld per una sicurezza avanzata. (Opzionale, richiede accesso root al container)

Client di Knocker

Knocker-Web App web PWA statica che supporta il knocking (whitelisting) al reload
Knocker-CLI Una cli scritta in go con supporto per knock in background attivati opzionalmente da cambi di IP.
Knocker-gnome un'estensione gnome costruita sopra Knocker-cli.
Knocker-EXPO Un'app Android sperimentale scritta in React EXPO con supporto per richieste di knocking in background

Diagramma di sequenza

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)

Deployment

Questo progetto è progettato per essere distribuito come container Docker utilizzando il file docker-compose.yml fornito. Utilizza le immagini docker pre-costruite con supporto per AMD64, ARMv8 e ARMv7

Tag delle Immagini Docker

Knocker fornisce diversi tag immagine per diversi casi d'uso:

latest Ultima release stabile (consigliata per la produzione)
v1.2.3 Tag di versione specifici (versioni bloccate)
main Branch di sviluppo (aggiornamenti continui, potrebbe essere instabile)

Registries

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

1. Prerequisiti

Docker e Docker Compose installati.
Un server esposto pubblicamente per eseguire i container (non deve nemmeno essere sullo stesso server che esegue i servizi! IN PROXY MODE)
(Opzionale) Firewalld 2.0+ installato e in esecuzione sull'host per l'integrazione avanzata con il firewall.

Configurazione:
- Rinomina knocker.example.yaml in knocker.yaml.
- Aggiungi almeno una API key sicura e casuale a knocker.yaml; l'esempio non contiene intenzionalmente alcun default utilizzabile.
- Rivedi la lista trusted_proxies in knocker.yaml: deve contenere solo l'indirizzo (o gli indirizzi) del reverse proxy stesso, non la sua subnet. Poiché knocker si fida di X-Forwarded-For solo da un peer elencato, una voce che copre l'intera subnet (es. 172.16.238.0/24) trasforma ogni container su quella rete in un'autorità di identità -- chiunque di essi potrebbe dichiarare qualsiasi IP client, o inserire in whitelist indirizzi arbitrari con una key normale. Docker non assegna IP stabili ai container per default, quindi fissa il proxy con ipv4_address / ipv6_address (vedi il servizio caddy commentato in docker-compose.yml) e elenca quegli indirizzi esatti /32 e /128.
- Mantieni whitelist.storage_path sotto la directory di lavoro dell'app, /data, o /tmp.
- (Opzionale) Configura l'integrazione firewalld impostando firewalld.enabled: true e regolando le impostazioni correlate. Nota: Questo richiede che il container venga eseguito come root.
Avvia il Servizio:
```
docker compose up -d
```
Questo scaricherà l'immagine knocker pre-costruita e avvierà entrambi i servizi knocker e caddy.

Usare knocker con un Reverse Proxy

Knocker funziona agendo come gateway di autenticazione per il tuo reverse Proxy. Offre un endpoint di verify, per verificare se l'IP richiedente è in whitelist o meno; in caso contrario risponderà con un 401 e il reverse proxy rifiuterà la connessione.

Caddy

Caddy ha la direttiva forward_auth per verificare le connessioni usando un endpoint di autenticazione.

Definisci uno Snippet Riutilizzabile: È buona pratica definire uno snippet nel tuo Caddyfile per il controllo di autenticazione.
Proteggi i Tuoi Servizi: Importa lo snippet per qualsiasi servizio che vuoi proteggere.

Esempio di Caddyfile:

# Caddyfile

# Define a reusable snippet for the knock-knock check.
# It points to the knocker service using Docker's internal DNS.
(knocker_auth) {
  forward_auth knocker:8000 {
    uri /verify
  }
}

# The public endpoint for performing the knock.
# Make sure this domain points to your Caddy server's IP.
knock.your-domain.com {
  request_body {
    max_size 4KB
  }
  reverse_proxy knocker:8000
}

# An example protected service.
jellyfin.your-domain.com {
  import knocker_auth  # Apply the forward_auth check
  reverse_proxy jellyfin_service_name:8096
}

Fallimenti di Autorizzazione

Quando un utente non è in whitelist, la direttiva forward_auth di Caddy restituirà una risposta 401 Unauthorized con body vuoto.

Nota Importante: La direttiva handle_errors di Caddy non funziona con le risposte di forward_auth. La risposta di errore proviene direttamente dal servizio di autenticazione (knocker), non da Caddy stesso, quindi handle_errors non può intercettare o modificare queste risposte.

Integrazione FirewallD

Knocker fornisce un'integrazione avanzata con il firewall tramite firewalld, creando regole firewall dinamiche e temporali che scadono automaticamente in base al TTL specificato nelle richieste di knock. Questa funzionalità opera a livello di rete, permettendoti di usare knocker per servizi non-http come ssh o server di gioco.

knocker

Più Popolari