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

È ideale per ambienti homelab in cui vuoi esporre servizi a internet senza una connessione VPN persistente, minimizzando al contempo la superficie d'attacco pubblica.

Caratteristiche

Autenticazione tramite API Key: Proteggi il tuo endpoint knock con più chiavi API 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.
Whitelist remota: Concedi a specifiche chiavi admin il permesso di mettere in whitelist qualsiasi IP o range CIDR, non solo il proprio.
Whitelist statica IP/CIDR: Consenti sempre a determinati indirizzi IP o range di bypassare la whitelist dinamica.
Esclusione basata sul percorso: Escludi determinati percorsi URL (come health check o API pubbliche) dall'autenticazione.
IPv6 di prima classe: Supporto completo per IPv6 e IPv4 in whitelist, proxy fidati e networking Docker.
Integrazione Firewalld: Controllo avanzato del firewall con regole temporizzate che scadono automaticamente in base al TTL. Crea regole firewall dinamiche utilizzando le rich rules di firewalld per una sicurezza potenziata. (Opzionale, richiede accesso root al container)

Client Knocker

Knocker-Web App web PWA statica che supporta il knocking (whitelisting) al ricaricamento
Knocker-CLI Una CLI scritta in Go con supporto per knock in background opzionalmente attivati da cambi di IP.
Knocker-gnome un'estensione di GNOME costruita sopra Knocker-cli.
Knocker-EXPO Un'app Android sperimentale scritta in React EXPO con supporto per richieste di knock 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)

Distribuzione

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

Tag delle immagini Docker

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

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

Registry

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

1. Prerequisiti

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

Configurazione:
- Rinomina knocker.example.yaml in knocker.yaml.
- Fondamentale: cambia le chiavi API predefinite in knocker.yaml con le tue stringhe casuali e sicure.
- Controlla l'elenco trusted_proxies in knocker.yaml: deve corrispondere alla sottorete della rete del reverse proxy (docker network inspect xxx)
- Mantieni whitelist.storage_path nella directory di lavoro dell'app, in /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
```

Usare Knocker con un reverse proxy

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

Caddy

Caddy ha la direttiva forward_auth per verificare le connessioni tramite 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 {
  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
}

Errori di autorizzazione

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

Nota importante: la direttiva handle_errors di Caddy non funziona con le risposte 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 del firewall tramite firewalld, creando regole firewall dinamiche e basate sul tempo 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.

Diagramma di sequenza (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)

    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 richiede FirewallD 2.0+ a causa della dipendenza dalla funzionalità di priorità delle zone. È disponibile in Debian 13, Ubuntu 24.04 LTS e altre recenti distribuzioni stabili.

Perché FirewallD?

FirewallD è stato scelto per la capacità di separare l'interfaccia CLI dal demone. Questo permette a Knocker di controllare firewalld dall'interno di un container Docker montando il socket D-Bus di sistema, e FirewallD supporta anche regole temporizzate, quindi le regole di Knocker scadono automaticamente alla fine del TTL.

FIREWALLD NON FUNZIONERÀ CON LE PORTE PUBBLICATE DI DOCKER, consulta questo problema per maggiori dettagli

Come funziona

Crea una zona firewalld dedicata con priorità alta
Aggiunge regole DROP/REJECT per le porte monitorate per bloccare l'accesso non autorizzato
Aggiunge dinamicamente regole ALLOW per gli IP in whitelist che sovrascrivono le regole di blocco
Fa scadere automaticamente le regole in base al TTL utilizzando il meccanismo di timeout di firewalld
Recupera le regole all'avvio confrontando whitelist.json con le regole firewalld attive

Abilitazione dell'integrazione FirewallD

Prerequisiti
- FirewallD 2.0+ installato e in esecuzione sul sistema host
- Il container Docker deve essere eseguito come root per l'accesso a D-Bus
Configurazione

Abilita FirewallD nella configurazione knocker.yaml; le impostazioni sono già disponibili nella configurazione di esempio
Monta il socket D-Bus nel container Docker e assicurati che venga eseguito come root; le voci richieste sono commentate nel file docker-compose.yml.

Test e risoluzione dei problemi

Monitora le regole attive:

# Check knocker zone
firewall-cmd --zone=knocker --list-all

# View rich rules
firewall-cmd --zone=knocker --list-rich-rules

# Monitor rule changes
journalctl -u firewalld -f

Per informazioni dettagliate su configurazione, architettura e risoluzione dei problemi, consulta la Guida completa all'integrazione FirewallD.

Problemi legati a userland-proxy

Se stai abilitando il knocking per IP dietro Tailscale o altri IP, potresti incontrare problemi a causa del funzionamento di userland-proxy: potresti ricevere un IP di richiesta diverso dall'indirizzo IP effettivo.

Disabilitare Userland-proxy dovrebbe risolvere il problema, ma assicurati di testare la tua configurazione. Puoi anche usare la rete host.

Utilizzo dell'API

`/knock` (POST)

Questo endpoint valida una chiave API e inserisce un IP in whitelist.

Headers:
- X-Api-Key: La tua chiave API segreta.
Body (Opzionale):
- Per inserire in whitelist un IP/CIDR remoto (richiede allow_remote_whitelist: true):
```
{"ip_address": "YOUR_TARGET_IP_OR_CIDR"}
```

Esempio (Inserimento del proprio IP in whitelist):

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

Risposta di successo (200 OK):

{
  "whitelisted_entry": "1.2.3.4",
  "expires_at": 1672534800,
  "expires_in_seconds": 3600
}

`/verify` (GET)

Questo endpoint viene utilizzato da forward_auth di Caddy per verificare se l'IP del client è in whitelist. Restituisce 200 OK in caso di successo e 401 Unauthorized in caso di fallimento. X-Forwarded-For, X-Forwarded-Host e X-Forwarded-Uri sono considerati affidabili solo quando la richiesta proviene da server.trusted_proxies.

Caddy inoltra già le intestazioni di richiesta X-Forwarded-* pertinenti a Knocker, così /verify può prendere la decisione di autenticazione.

Test

Il progetto include una suite di test completa

Strumenti

Questo progetto utilizza la toolchain Python di Astral:

uv per la gestione delle dipendenze, degli ambienti e dell'esecuzione dei comandi
ruff per linting e formattazione
ty per il type checking

Unit test

Per eseguire i test localmente:

Installa uv:

curl -LsSf https://astral.sh/uv/install.sh | sh

Sincronizza l'ambiente del progetto:
```
uv sync --all-groups
```

Esegui i controlli:

uv run pytest
uv run --group lint ruff check .
uv run --group lint ruff format --check .
uv run --group type ty check

Test di integrazione

C'è un ambiente di sviluppo in dev, con script bash per i test di integrazione con caddy e uno separato con firewalld. Gli stack di test standard sono dev/docker-compose.yml e dev/docker-compose.ci.yml; entrambi espongono Caddy su http://localhost:18080 e https://localhost:18443. La CI esegue i test di Caddy, ma firewalld richiede un runner privilegiato, motivo per cui deve essere eseguito localmente e non fa parte della CI.

Documentazione

Gli endpoint di documentazione interattiva (/docs, /redoc, /openapi.json) sono disabilitati per impostazione predefinita. Per esporli, imposta quanto segue in knocker.yaml:

documentation:
  enabled: true
  openapi_output_path: "openapi.json"

Quando la documentazione è disabilitata (impostazione predefinita), Knocker rimuove questi endpoint ed elimina qualsiasi file schema generato in precedenza per prevenire artefatti obsoleti.

Per una specifica API formale e un riepilogo delle scelte architetturali, consulta la documentazione.

Completamente vibe-coded

Knocker è stato interamente vibe-coded. L'implementazione iniziale è stata realizzata con Gemini 2.5 Pro, grazie ai token forniti nell'hackathon roo code/requesty.

Le funzionalità successive sono state realizzate principalmente con GitHub Copilot Agent (sonnet 4 / successivamente 4.5), che ha richiesto molte correzioni, fatte principalmente da GPT-5 mini/CODEX in Roo code, Opencode e l'estensione Copilot standard.

Ho fatto del mio meglio, pianificando sempre le modifiche e testando tutto dopo ogni cambiamento, ma se sei contrario all'AI probabilmente non riuscirei a cambiare la tua opinione su questo.

knocker

Più Popolari