Security
Security is not a standalone feature in Soul Stack — it is the primary criterion behind every architectural choice. Wherever convenience and security trade off against each other, security wins by default, and any relaxation takes the form of an explicit, auditable operator opt-out rather than silent behavior.
This section describes the security model: what node identity rests on, how the transport between nodes is protected, and how the system handles secrets.
What you get out of the box
Section titled “What you get out of the box”| Control | What it gives you | More |
|---|---|---|
| mTLS transport | All Keeper ↔ agent traffic runs over mutually authenticated TLS. Both sides present certificates; neither trusts an anonymous peer. | Transport |
| CSR-based identity | The agent’s private key is generated on the host itself and never leaves it. Only the certificate fingerprint is registered on the Keeper — no PEM and no private keys in the database. | Identity |
| Built-in RBAC | Every Operator API call is checked against the operator’s (Archon’s) permissions. The default policy is deny: anything not explicitly allowed is forbidden. | Operator management |
| Audit log | Every operator action is recorded in the audit log with its initiator (AID) and outcome. | Operator management |
| Vault integration | Vault PKI issues agent certificates; Vault KV stores the secrets injected into configs during rendering. Secrets never materialize on the cluster’s disk. | Secrets |
| Secret masking | Values marked as secret are masked on every output — in logs, OTel traces, the UI, API responses, and run reports. | Secrets |
| Thin agent | Destiny rendering (CEL + templates, reading Vault) happens on the Keeper. The agent carries no Vault client and no secret-resolution logic — the attack surface on the managed host is minimal. | Secrets |
The thin-agent principle
Section titled “The thin-agent principle”A key consequence of the model: the managed host runs minimal code with minimal privileges.
- Rendering happens on the Keeper. Templating and resolving secrets from Vault happen on the Keeper side; the agent receives a ready-made set of tasks. The agent needs neither a Vault client nor access to Vault tokens.
- No inbound traffic. The agent itself initiates the stream to the Keeper. Managed hosts need no open inbound ports — the only thing exposed is the local metrics listener (on loopback by default).
- Minimal secrets on the host. The only sensitive material on the host is the private key of the agent’s own identity — and even that was generated locally and has never left the machine.
Pages in this section
Section titled “Pages in this section”- Identity — how nodes and operators prove who they are: SID, SoulSeed, CSR onboarding, bootstrap tokens, Archons, and AID.
- Transport — the gRPC stream over mTLS, which side initiates the connection, and the shared PKI root.
- Secrets — Vault integration, Keeper-side resolution, output masking, and the
no_logkey.
RBAC details live in Operator management: bootstrapping the first Archon — Archons; the permissions catalog and roles — Roles; operator groups (Synod) and scoped visibility (Purview) — Synod and Purview.