Skip to content

Security Architecture & Threat Model

StackPilot protects mission-critical infrastructure across multiple Linux nodes. This document defines our security threat model, primary assets, and defensive mitigations.

1. Threat Model Diagram

flowchart LR
    subgraph Untrusted ["Public Internet / Untrusted Network"]
        Attacker["Potential Adversary\n(MitM, Injection, Traversal)"]
    end

    subgraph Edge ["Ingress / Reverse Proxy"]
        Proxy["Reverse Proxy (Traefik / Caddy / Nginx)\n+ Forward Auth (Authentik / Authelia)"]
    end

    subgraph ControlPlane ["StackPilot Hub"]
        Hub["Central Hub API (:8081)\n• Nonce CSP + Double-Submit CSRF\n• RBAC Policy Engine\n• Scoped Host Tokens"]
    end

    subgraph Host ["Managed Host"]
        Agent["StackPilot Agent (:9091)\n• TLS Listener (SHA-256 Pinned)\n• Canonical Path Jails"]
        Systemd["systemd --user\n• Rootless User Namespaces\n• No Root Daemon"]
    end

    Attacker -.->|"Blocked by CSP / CSRF"| Edge
    Edge -->|"Trusted IP + Remote Headers"| Hub
    Hub <==|"mTLS + X-Agent-Token"|==> Agent
    Agent <--> Systemd

2. Asset Classification & Defense Controls

Host Root Integrity

  • Risk: Container breakout leads to full root control of the host machine.
  • Defense: Rootless user namespaces (UID mapping). The container process running as UID 0 inside the container maps to an unprivileged host UID (e.g. 100000+). No root Docker daemon is required.

Host Filesystem Protection

  • Risk: Malicious path parameters (../../etc/shadow or ../../.ssh/id_rsa).
  • Defense: Canonical path resolution via os.path.realpath. Requests attempting to read or write files outside configured stack directories are terminated immediately with 403 Path Traversal Prohibited.

Web Dashboard & Session Security

  • Risk: Cross-Site Scripting (XSS), Cross-Site Request Forgery (CSRF), clickjacking.
  • Defense:
  • Dynamic Content Security Policy (CSP) with unique cryptographic nonces per request.
  • Double-submit signed CSRF cookies (csrf-csrf).
  • X-Frame-Options: DENY via Helmet.
  • Strict input sanitization and dynamic DOM updates via .textContent.

Host Communications & Agent Impersonation

  • Risk: Rogue agents registering with the Hub or Man-in-the-Middle eavesdropping.
  • Defense: Pinned TLS CA certificates, SHA-256 TLS cert fingerprint registration during onboarding, and rotating X-Agent-Token bearer credentials with 0600 permissions.