Skip to content
KitploitKITPLOIT
StrumentiBlog
Invia
StrumentiBlog
Invia

Strumenti di Hacking, PenTest e Cybersecurity per il tuo Arsenale di Sicurezza!

Kitploit è una directory di strumenti di hacking, cybersecurity e pentesting. Scopri gli ultimi aggiornamenti dei progetti per trovare vulnerabilità, analizzare sistemi, automatizzare i test e rafforzare la tua sicurezza.

··Feed·Contatto·Privacy·© 2026 Kitploit

Directory degli strumenti

Categorie

Vedi tutte le categorie
Loading categories
knocker — Knocker, un servizio di controllo accessi basato su knock per il tuo homelab | Kitploit
Strumenti/GitHubGitHub/fariszr/knocker
Sicurezza di ReteSicurezza CloudDevSecOpsAutenticazioneSicurezza delle API
GitHubfariszr/knocker

knocker

Knocker, un servizio di controllo accessi basato su knock per il tuo homelab

Vedi Repository
135413 giorni faRevisionato da Kitploit

Più Popolari

Vedi tutti →

Scopri gli strumenti più utilizzati dalla nostra community.

Esplora tutti gli strumenti

Sfoglia la nostra collezione di strumenti

Vedi tutti gli strumenti →
Condividi

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

Scarica lo strumento

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

    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)

    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.

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

    2. Avvia il servizio:

      root@kitploit:~
      docker compose up -d

      Questo scaricherà l'immagine knocker precompilata e avvierà i servizi knocker e caddy.

    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.

    1. Definisci uno snippet riutilizzabile: è buona pratica definire uno snippet nel tuo Caddyfile per il controllo di autenticazione.

    2. Proteggi i tuoi servizi: importa lo snippet per qualsiasi servizio che vuoi proteggere.

    Esempio di Caddyfile:

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

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

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

    Abilitazione dell'integrazione FirewallD

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

    2. 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:

    root@kitploit:~
    # 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):
        root@kitploit:~
        {"ip_address": "YOUR_TARGET_IP_OR_CIDR"}

    • Esempio (Inserimento del proprio IP in whitelist):

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

    • Risposta di successo (200 OK):

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

    1. Installa uv:

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

    2. Sincronizza l'ambiente del progetto:

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

    3. Esegui i controlli:

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

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