Skip to content
KitploitKITPLOIT
OutilsBlog
Soumettre
OutilsBlog
Soumettre

Outils de Hacking, PenTest et Cybersécurité pour votre Arsenal de Sécurité !

Kitploit est un répertoire d'outils de hacking, de cybersécurité et de pentesting. Découvrez les dernières mises à jour des projets pour trouver des vulnérabilités, analyser des systèmes, automatiser les tests et renforcer votre sécurité.

··Flux·Contact·Confidentialité·© 2026 Kitploit

Répertoire d'outils

Catégories

Voir toutes les catégories
Loading categories
Outils/GitHubGitHub/fariszr/knocker
Sécurité RéseauSécurité CloudDevSecOpsAuthentificationSécurité des API
GitHubfariszr/knocker

knocker

Knocker, un service de contrôle d'accès basé sur le knock pour votre homelab

Voir le dépôt
1354il y a 13 joursVérifié par Kitploit

Populaires

Voir tout →

Découvrez les outils les plus utilisés par notre communauté.

Explorer tous les outils

Parcourez notre collection d'outils

Voir tous les outils →
Partager

Knocker est un service auto-hébergé qui fournit une passerelle d'autorisation à paquet unique (SPA) de type "toc-toc" basée sur HTTP pour votre Homelab, avec des clients web, CLI + GNOME et Android. Il peut être utilisé comme authentification pour votre proxy inverse comme Caddy, ou même au niveau du pare-feu via l'intégration FirewallD. Il vous permet de garder vos services complètement privés, en ne les ouvrant à la demande que pour les adresses IP autorisées.

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

Fonctionnalités

  • Authentification par clé API : sécurisez votre endpoint knock avec plusieurs clés API configurables.
  • TTL configurable : chaque clé API peut avoir sa propre durée de vie (TTL), définissant combien de temps une IP autorisée reste active.
  • Autorisation à distance : accordez à certaines clés admin la permission d'autoriser n'importe quelle IP ou plage CIDR, pas seulement la leur.
  • Autorisation statique IP/CIDR : autorisez toujours certaines adresses IP ou plages à contourner la liste blanche dynamique.
  • Exclusion par chemin : excluez entièrement certains chemins d'URL (comme les health checks ou les API publiques) de l'authentification.
  • IPv6 en citoyen de première classe : prise en charge complète d'IPv6 et d'IPv4 pour l'autorisation, 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 (mise sur liste blanche) au rechargement

  • Knocker-CLI Une CLI écrite en Go avec prise en charge des knocks en arrière-plan, éventuellement déclenchés 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

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)

Déploiement

Ce projet est conçu pour être déployé comme 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'images Docker

Knocker fournit différents tags d'images pour différents cas d'utilisation :

  • 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 accessible publiquement pour exécuter les conteneurs (il n'a même pas besoin d'être sur le même serveur que celui qui exécute les services ! EN MODE PROXY)
  • (Optionnel) FirewallD 2.0+ installé et exécuté sur l'hôte pour une intégration avancée du pare-feu.

  1. Configuration :

    • Renommez knocker.example.yaml en knocker.yaml.
    • Crucial : modifiez les clés API par défaut dans knocker.yaml avec vos propres chaînes aléatoires sécurisées.
    • Vérifiez la liste trusted_proxies dans knocker.yaml ; elle doit correspondre au sous-réseau du réseau du proxy inverse (docker network inspect xxx).
    • Conservez whitelist.storage_path dans 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. Remarque : cela nécessite que le conteneur s'exécute en tant que root.

  2. Exécutez le service :

    root@kitploit:~
    docker compose up -d

    Cela récupérera l'image knocker préconstruite et démarrera à la fois les services knocker et caddy.

Utiliser knocker avec un proxy inverse

Knocker agit comme une passerelle d'authentification pour votre proxy inverse. Il offre un endpoint de vérification pour contrôler si l'IP requérante est autorisée ou non ; si ce n'est pas le cas, il répond par un 401 et le proxy inverse refuse la connexion.

Caddy

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

  1. Définissez un snippet réutilisable : il est recommandé de définir un snippet dans votre Caddyfile pour la vérification d'authentification.

  2. Protégez vos services : importez le snippet pour tout service que vous souhaitez protéger.

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

Échecs d'authentification

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

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

Intégration FirewallD

Knocker fournit une intégration avancée du pare-feu via firewalld, créant des règles de pare-feu dynamiques et temporisées qui expirent automatiquement en fonction du TTL spécifié dans les requêtes de knock. Cette fonctionnalité opère au niveau réseau, ce qui vous permet d'utiliser knocker pour des services non-HTTP comme SSH ou des serveurs de jeu.

Diagramme de séquence (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 nécessite FirewallD 2.0+ en raison de sa dépendance à la fonctionnalité de priorité de zone. Il est disponible dans Debian 13, Ubuntu 24.04 LTS et d'autres distributions stables récentes.

Pourquoi FirewallD ?

FirewallD a été choisi pour sa capacité à séparer l'interface CLI du démon. Cela permet à Knocker de contrôler firewalld depuis un conteneur Docker en montant le socket D-Bus du système. FirewallD prend également en charge les règles temporisées, de sorte que les règles de knocker expirent automatiquement à la fin du TTL.

FIREWALLD NE FONCTIONNERA PAS AVEC LES PORTS PUBLIÉS DE DOCKER, consultez ce problème pour plus de détails

Comment ça marche

  1. Crée une zone firewalld dédiée avec une priorité élevée
  2. Ajoute des règles DROP/REJECT pour les ports surveillés afin de bloquer les accès non autorisés
  3. Ajoute dynamiquement des règles ALLOW pour les IP autorisées, qui remplacent les règles de blocage
  4. Fait automatiquement expirer les règles en fonction du TTL à l'aide du mécanisme de délai d'expiration de firewalld
  5. Restaure les règles au démarrage en comparant whitelist.json avec les règles firewalld actives

Activer l'intégration FirewallD

  1. Prérequis

    • FirewallD 2.0+ installé et exécuté sur le système hôte
    • Le conteneur Docker doit s'exécuter en tant que root pour l'accès D-Bus

  2. Configuration

  • Activez FirewallD dans la configuration knocker.yaml ; les paramètres sont déjà disponibles dans la configuration d'exemple
  • Montez le socket D-Bus dans le conteneur Docker et assurez-vous qu'il s'exécute en tant que root ; les entrées requises sont commentées dans le fichier docker-compose.yml.

Tests et dépannage

Surveillez les règles actives :

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

Pour des informations détaillées sur la configuration, l'architecture et le dépannage, consultez le Guide d'intégration FirewallD complet.

Problèmes liés au userland-proxy

Si vous activez le knock pour des IP derrière Tailscale ou d'autres IP, vous pouvez rencontrer des problèmes en raison du fonctionnement de userland-proxy ; vous pouvez obtenir une IP de requête différente de l'adresse IP réelle.

Désactiver Userland-proxy devrait résoudre le problème, mais assurez-vous de tester votre configuration. Vous pouvez également utiliser le réseau de l'hôte (host networking).

Utilisation de l'API

/knock (POST)

Cet endpoint valide une clé API et autorise une IP.

  • En-têtes :

    • X-Api-Key : votre clé API secrète.

  • Corps (optionnel) :

    • Pour autoriser une IP/CIDR distante (nécessite allow_remote_whitelist: true) :
      root@kitploit:~
      {"ip_address": "YOUR_TARGET_IP_OR_CIDR"}

  • Exemple (autoriser votre propre IP) :

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

  • Réponse de succès (200 OK) :

    root@kitploit:~
    {
  "whitelisted_entry": "1.2.3.4",
  "expires_at": 1672534800,
  "expires_in_seconds": 3600
}

/verify (GET)

Cet endpoint est utilisé par forward_auth de Caddy pour vérifier si l'IP du client est autorisée. Il renvoie 200 OK en cas de succès et 401 Unauthorized en cas d'échec. X-Forwarded-For, X-Forwarded-Host et X-Forwarded-Uri ne sont considérés comme fiables que lorsque la requête provient de server.trusted_proxies.

Caddy transmet déjà les en-têtes de requête X-Forwarded-* pertinents à Knocker afin que /verify puisse prendre la décision d'authentification.

Tests

Le projet inclut une suite de tests complète

Outillage

Ce projet utilise la chaîne d'outils Python d'Astral :

  • uv pour la gestion des dépendances, les environnements et l'exécution de commandes
  • ruff pour le linting et le formatage
  • ty pour la vérification de types

Tests unitaires

Pour exécuter les tests localement :

  1. Installez uv :

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

  2. Synchronisez l'environnement du projet :

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

  3. Exécutez les vérifications :

    root@kitploit:~
    uv run pytest
uv run --group lint ruff check .
uv run --group lint ruff format --check .
uv run --group type ty check

Tests d'intégration

Il y a un environnement de développement dans dev, avec des scripts bash pour les tests d'intégration avec caddy et un autre avec firewalld. Les piles de test standard sont dev/docker-compose.yml et dev/docker-compose.ci.yml ; toutes deux exposent Caddy sur http://localhost:18080 et https://localhost:18443. Le CI exécute les tests caddy, mais firewalld nécessite un runner privilégié, c'est pourquoi il doit être exécuté localement et ne fait pas partie du CI.

Documentation

Les endpoints de documentation interactive (/docs, /redoc, /openapi.json) sont désactivés par défaut. Pour les exposer, définissez ce qui suit dans knocker.yaml :

root@kitploit:~
documentation:
  enabled: true
  openapi_output_path: "openapi.json"

Lorsque la documentation est désactivée (par défaut), Knocker supprime ces endpoints et efface tout fichier de schéma précédemment généré afin d'éviter des artefacts obsolètes.

Pour une spécification formelle de l'API et un résumé des choix architecturaux, veuillez consulter la documentation.

Entièrement vibe-codé

Knocker a été entièrement vibe-codé. L'implémentation initiale a été réalisée avec Gemini 2.5 pro, grâce aux tokens fournis lors du hackathon roo code/requesty.

Les fonctionnalités supplémentaires ont été principalement développées avec l'agent GitHub Copilot (sonnet 4/plus tard 4.5), qui a nécessité de nombreuses corrections, effectuées principalement par GPT-5 mini/CODEX dans Roo code, Opencode et l'extension Copilot standard.

J'ai fait de mon mieux, en planifiant toujours les changements et en testant tout après chaque modification, mais si vous êtes anti-IA, je ne pourrai probablement pas changer votre opinion à ce sujet.

Télécharger l’outil