Knocker est un service auto-hébergé qui fournit une passerelle d'autorisation par paquet unique (SPA) « knock-knock » basée sur HTTP pour votre Homelab, avec des clients web, cli + gnome et android. Il peut être utilisé comme authentification pour votre reverse proxy comme Caddy, ou même au niveau du pare-feu grâce à l'intégration FirewallD. Il vous permet de garder vos services complètement privés, en les ouvrant à la demande uniquement pour les adresses IP autorisées.

C'est idéal pour les environnements homelab où vous souhaitez exposer des services à Internet sans connexion VPN persistante, tout en minimisant votre surface d'attaque exposée publiquement.

Fonctionnalités

Authentification par clé API : Sécurisez votre endpoint knock avec plusieurs clés API configurables.
TTL configurable : Chaque clé API peut avoir son propre Time-To-Live (TTL), définissant combien de temps une IP whitelistée reste active.
Whitelisting distant : Accordez à des clés admin spécifiques la permission de whitelister n'importe quelle IP ou plage CIDR, pas seulement la leur.
Whitelisting IP/CIDR statique : Autorisez toujours certaines adresses IP ou plages à contourner la whitelist dynamique.
Exclusion limitée à l'hôte : Gardez les chemins intentionnellement publics limités au bon hôte virtuel.
IPv6 citoyen de première classe : Prise en charge complète d'IPv6 et IPv4 dans le whitelisting, les proxys de confiance et le réseau Docker.
Intégration Firewalld : Contrôle avancé du pare-feu avec des règles temporisées qui expirent automatiquement selon le TTL. Crée des règles de pare-feu dynamiques à l'aide des rich rules de firewalld pour une sécurité renforcée. (Optionnel, nécessite un accès root au conteneur)

Clients Knocker

Knocker-Web Application web PWA statique qui prend en charge le knock (whitelisting) au rechargement
Knocker-CLI Un cli écrit en go avec prise en charge des knocks en arrière-plan, déclenchés optionnellement par des changements d'IP.
Knocker-gnome une extension gnome construite au-dessus de Knocker-cli.
Knocker-EXPO Une application Android expérimentale écrite en React EXPO avec prise en charge des requêtes de knock en arrière-plan

Diagramme de séquence

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)

Déploiement

Ce projet est conçu pour être déployé en tant que conteneur Docker à l'aide du fichier docker-compose.yml fourni. Il utilise les images docker pré-construites avec prise en charge d'AMD64, ARMv8 et ARMv7

Tags d'image Docker

Knocker fournit différents tags d'image pour différents cas d'usage :

latest Dernière version stable (recommandée pour la production)
v1.2.3 Tags de version spécifiques (versions épinglées)
main Branche de développement (mises à jour continues, peut être instable)

Registres

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

1. Prérequis

Docker et Docker Compose installés.
Un serveur exposé publiquement pour exécuter les conteneurs (il n'a même pas besoin d'être sur le même serveur que celui exécutant les services ! EN MODE PROXY)
(Optionnel) Firewalld 2.0+ installé et en cours d'exécution sur l'hôte pour une intégration avancée du pare-feu.

Configuration :
- Renommez knocker.example.yaml en knocker.yaml.
- Ajoutez au moins une clé API sécurisée et aléatoire à knocker.yaml ; l'exemple ne contient intentionnellement aucune valeur par défaut utilisable.
- Vérifiez la liste trusted_proxies dans knocker.yaml : elle doit contenir uniquement la ou les adresses du reverse proxy lui-même, pas son sous-réseau. Comme knocker ne fait confiance à X-Forwarded-For que provenant d'un pair listé, une entrée couvrant tout un sous-réseau (par ex. 172.16.238.0/24) transforme chaque conteneur de ce réseau en autorité d'identité -- n'importe lequel d'entre eux pourrait prétendre n'importe quelle IP client, ou whitelister des adresses arbitraires avec une clé ordinaire. Docker n'attribue pas d'IP de conteneur stables par défaut, donc épinglez le proxy avec ipv4_address / ipv6_address (voir le service caddy commenté dans docker-compose.yml) et listez ces adresses exactes en /32 et /128.
- Gardez whitelist.storage_path sous le répertoire de travail de l'application, /data, ou /tmp.
- (Optionnel) Configurez l'intégration firewalld en définissant firewalld.enabled: true et en ajustant les paramètres associés. Note : Cela nécessite que le conteneur s'exécute en tant que root.
Lancer le service :
```
docker compose up -d
```
Cela va récupérer l'image knocker pré-construite et démarrer les services knocker et caddy.

Utiliser knocker avec un reverse proxy

Knocker fonctionne en agissant comme passerelle d'authentification pour votre reverse proxy. Il offre un endpoint verify, pour vérifier si l'IP demandeuse est whitelistée ou non ; si ce n'est pas le cas, il répondra avec un 401 et le reverse proxy refusera la connexion.

Caddy

Caddy dispose de la directive forward_auth pour vérifier les connexions à l'aide d'un endpoint d'authentification.

Définir un snippet réutilisable : Il est de bonne pratique de définir un snippet dans votre Caddyfile pour la vérification d'authentification.
Protéger vos services : Importez le snippet pour tout service que vous souhaitez protéger.

Exemple de 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
}

Échecs d'autorisation

Lorsqu'un utilisateur n'est pas whitelisté, la directive forward_auth de Caddy renverra une réponse 401 Unauthorized avec un corps vide.

Note importante : La directive handle_errors de Caddy ne fonctionne pas avec les réponses de forward_auth. La réponse d'erreur provient directement du service d'authentification (knocker), et non de Caddy lui-même, donc handle_errors ne peut pas intercepter ni modifier ces réponses.

knocker

Populaires