Security

potaru's core feature — arbitrary reverse-shell access to enrolled machines — is high-privilege by design. This page documents the model.

Enrollment tokens vs. agent secrets

Two distinct credentials exist, deliberately:

• Enrollment tokens are multi-use (or single-use), admin-issued, optionally expiring bootstrap credentials — what you paste into potaru init on a new machine. They're revocable independently of any agent that has already enrolled with one.
• Agent secrets are minted once, automatically, the first time an enrollment token is redeemed. They're permanent (until the agent is deleted) and unique per machine.

Revoking an enrollment token never disconnects an already-enrolled agent; deleting an agent invalidates only that agent's own secret.

Audit log

Every shell session (open and close) and every mutating admin action (enrolling/revoking tokens, deleting agents, creating the admin account) is recorded with actor, target, source IP, and timestamp — GET /api/audit-log or the "Audit log" page (admin-only).

Shell-open events are recorded before the stream is actually opened, so even an attempt that immediately fails (agent offline, refused) is accounted for.

Session transcript recording (logging the actual bytes typed/displayed in a session) is not implemented. If it's added later, it will capture everything — including passwords typed at a remote sudo prompt — which is a real retention/privacy tradeoff to document explicitly, not a default to ship silently.

Least privilege on the agent

The agent never requires or defaults to root. A shell you get through it is only ever as privileged as the OS user (or container user) the agent process itself runs as. If you want root access to a machine, that's an explicit choice — run the agent as root yourself; the product never elevates on your behalf.

The Docker client image reflects this: it runs as a dedicated unprivileged user (uid 65532), not root.

Confirmation gating

Destructive admin actions — revoking an enrollment token, deleting an agent — require an explicit {"confirm": true} in the request body. A bare DELETE is rejected.

Rate limiting

Login attempts, agent tunnel authentication, and enrollment-token redemption are all rate-limited per source IP with a temporary lockout after repeated failures.

TLS

TLS is currently self-signed only on both listeners (the agent tunnel and the admin web UI) — real ACME-issued certificates are a planned addition. --self-signed/--insecure are explicit opt-ins, never silent defaults, in anticipation of that change.

Secrets at rest

Enrollment tokens, agent secrets, and session cookies are stored only as SHA-256 hashes — the raw value is shown to the operator exactly once, at creation.