Skip to main content

SECURITY

The remote execution security model centralizes trust in the orchestrator. Workers are stateless compute nodes that execute dispatched steps and return results. They hold no credentials, no persistent secrets, and no definitions beyond what the current dispatch requires.

Trust model

Workers authenticate to the orchestrator using a bearer credential pair: {token, machineId}, transmitted over a wss:// (WebSocket Secure) control socket.

  • The token is an enrollment token created with swamp worker token create. It is single-use: once bound to a machine identity, no other machine can present it.
  • The machine-id is a client-asserted identifier stored in the worker's --cache-dir directory. It prevents accidental reuse from different machines but does not defend against a malicious token holder. A compromised token grants the holder the same enrollment access regardless of machine identity.

For production deployments:

  • Keep enrollment token durations short (hours, not weeks) to limit the exposure window of a compromised token.
  • Terminate TLS at the orchestrator or a reverse proxy in front of it. The control socket and data plane both carry step inputs, outputs, and resolved secrets in transit.
  • Consider certificate pinning on the worker side to prevent man-in-the-middle interception of the wss:// connection.

See Enrollment Tokens for machine binding semantics and the full token state machine.

What a worker can see

Workers receive a per-dispatch environment snapshot containing only the inputs and resolved values needed for the current step. This snapshot is held in memory for the duration of the dispatch and discarded when the step completes.

  • The orchestrator resolves all vault secrets and datastore queries on its own side, then transmits the resolved values to the worker over the encrypted connection.
  • No datastore connection strings or vault credentials are sent to the worker. The worker cannot connect to datastores or vaults directly.
  • The worker executes the step and returns results through the data plane. It never initiates access to the orchestrator's persistence layer.
  • After the dispatch completes (success, failure, or cancellation), the environment snapshot is discarded from worker memory. No secrets persist between dispatches.

What a worker cannot see

The following are never transmitted to a worker:

Resource Reason
Vault credentials Secret resolution happens orchestrator-side; only resolved values for the current step are sent
Datastore connection strings Workers access data only through the orchestrator's capability proxy
Other workers' dispatches Each dispatch is isolated; workers have no visibility into the pool
The full definition set Only the definitions required for the current dispatch are bundled
Datastore contents beyond scope The orchestrator scopes data access to what the current step declares

The capability proxying architecture explains how the orchestrator mediates all resource access on behalf of workers.

Reverse trust direction

Warning

Connecting a worker to an untrusted orchestrator URL grants that URL code execution on the worker machine. The orchestrator dispatches steps that the worker executes locally — a malicious orchestrator can send arbitrary work.

This is the same trust model as a self-hosted CI runner (GitHub Actions, GitLab Runner): the runner trusts the server to send legitimate work. The security boundary points inward, not outward.

  • Only connect workers to orchestrators you control.
  • Verify the orchestrator URL before running swamp worker connect.
  • Treat the orchestrator URL with the same care as a CI server URL.

Security recommendations

Recommendation Detail
Use wss:// for the control socket The control socket carries authentication tokens and step data. Never use unencrypted ws:// in production.
Keep enrollment token durations short Hours, not weeks. Shorter lifetimes reduce the window in which a leaked token can be used.
Set --cache-dir with restricted permissions The cache directory contains the machine-id file. Restrict filesystem permissions to the worker process owner.
Run workers with minimum OS privileges Use a dedicated service account with only the permissions the workload requires. Avoid running workers as root.
Audit tokens and workers regularly Run swamp worker token list and swamp worker list periodically. Identify tokens that are enrolled but no longer expected, or workers that have not connected recently.
Revoke tokens on decommission When a worker is retired, immediately revoke its token with swamp worker token revoke. Do not wait for expiry.
← PreviousFailure SemanticsNext →API Key Authentication