HL-PRC-020 — WatchTower — raccordement des connecteurs de supervision

PROCÉDURE TECHNIQUE

Raccordement des connecteurs de supervision et passerelles à WatchTower

Configuration des accès d’API de service (Guacamole, NPM, Technitium, Gitea, CrowdSec, Wazuh, Proxmox VE), contournement 2FA et sécurisation du coffre de clés.

Sommaire

Raccordement des connecteurs de supervision et passerelles à WatchTower — HL-PRC-020

1 Objet

Cette procédure détaille l’intégration et le raccordement technique des connecteurs d’infrastructure au sein de la plateforme WatchTower (hébergée dans le conteneur LXC 2013). Elle décrit la création des comptes de service dédiés, la génération des jetons d’authentification pour chaque composant supervisé (passerelle d’accès distant Apache Guacamole, reverse proxy Nginx Proxy Manager, serveur DNS Technitium, forge logicielle Gitea, moteur de sécurité CrowdSec LAPI, pile SIEM Wazuh Indexer et Manager, grappe Proxmox VE et agent Hermes), ainsi que leur enregistrement dans le coffre chiffré de WatchTower. À l’issue de la procédure, l’ensemble des connecteurs doit présenter le statut joignable (« OK »), permettant à WatchTower d’assurer la découverte automatique, la télémétrie unifiée et le pilotage opérationnel, les identifiants étant protégés par le coffre chiffré de WatchTower.

La difficulté principale réside dans la disparité des mécanismes d’authentification des composants tiers et les exigences de fonctionnement « headless » de WatchTower : Apache Guacamole impose par défaut un enrôlement 2FA/TOTP bloquant les connexions automatisées (nécessitant une dérogation au niveau de la base de données PostgreSQL), l’API locale de CrowdSec écoute nativement sur l’interface de boucle locale (127.0.0.1) interdisant les requêtes distantes, la sonde interne WatchTower pour Gitea exige une authentification explicite sur les instances privées (erreur 403 Forbidden corrigée dans le code du catalogue), et la pile Wazuh sépare l’API de gestion (port 55000) du moteur d’indexation (port 9200). Le non-respect de ces particularités provoque des échecs d’authentification silencieux ou des interruptions de service.

2 Périmètre et prérequis

Périmètre

Couvert : création des comptes et jetons de service sur Apache Guacamole, Nginx Proxy Manager, Technitium DNS, Gitea, CrowdSec et Wazuh ; modification de la configuration d’écoute LAPI de CrowdSec ; désactivation ciblée de la contrainte TOTP sur Guacamole pour le compte de service API ; correction de la sonde d’authentification du catalogue WatchTower pour Gitea ; déclaration des identifiants et des URL dans l’interface d’administration WatchTower ; persistance et chiffrement des clés dans le coffre local (/opt/watchtower/donnees/).

Hors périmètre : déploiement initial du conteneur WatchTower et de son API REST (déjà opérationnels) ; configuration des règles de filtrage pare-feu transverses du Juniper SRX300 (traitées dans HL-PRC-001) ; déploiement des services tiers sous-jacents (Gitea, Wazuh, Guacamole, Technitium) ; intégration des assistants conversationnels externes (OpenAI/Anthropic).

Prérequis

• Conteneur WatchTower opérationnel : CT 2013 actif sur pve1, API watchtower-api.service en écoute sur le port 8000, frontend accessible via le reverse proxy NPM (https://watchtower.srv.dozylab.lan).

• Passerelle Apache Guacamole accessible : instance opérationnelle sur 10.10.10.20:8080, base PostgreSQL guacamole_db accessible en local ou via terminal d’administration.

• Reverse Proxy Nginx Proxy Manager fonctionnel : instance active sur 10.10.20.12, port d’administration web 81 joignable en HTTP depuis le VLAN serveurs.

• Serveur Technitium DNS joignable : conteneur 2011 actif sur 10.10.20.11, interface web et API REST opérationnelles sur le port 5380.

• Instance Gitea disponible : conteneur 2014 opérationnel sur 10.10.20.15:3000 avec instance configurée en mode privé (REQUIRE_SIGNIN_VIEW).

• Moteur CrowdSec déployé : serveur opérationnel sur 10.10.20.22, utilitaire cscli accessible en ligne de commande root.

• Pile Wazuh opérationnelle : Wazuh Indexer accessible sur 10.10.20.20:9200 et Wazuh Manager accessible sur 10.10.20.20:55000.

• Grappe Proxmox VE active : nœuds pve1 (10.10.10.10), pve2 (10.10.10.11), pve3 (10.10.10.12) avec API REST active sur le port 8006.

• Agent Hermes déployé : instance active sur 10.10.80.10 avec API server opérationnelle sur le port 8642.

Note Versions validées sur le terrain. Procédure validée le 26/10/2026 sur l’infrastructure DozyLab avec WatchTower v1.0 (branche surcouche/reconciliation-auth-collecteurs), Apache Guacamole v1.5.x, Nginx Proxy Manager v2.11, Technitium DNS Server v13, Gitea v1.22, CrowdSec v1.6, Wazuh v4.9, Proxmox VE 9.x et Debian 12 (bookworm).

3 Rôles et responsabilités

Note Homelab individuel. Les trois rôles sont assumés par la même personne. La distinction est maintenue pour assurer la rigueur opérationnelle, le cloisonnement des privilèges et la traçabilité des accès.

4 Procédure de raccordement des connecteurs

Paramètres de la procédure

Les paramètres ci-dessous fixent les valeurs du lab pour les services supervisés, leurs interfaces d’API et les comptes de service associés.

Attention Substitution des paramètres. Les blocs de commandes ci-après contiennent les valeurs de référence réelles de l’infrastructure DozyLab. Lors d’une réplication sur un autre environnement, les adresses IP et secrets doivent être substitués avant exécution. Aucun jeton secret ne doit être consigné en clair dans un script non sécurisé.

Inventaire des connecteurs et interfaces cibles

Le tableau ci-dessous récapitule l’ensemble des connecteurs intégrés à WatchTower, leur méthode d’authentification et leurs exigences de communication.

Étapes de réalisation

1. Raccordement et contournement 2FA de la passerelle Apache Guacamole

Principe et contrainte d’authentification headless : L’extension TOTP de Guacamole force par défaut l’inscription d’un second facteur pour tous les comptes. Lors d’une connexion via l’API REST (POST /api/tokens), Guacamole renvoie une erreur HTTP 403 « TOTP enrollment must be completed before authentication can continue », ce qui empêche tout raccordement automatisé. La création d’une dérogation s’effectue en injectant l’attribut guac-totp-disabled positionné à true dans la base de données PostgreSQL guacamole_db.

1. Se connecter à l’interface web de Guacamole (https://guacamole.adm.dozylab.lan/guacamole) avec le compte administrateur.2. Dans Paramètres > Utilisateurs, cliquer sur Nouvel utilisateur et créer le compte watchtower avec un mot de passe robuste.3. Ne cocher aucun privilège d’administration. Dans la section Connexions, attribuer les droits de lecture aux connexions destinées à être visualisées dans WatchTower.4. Ouvrir une session SSH sur le serveur hébergeant la base PostgreSQL de Guacamole (10.10.10.20) et injecter la dérogation TOTP pour le compte watchtower :

Connexion à PostgreSQL et application de la dérogation 2FA
su – postgres -c "psql -d guacamole_db" << 'EOF'
INSERT INTO guacamole_user_attribute (user_id, attribute_name, attribute_value)
SELECT u.user_id, 'guac-totp-disabled', 'true'
FROM guacamole_user u
JOIN guacamole_entity e ON u.entity_id = e.entity_id
WHERE e.name = 'watchtower'
ON CONFLICT (user_id, attribute_name)
DO UPDATE SET attribute_value = 'true';
EOF

Validation du jeton API sans 2FA : Tester immédiatement la génération d’un jeton d’authentification via l’API REST depuis la console :

curl -s -X POST "http://10.10.10.20:8080/guacamole/api/tokens" \
  -d "username=watchtower&password=MOT_DE_PASSE_GUACAMOLE"

Sortie attendue : Un objet JSON contenant "authToken":"…","username":"watchtower","dataSource":"postgresql". Aucune demande d’enrôlement TOTP ne doit être renvoyée.

5. Dans WatchTower > Paramètres > Connecteurs > Guacamole > Configurer : – Adresse : http://10.10.10.20:8080/guacamole (ou https://guacamole.adm.dozylab.lan/guacamole) – Utilisateur : watchtower – Mot de passe : le mot de passe attribué – Vérifier le certificat TLS : désactivé si appel en HTTP direct ou certificat auto-signé.6. Cliquer sur Tester la connexion puis Enregistrer.

2. Configuration du connecteur Nginx Proxy Manager

Protocole d’administration et autorisations : L’interface d’administration de Nginx Proxy Manager écoute nativement sur le port TCP 81 en HTTP simple. Tenter une connexion en HTTPS sur ce port provoque une interruption brutale du handshake SSL. Le compte de service doit disposer des droits de consultation sur l’ensemble des hôtes proxy et des certificats pour que WatchTower puisse inventorier les règles de publication.

1. Se connecter à l’interface d’administration de NPM (http://10.10.20.12:81) avec le compte administrateur.2. Dans le menu Users, cliquer sur Add User et renseigner les informations : – First Name : WatchTower, Last Name : Service – Email : watchtower@dozylab.lan – Roles : cocher Permissions sur All Items (Proxy Hosts, Redirection Hosts, SSL Certificates en mode View). Ne pas attribuer le rôle Administrator.3. Dans l’onglet Permissions, s’assurer que les accès en lecture seule sont validés et enregistrer.4. Dans WatchTower > Paramètres > Connecteurs > Nginx Proxy Manager > Configurer : – Adresse : http://10.10.20.12:81 (impérativement en http:// et non https://) – Adresse de connexion : watchtower@dozylab.lan – Mot de passe : mot de passe du compte de service5. Cliquer sur Tester la connexion puis Enregistrer.

3. Génération du jeton d’API Technitium DNS

Persistance de la session de supervision : L’interrogation des zones et enregistrements Technitium DNS sur le port 5380 s’effectue au moyen d’un jeton d’API (API Token). Pour éviter toute interruption de supervision lors de l’expiration des sessions web, le jeton doit être configuré avec une durée de validité illimitée.

1. Se connecter à l’interface Technitium DNS (http://10.10.20.11:5380).2. Accéder à Administration > Sessions.3. Cliquer sur Create API Token : – Name / Description : watchtower-probe – Validity : Never expires (validité permanente)4. Valider et copier immédiatement le jeton affiché dans le presse-papier.5. Tester la validité du jeton en ligne de commande depuis le conteneur WatchTower :

curl -s "http://10.10.20.11:5380/api/zones/list?token=TOKEN_SECRET" | grep -o '"status":"ok"'

Sortie attendue : "status":"ok".6. Dans WatchTower > Paramètres > Connecteurs > Technitium DNS > Configurer : – Adresse : http://10.10.20.11:5380 – Jeton d’API : coller le jeton généré7. Cliquer sur Tester la connexion puis Enregistrer.

4. Raccordement Gitea et correction de la sonde du catalogue WatchTower

Contradiction doc/terrain et correction logicielle : Sur une instance Gitea configurée en mode privé (directive REQUIRE_SIGNIN_VIEW = true dans app.ini), toute consultation anonyme d’une route d’API — y compris la vérification de version logicielle /api/v1/version — est rejetée avec le code HTTP 403 Forbidden. La sonde interne _sonde_gitea de WatchTower effectuait initialement un appel GET sans en-tête d’autorisation, provoquant l’échec systématique du test de connectivité. Il est impératif d’injecter le jeton d’authentification dans la sonde et de redémarrer le service d’API.

1. Sur l’instance Gitea (http://10.10.20.15:3000), se connecter avec le compte de service ou l’administrateur.2. Accéder à Paramètres > Applications > Gestion des jetons d’accès personnels.3. Générer un nouveau jeton : – Nom du jeton : watchtower-connector – Portées cochées : read:repository, read:organization, read:user4. Copier la chaîne de jeton (visible une seule fois).5. Ouvrir une session sur le conteneur WatchTower (CT 2013) et éditer le fichier du catalogue de connecteurs :

Sauvegarde du fichier de catalogue original
cp /opt/watchtower/apps/api/watchtower_api/connecteurs/catalogue.py \
/opt/watchtower/apps/api/watchtower_api/connecteurs/catalogue.py.bak

6. Dans la fonction _sonde_gitea, remplacer l’appel sans en-tête par l’appel authentifié transmettant le header Authorization: token <jeton> :

Extrait corrigé dans /opt/watchtower/apps/api/watchtower_api/connecteurs/catalogue.py
async def _sonde_gitea(client: httpx.AsyncClient, valeurs: dict[str, Any]) -> tuple[bool, str]:
adresse = valeurs.get("adresse", "").rstrip("/")
jeton = valeurs.get("jeton", "")
headers = {"Authorization": f"token {jeton}"} if jeton else {}
try:
r = await client.get(f"{adresse}/api/v1/version", headers=headers, timeout=5.0)
if r.status_code == 200:
v = r.json().get("version", "inconnue")
return True, f"Gitea {v}"
return False, f"Code HTTP {r.status_code}"
except Exception as e:
return False, str(e)

7. Redémarrer le service API WatchTower pour charger le correctif :

systemctl restart watchtower-api
systemctl status watchtower-api --no-pager

Validation du jeton Gitea en ligne de commande : Vérifier que le jeton permet bien d’interroger l’API avec succès :

curl -i -H "Authorization: token e2800bb86bb78c881998a10cd400daeaf05c145c" \
  "http://10.10.20.15:3000/api/v1/user"

Sortie attendue : HTTP/1.1 200 OK avec le corps JSON contenant l’identifiant, le statut is_admin et les paramètres du profil.8. Dans WatchTower > Paramètres > Connecteurs > Gitea > Configurer : – Adresse : http://10.10.20.15:3000 – Jeton d’accès : coller le jeton généré9. Cliquer sur Tester la connexion puis Enregistrer.

5. Déclaration du bouncer CrowdSec et ouverture d’écoute LAPI

Liaison réseau de la LAPI et contrôle d’accès : Par défaut, le démon CrowdSec lie son API locale (LAPI) à l’adresse de bouclage 127.0.0.1:8080. Les requêtes en provenance d’autres conteneurs ou machines du VLAN serveurs sont systématiquement rejetées par le noyau. L’écoute doit être étendue à 0.0.0.0:8080 dans la directive api.server.listen_uri, et une clé de bouncer dédiée doit être enregistrée dans la base CrowdSec.

1. Se connecter en console root sur le serveur CrowdSec (10.10.20.22).2. Enregistrer un bouncer nommé watchtower :

cscli bouncers add watchtower

Sortie attendue : Génération et affichage de la clé d’API du bouncer (chaîne de 32 caractères alphanumériques). Consigner cette clé dans Vaultwarden.3. Éditer le fichier de configuration principal /etc/crowdsec/config.yaml :

Modification de l'écoute LAPI dans /etc/crowdsec/config.yaml
sed -i 's/listen_uri: 127.0.0.1:8080/listen_uri: 0.0.0.0:8080/' /etc/crowdsec/config.yaml
systemctl restart crowdsec

4. Vérifier que le démon écoute bien sur toutes les interfaces réseau :

ss -tlpn | grep 8080

Sortie attendue : LISTEN 0 4096 0.0.0.0:8080 0.0.0.0:* users:(("crowdsec",pid=…,fd=…)).5. Valider la joignabilité de l’API depuis le conteneur WatchTower :

curl -s -H "X-Api-Key: CLE_BOUNCER_CROWDSEC" \
  http://10.10.20.22:8080/v1/decisions

Sortie attendue : Réponse JSON (tableau vide [] ou null si aucune décision de bannissement active, prouvant que la clé est acceptée).6. Dans WatchTower > Paramètres > Connecteurs > CrowdSec > Configurer : – Adresse : http://10.10.20.22:8080 – Clé de bouncer : coller la clé générée par cscli7. Cliquer sur Tester la connexion puis Enregistrer.

6. Raccordement des composants Wazuh (Indexer et Manager)

Dissociation de l’indexation et de la gestion : La solution Wazuh all-in-one héberge deux points d’accès distincts : l’Indexer (moteur OpenSearch sur le port TCP 9200) et le Manager (API de pilotage sur le port TCP 55000). Renseigner le port 55000 pour l’Indexer provoque une erreur HTTP 404. De même, les comptes d’authentification diffèrent : l’Indexer utilise un compte de sécurité interne (readall), tandis que le Manager s’appuie sur les utilisateurs de l’API Wazuh.

1. Raccordement du connecteur Wazuh Indexer : – Adresse : https://10.10.20.20:9200 – Utilisateur : readall (compte stocké dans Vaultwarden avec privilèges de lecture sur les index wazuh-alerts-*) – Mot de passe : mot de passe du compte readall – Vérifier le certificat TLS : Décoché (certificat auto-signé natif)2. Vérifier la réponse de l’Indexer en console :

curl -k -u readall:MOT_DE_PASSE https://10.10.20.20:9200/

Sortie attendue : JSON avec "cluster_name":"wazuh-cluster" et "version":{"number":"2.x.x"…}.3. Raccordement du connecteur Wazuh Manager API : – Adresse : https://10.10.20.20:55000 – Utilisateur : wazuh (ou wazuh-wui) – Mot de passe : mot de passe extrait du fichier de configuration du dashboard (/usr/share/wazuh-dashboard/data/wazuh/config/wazuh.yml) – Vérifier le certificat TLS : Décoché4. Tester les deux connecteurs et enregistrer.

7. Raccordement de la grappe Proxmox VE et de l’agent Hermes

Haute disponibilité et privilèges sans séparation : Un jeton d’API unique partagé au niveau de la grappe Proxmox permet de surveiller les trois hyperviseurs (pve1, pve2, pve3). L’option –privsep 0 est rigoureusement obligatoire : avec la séparation de privilèges par défaut (–privsep 1), le jeton s’authentifie avec succès mais n’hérite d’aucun droit d’inventaire sur les nœuds et les conteneurs.

1. Sur le nœud pve1 (la configuration étant répliquée sur toute la grappe via corosync) :

Création du compte d'audit et du jeton sans séparation de privilèges
pveum user add watchtower@pve --comment "Compte de supervision WatchTower"
pveum acl modify / --users watchtower@pve --roles PVEAuditor
pveum user token add watchtower@pve lecture --privsep 0

Sortie attendue : Affichage du Token ID (watchtower@pve!lecture) et de la valeur secrète (value). Copier le secret immédiatement.2. Dans WatchTower > Paramètres > Connecteurs > Proxmox VE > Configurer : – Créer un nœud pour pve1 (https://10.10.10.10:8006), pve2 (https://10.10.10.11:8006) et pve3 (https://10.10.10.12:8006) – Identifiant du jeton : watchtower@pve!lecture – Secret du jeton : valeur secrète générée – Vérifier le certificat TLS : Décoché3. Raccordement de l’agent Hermes : – Récupérer la clé API sur la machine Hermes (10.10.80.10) : grep API_SERVER_KEY ~/.hermes/.env – Dans WatchTower > Connecteurs > Hermes : Adresse http://10.10.80.10:8642, clé API_SERVER_KEY – Adresse tableau de bord : http://10.10.80.10:9119 avec identifiants admin.4. Valider l’ensemble des tests de connexion.

8. Initialisation du coffre de clés et vérification globale des sondes

Chiffrement local et intégrité de session : Au premier enregistrement d’un connecteur, WatchTower initialise automatiquement sa clé de chiffrement symétrique dans le fichier /opt/watchtower/donnees/coffre.cle. Les requêtes de test exécutées depuis l’interface web s’appuient sur un jeton JWT dont la validité est de 15 minutes. Si la session expire, l’interface renvoie une erreur 401 Unauthorized « Refusé : Session requise », imposant une réauthentification avant de poursuivre les tests.

1. Se connecter à l’interface WatchTower (https://watchtower.srv.dozylab.lan).2. Dans Paramètres > Connecteurs, cliquer sur le bouton Tout tester.3. Vérifier que le compteur en en-tête affiche l’ensemble des connecteurs au vert (« Joignable »).4. Ouvrir une session SSH sur le conteneur WatchTower et contrôler la création et les permissions du coffre chiffré :

ls -la /opt/watchtower/donnees/
file /opt/watchtower/donnees/coffre.cle

Sortie attendue : Le fichier coffre.cle est présent avec les droits stricts 600 (-rw——-) appartenant au propriétaire du service api.5. Sauvegarder la clé du coffre dans Vaultwarden (élément WatchTower – Coffre Clé) pour faciliter la recouvrabilité en cas de restauration du conteneur sans volume persistant.

Retour arrière

En cas de dysfonctionnement bloquant lors de la configuration des connecteurs ou de l’application des correctifs, exécuter les actions ci-dessous :

Pièges connus

Les anomalies ci-après ont été réellement constatées lors des opérations de raccordement et de qualification des connecteurs dans l’infrastructure DozyLab.

5 Intégration réseau

Identité des instances

Le tableau ci-dessous recense l’ensemble des composants intervenant dans l’architecture de supervision et leur localisation dans les zones de sécurité.

Plan d’adressage et interfaces

Matrice des flux réseau

Dépendances et points de défaillance

6 Durcissement et sécurité

• Principe de moindre privilège sur les comptes de service : Aucun connecteur n’utilise de compte administrateur racine (root, admin global). Chaque composant est configuré avec un compte d’audit dédié restreint à la seule lecture (PVEAuditor sur Proxmox, rôle Viewer sur NPM, compte readall sur Wazuh Indexer).

• Chiffrement symétrique des secrets au repos : L’intégralité des identifiants et jetons enregistrés dans WatchTower est chiffrée de manière symétrique dans /opt/watchtower/donnees/ au moyen d’une clé locale (coffre.cle). Les secrets ne figurent jamais en clair dans la base de données applicative.

• Cloisonnement strict par zones pare-feu : Le conteneur WatchTower réside dans le VLAN serveurs (zone srv). Ses communications vers les hyperviseurs de gestion (zone adm) et l’agent Hermes (zone lab) sont strictement filtrées par port sur le pare-feu Juniper SRX300.

• Exclusion des secrets de la gestion de versions : Le dossier /opt/watchtower/donnees/ et le fichier .env sont exclus de l’arbre Git via le fichier .gitignore, garantissant qu’aucune clé ou jeton ne soit poussé sur les forges publiques ou privées.

• Contrôle d’accès aux fichiers sensibles du système : Le fichier /opt/watchtower/donnees/coffre.cle est protégé par les droits stricts 600 (-rw——-), interdisant sa lecture par tout autre utilisateur que le service système watchtower-api.

Dettes techniques

7 Vérifications finales

Exécuter les contrôles ci-dessous pour prononcer la recette fonctionnelle et la qualification des connecteurs de WatchTower.

8 Références et historique des révisions

Documentation éditeur

• Apache Guacamole Project : Guacamole Manual — REST API Authentication and TOTP Extension Configuration (2026). Établit la structure des requêtes API tokens et la table des attributs utilisateurs.

• CrowdSec : CrowdSec Documentation — Local API (LAPI) and Bouncers Configuration (2026). Établit les paramètres de liaison réseau (listen_uri) et l’enregistrement de bouncers.

• Gitea Project : Gitea Documentation — API Authentication and Private Instance Scopes (2026). Établit l’obligation d’en-tête d’autorisation sur instance privée.

• Nginx Proxy Manager : Official Documentation — Host Configuration, Custom SSL and Admin API (2026). Établit les prérequis de droits sur le port 81.

• Technitium : Technitium DNS Server HTTP API Documentation (2026). Établit la syntaxe des jetons d’authentification permanents.

• Wazuh Server Solutions : Wazuh User Manual — RESTful API Reference and Indexer Authentication (2026). Établit la distinction entre les ports 55000 et 9200.

• Proxmox Server Solutions : Proxmox VE Administration Guide — API Tokens and Privileges Separation (2026). Établit le rôle PVEAuditor et l’option –privsep 0.

Documents associés

• HL-PRC-001 : Mise en service du pare-feu Juniper SRX300.

• HL-PRC-003 : Mise en service de la grappe Proxmox à trois nœuds.

• HL-PRC-004 : Technitium DNS.

• HL-PRC-006 : Wazuh all-in-one.

• HL-PRC-007 : Hermes Agent.

• HL-PRC-010 : Guacamole — Connexion SSH par clé.

• HL-PRC-012 : Publication de ProxPanel via Nginx Proxy Manager.

Historique des révisions