Troubleshooting: Common Agent Connectivity Issues

The StateWarden Agent is designed for autonomous resilience. However, its ability to secure your infrastructure relies entirely on establishing a pristine, mutually authenticated (mTLS) network connection with the Artemis Control Plane and Driad Data Plane.

If a Device appears "Offline" in the Dashboard or fails to execute scheduled tasks, the issue almost universally stems from host-level network restrictions.

Here is the authoritative guide to diagnosing and resolving Agent connectivity failures.

1. Understanding the Agent Lifecycle

When the sw (StateWarden) service starts on a target machine, it executes a strict boot sequence:

1. Network Wait State: The Agent pauses its internal workers until it can successfully ping the Artemis /health endpoint. This prevents the Agent from crashing during early OS boot phases before the network stack is fully initialized.
2. mTLS Handshake: Once the network is up, the Agent attempts a Mutually Authenticated TLS connection to Artemis using its unique, locally stored client certificate.
3. Heartbeat Loop: Upon success, the Agent drops into a persistent WebSocket or polling loop, transmitting system telemetry (CPU, RAM, Status) and waiting for commands (START_BACKUP, SECURITY_SCAN).

2. Primary Diagnostic Steps

If your Agent is failing to connect, perform these checks directly on the affected host machine.

Check 1: DNS Resolution

The Agent must be able to resolve the FQDNs of your StateWarden infrastructure.

• Action: Ping the Control Plane API (e.g., api.statewarden.com or your custom domain).
• Resolution: If the hostname fails to resolve, verify the machine's DNS settings. In heavily restricted enterprise environments, you may need to add manual entries to the local /etc/hosts or C:\Windows\System32\drivers\etc\hosts file.

Check 2: Outbound Firewall Rules (Port 443)

StateWarden operates exclusively over standard HTTPS (Port 443). We do not require any inbound ports to be opened on your firewalls. The Agent always initiates the connection.

• Action: Ensure the host machine's local firewall (Windows Defender Firewall, iptables, ufw) permits outbound TCP traffic on Port 443 to the StateWarden IP ranges.
• Action: Verify that corporate edge firewalls (Palo Alto, Fortinet) are not blocking the traffic.

Check 3: Deep Packet Inspection (DPI) and Proxies

This is the most common cause of mTLS failure in corporate environments. StateWarden uses strict Mutual TLS. If your corporate network utilizes a "Man-in-the-Middle" (MitM) SSL inspection proxy (which intercepts traffic, decrypts it, and re-encrypts it using a corporate certificate), the connection will fail violently.

• The Error: The Agent's logs will show tls: unknown certificate authority or bad certificate. Artemis will reject the connection because the proxy destroys the Agent's unique client certificate during the interception process.
• Resolution: You must explicitly whitelist the StateWarden domains (*.statewarden.com or your specific endpoints) in your SSL inspection appliance to bypass DPI and allow raw passthrough traffic.

3. Reading the Agent Logs

When in doubt, consult the Agent's internal logs. StateWarden provides highly verbose, developer-grade logging.

• Linux: journalctl -u sw-agent.service -f
• Windows: Open the Event Viewer or check the raw log files typically located in C:\ProgramData\StateWarden\logs\.

Common Log Signatures:

• failed to dial Artemis: connection refused -> The IP resolves, but a firewall is blocking port 443.
• handshake failure: bad certificate -> Your mTLS certificate is corrupted, revoked, or an SSL proxy is interfering.
• waiting for Artemis health check... -> The Agent has no network connection at all or DNS is failing.

4. Forced Re-Pairing

If an Agent's local cryptographic vault becomes corrupted (e.g., due to catastrophic disk failure), it will be permanently locked out of the Realm.

You cannot "recover" a lost Agent certificate. You must forcefully re-pair the device.

1. In the Dashboard, delete the old Device entry (this revokes its old certificate).
2. Generate a new Pairing Code.
3. On the host machine, completely uninstall the Agent (which wipes the local vault) and reinstall using the fresh code.

StateWarden: Resilience Engineered.