Skip to content

TLS Certificate Pinning & Token Authentication

StackPilot secures all communication between the Central Hub and remote Host Agents using cryptographic certificate pinning and rotating bearer tokens.

1. Dual-Phase Host Enrollment Flow

sequenceDiagram
    autonumber
    actor Admin as Administrator
    participant Hub as Central Hub
    participant Node as Managed Linux Host

    Admin->>Hub: Click "Add Host"
    Hub->>Hub: Generate Short-Lived Enrollment Token
    Hub-->>Admin: Display 1-line curl enrollment command
    Admin->>Node: Execute curl command
    Node->>Hub: GET /api/agents/install.sh (Bearer Enrollment Token)
    Note over Node,Hub: Hub verifies enrollment token and returns installer script
    Node->>Node: Generate RSA 2048-bit Key & Self-Signed TLS Cert
    Node->>Hub: POST /api/agents/fingerprint (Sends Cert PEM)
    Hub->>Hub: Calculate & Pin SHA-256 Fingerprint
    Hub->>Hub: Generate Dedicated Node Runtime Token
    Hub-->>Node: Return Runtime Token
    Node->>Node: Save Token to ~/.stackpilot_agent_token (0600)
    Node->>Node: Start Agent Service with TLS Listener (:9091)
    Hub->>Node: GET /api/status (Header: X-Agent-Token)
    Node-->>Hub: Return Node Metrics & Container List

2. Pinned CA Verification

When the Central Hub operates over HTTPS: 1. The Hub's public TLS certificate is embedded directly into the installer script dynamically. 2. All download operations (curl) and Python API calls (urllib.request) enforce --cacert verification against the embedded CA certificate. 3. This prevents active adversary MitM attacks on local networks during initial node onboarding.

3. Token Storage & Permissions

  • Agent Host: The runtime bearer token is written exclusively to ~/.stackpilot_agent_token with strict permissions: 
    chmod 600 ~/.stackpilot_agent_token
  • Central Hub: Stored in ~/.config/stackpilot/agent-tokens.json (also permissions 0600).
  • Rotation: Tokens can be rotated at any time from the Hub's host settings without restarting host containers.