Dépannage : problèmes courants de connectivité de l'agent

L'agent StateWarden est conçu pour une résilience autonome. Cependant, sa capacité à sécuriser votre infrastructure repose entièrement sur l'établissement d'une connexion réseau irréprochable, mutuellement authentifiée (mTLS), avec le plan de contrôle Artemis et le plan de données Driad.

Si un appareil apparaît « hors ligne » dans le Dashboard ou n'exécute pas les tâches planifiées, le problème provient presque systématiquement de restrictions réseau au niveau de l'hôte.

Voici le guide de référence pour diagnostiquer et résoudre les échecs de connectivité de l'agent.

1. Comprendre le cycle de vie de l'agent

Au démarrage du service sw (StateWarden) sur une machine cible, celui-ci exécute une séquence de démarrage stricte :

1. État d'attente réseau : l'agent suspend ses workers internes jusqu'à ce que le plan de contrôle Artemis soit joignable. Cela évite que l'agent ne plante pendant les premières phases du démarrage de l'OS, avant que la pile réseau soit entièrement initialisée.
2. Poignée de main mTLS : une fois le réseau disponible, l'agent tente une connexion TLS mutuellement authentifiée vers Artemis à l'aide de son certificat client unique, stocké localement.
3. Boucle d'opérations : en cas de succès, l'agent établit une connexion persistante avec le plan de contrôle, transmet la télémétrie système (CPU, RAM, statut) et attend des tâches telles que des sauvegardes et des analyses de sécurité.

2. Étapes de diagnostic principales

Si votre agent ne parvient pas à se connecter, effectuez ces vérifications directement sur la machine hôte affectée.

Vérification 1 : résolution DNS

L'agent doit pouvoir résoudre les FQDN de votre infrastructure StateWarden.

• Action : envoyez un ping vers l'API du plan de contrôle (par ex. api.statewarden.com ou votre domaine personnalisé).
• Résolution : si le nom d'hôte ne se résout pas, vérifiez les paramètres DNS de la machine. Dans des environnements d'entreprise fortement restreints, vous devrez peut-être ajouter des entrées manuelles au fichier local /etc/hosts ou C:\Windows\System32\drivers\etc\hosts.

Vérification 2 : règles de pare-feu sortantes (port 443)

StateWarden fonctionne exclusivement en HTTPS standard (port 443). Aucun port entrant ne doit être ouvert sur vos pare-feux. C'est toujours l'agent qui initie la connexion.

• Action : assurez-vous que le pare-feu local de la machine hôte (Pare-feu Windows Defender, iptables, ufw) autorise le trafic TCP sortant sur le port 443 vers les plages IP StateWarden.
• Action : vérifiez que les pare-feux périmétriques d'entreprise (Palo Alto, Fortinet) ne bloquent pas ce trafic.

Vérification 3 : inspection profonde des paquets (DPI) et proxys

C'est la cause la plus courante d'échec mTLS dans les environnements d'entreprise. StateWarden utilise un TLS mutuel strict. Si votre réseau d'entreprise utilise un proxy d'inspection SSL « Man-in-the-Middle » (MitM) (qui intercepte le trafic, le déchiffre et le rechiffre avec un certificat d'entreprise), la connexion échouera immédiatement.

• L'erreur : les journaux de l'agent afficheront tls: unknown certificate authority ou bad certificate. Artemis rejettera la connexion, car le proxy détruit le certificat client unique de l'agent pendant l'interception.
• Résolution : vous devez explicitement mettre en liste blanche les domaines StateWarden (*.statewarden.com ou vos endpoints spécifiques) dans votre appliance d'inspection SSL afin de contourner la DPI et d'autoriser le trafic brut en passthrough.

3. Lecture des journaux de l'agent

En cas de doute, consultez les journaux internes de l'agent. StateWarden fournit une journalisation très verbose, de niveau développeur.

• Linux : journalctl -u statewarden -f
• Windows : ouvrez l'Observateur d'événements ou consultez les fichiers journaux bruts, généralement situés dans C:\ProgramData\StateWarden\logs\.

Signatures de journaux courantes :

• failed to dial Artemis: connection refused -> l'IP se résout, mais un pare-feu bloque le port 443.
• handshake failure: bad certificate -> votre certificat mTLS est corrompu, révoqué, ou un proxy SSL interfère.
• waiting for Artemis health check... -> l'agent n'a aucune connexion réseau, ou le DNS échoue.

4. Réappairage forcé

Si le coffre cryptographique local d'un agent est corrompu (par ex. à la suite d'une panne disque catastrophique), il sera définitivement exclu du Realm.

Vous ne pouvez pas « récupérer » un certificat d'agent perdu. Vous devez forcer le réappairage de l'appareil.

1. Dans le Dashboard, supprimez l'ancienne entrée de l'appareil (cela révoque son ancien certificat).
2. Générez un nouveau code d'appairage.
3. Sur la machine hôte, désinstallez complètement l'agent (ce qui efface le coffre local) et réinstallez-le avec le nouveau code.

StateWarden : la résilience par l'ingénierie.