Fehlerbehebung: Häufige Verbindungsprobleme des Agenten

Der StateWarden-Agent ist für autonome Resilienz ausgelegt. Seine Fähigkeit, Ihre Infrastruktur zu schützen, hängt jedoch vollständig davon ab, eine fehlerfreie, gegenseitig authentifizierte (mTLS) Netzwerkverbindung zur Artemis Control Plane und zur Driad Data Plane aufzubauen.

Wenn ein Gerät im Dashboard als „OFFLINE" erscheint oder geplante Aufgaben nicht ausführt, liegt die Ursache fast immer in Netzwerkbeschränkungen auf Host-Ebene.

Dies ist die maßgebliche Anleitung zur Diagnose und Behebung von Verbindungsfehlern des Agenten.

1. Den Lebenszyklus des Agenten verstehen

Wenn der Dienst sw (StateWarden) auf einer Zielmaschine startet, durchläuft er eine strikte Boot-Sequenz:

Netzwerk-Wartezustand: Der Agent hält seine internen Worker an, bis die Artemis Control Plane erreichbar ist. Dies verhindert, dass der Agent während früher Boot-Phasen des Betriebssystems abstürzt, bevor der Netzwerk-Stack vollständig initialisiert ist.
mTLS-Handshake: Sobald das Netzwerk verfügbar ist, versucht der Agent eine gegenseitig authentifizierte TLS-Verbindung (Mutual TLS) zu Artemis mit seinem eindeutigen, lokal gespeicherten Clientzertifikat.
Betriebsschleife: Nach dem erfolgreichen Aufbau stellt der Agent eine persistente Verbindung zur Control Plane her, überträgt Systemtelemetrie (CPU, RAM, Status) und wartet auf Aufgaben wie Backups und Sicherheitsscans.

2. Primäre Diagnoseschritte

Wenn Ihr Agent keine Verbindung herstellen kann, führen Sie diese Prüfungen direkt auf der betroffenen Host-Maschine durch.

Prüfung 1: DNS-Auflösung

Der Agent muss die FQDNs Ihrer StateWarden-Infrastruktur auflösen können.

Aktion: Pingen Sie die Control-Plane-API (z. B. api.statewarden.com oder Ihre benutzerdefinierte Domain).
Lösung: Wenn der Hostname nicht aufgelöst wird, prüfen Sie die DNS-Einstellungen der Maschine. In stark eingeschränkten Unternehmensumgebungen müssen Sie möglicherweise manuelle Einträge in die lokale Datei /etc/hosts oder C:\Windows\System32\drivers\etc\hosts aufnehmen.

Prüfung 2: Ausgehende Firewall-Regeln (Port 443)

StateWarden arbeitet ausschließlich über Standard-HTTPS (Port 443). Es müssen keine eingehenden Ports auf Ihren Firewalls geöffnet werden. Der Agent initiiert die Verbindung immer.

Aktion: Stellen Sie sicher, dass die lokale Firewall der Host-Maschine (Windows Defender Firewall, iptables, ufw) ausgehenden TCP-Verkehr auf Port 443 zu den StateWarden-IP-Bereichen zulässt.
Aktion: Verifizieren Sie, dass Unternehmens-Perimeter-Firewalls (Palo Alto, Fortinet) den Verkehr nicht blockieren.

Prüfung 3: Deep Packet Inspection (DPI) und Proxys

Dies ist die häufigste Ursache für mTLS-Fehler in Unternehmensumgebungen. StateWarden verwendet striktes Mutual TLS. Wenn Ihr Unternehmensnetzwerk einen SSL-Inspektions-Proxy vom Typ „Man-in-the-Middle" (MitM) einsetzt (der den Verkehr abfängt, entschlüsselt und mit einem Unternehmenszertifikat neu verschlüsselt), schlägt die Verbindung hart fehl.

Der Fehler: Die Protokolle des Agenten zeigen tls: unknown certificate authority oder bad certificate. Artemis lehnt die Verbindung ab, weil der Proxy das eindeutige Clientzertifikat des Agenten während des Abfangvorgangs zerstört.
Lösung: Sie müssen die StateWarden-Domains (*.statewarden.com oder Ihre spezifischen Endpunkte) in Ihrer SSL-Inspektions-Appliance explizit auf eine Whitelist setzen, um DPI zu umgehen und unveränderten Passthrough-Verkehr zuzulassen.

3. Die Agenten-Protokolle lesen

Konsultieren Sie im Zweifel die internen Protokolle des Agenten. StateWarden bietet sehr ausführliche Protokollierung auf Entwicklerebene.

Linux: journalctl -u statewarden -f
Windows: Öffnen Sie die Ereignisanzeige oder prüfen Sie die Rohprotokolle, üblicherweise unter C:\ProgramData\StateWarden\logs\.

Häufige Protokoll-Signaturen:

failed to dial Artemis: connection refused -> Die IP wird aufgelöst, aber eine Firewall blockiert Port 443.
handshake failure: bad certificate -> Ihr mTLS-Zertifikat ist beschädigt oder widerrufen, oder ein SSL-Proxy stört.
waiting for Artemis health check... -> Der Agent hat überhaupt keine Netzwerkverbindung, oder DNS schlägt fehl.

4. Erzwungenes erneutes Pairing

Wenn der lokale kryptografische Tresor eines Agenten beschädigt wird (z. B. durch einen katastrophalen Festplattenausfall), wird er dauerhaft aus dem Realm ausgesperrt.

Sie können ein verlorenes Agenten-Zertifikat nicht „wiederherstellen". Sie müssen das Gerät zwangsweise neu koppeln.

Löschen Sie im Dashboard den alten Geräteeintrag (dadurch wird sein altes Zertifikat widerrufen).
Generieren Sie einen neuen Kopplungscode.
Deinstallieren Sie auf der Host-Maschine den Agenten vollständig (dadurch wird der lokale Tresor gelöscht) und installieren Sie ihn mit dem neuen Code erneut.

StateWarden: Resilience Engineered.