Warden Documentation

Features #

Prerequisites #

Warden ships as Docker containers — everything it needs to run is inside the image and the Compose stack. On the host you only need Docker.

Everything else is provided for you: the PostgreSQL database runs as a Compose service, and ssh/sshpass plus the AWS CLI v2 + session-manager-plugin (for ECS connections) are bundled inside the Warden image — nothing to install on the host.

Quick Start (Docker) #

Docker Compose starts the app (with the AWS CLI + session-manager-plugin bundled) and a PostgreSQL instance together.

cp .env.example .env        # set ENCRYPTION_KEY, POSTGRES_PASSWORD, and review the rest
docker compose up -d        # starts the provided Warden image + PostgreSQL
open http://localhost:8080

The image runs as non-root user warden (UID 1000) with a read-only root filesystem; /tmp and /home/warden are tmpfs, and /data (recordings + known_hosts) is a persistent volume.

First-Run Setup #

On first launch — when no users exist — Warden's bootstrapCheck() prints a one-time setup link to stdout (valid 24 hours):

WARDEN setup link (expires in 24 h): http://localhost:8080/...

Open that link to create the initial admin account with a passkey. Every subsequent user is invited from Admin → Users (an invite or reset link is emailed via SMTP, or printed to stdout if SMTP is not configured).

How It Works #

Browser (xterm.js)
  │  WS binary frames  — raw terminal I/O
  │  WS text frames    — JSON connect / resize / session_id / exit
  ▼
Go HTTP server  (net/http + gorilla/websocket)
  │  ── SSH path ──  pty.Start(ssh / sshpass)
  │  ── ECS path ──  pty.Start(aws ecs execute-command --interactive)
  │  one long-lived liveSession owns the PTY:
  │     output → recorder (if enabled) + hub fan-out (owner + share subscribers) + scrollback
  ▼
Remote SSH server  or  AWS ECS task (via SSM session-manager-plugin)

1. Browser authenticates via passkey; the server issues an http_sessions cookie.
2. User opens a WebSocket to /ws and sends {"type":"connect", "connType":"ssh"|"ecs", ...} (or resumeSessionId to reattach).
3. Saved configs are resolved and the target is checked against the access-approval gate; inputs that become process args are validated.
4. The PTY is owned by a liveSession that outlives the WebSocket. Detaching (logout / tab close) leaves it running; the owner reattaches later and the buffered scrollback is replayed.
5. PTY output is fanned out to the owner and any share subscribers, and (when the environment opts in) appended to the recorder.
6. On a clean remote exit the server sends {"type":"exit"} and the tab auto-closes; the recording is finalized to an encrypted file on disk.
7. Sessions with no browser attached are reclaimed after SESSION_IDLE_TIMEOUT; a session is also killed if its access grant expires.

The liveSession Model #

The load-bearing invariant: a liveSession owns the PTY — not the WebSocket. Registered in a sync.Map by sessionID, it owns the ptmx, the recorder, and a sessionHub, and it outlives any WebSocket.

• Start: newLiveSession launches run() (PTY → recorder + hub fan-out) and a cmd.Wait() reaper.
• Attach / detach: WebSockets attach via serveOwner or handleShareWS. On WS close they detach — they never finalize or kill the session.
• End: the session ends only when the PTY closes — process exit or kill() (ptmx.Close(), called by the End endpoint, the idle sweeper, or when a grant expires). Then finish() runs once: reads the exit code, notifies a clean exit ({"type":"exit"} → tab auto-closes), closes the hub, deletes from the registry, finalizes the recording, removes the temp SSH key.
• Reclaim: detached sessions with no clients are reclaimed after SESSION_IDLE_TIMEOUT; the sweeper also kills a session whose access grant has expired.

The session hub appends to a bounded scrollback (256 KiB) and fans output out to all clients; on attach it replays the scrollback to restore the screen. An owner-approved view→control upgrade takes effect live, with no reconnect.

Roles #

admin_only passes the admin guard but is blocked from /ws; the terminal page redirects it to /admin. Disabling a user immediately drops their browser sessions and kills their live terminals.

SSH Terminals #

Connect to any reachable SSH server. Warden launches a real ssh subprocess (wrapped by sshpass for password auth) attached to a PTY.

• In the UI, choose the SSH tab and enter host, username, port, and credentials — or pick a saved connection.
• Host, username, port, and any value that becomes a process argument are validated and rejected if they could be parsed as options (e.g. -oProxyCommand=…).
• SSH host keys are verified via accept-new (trust-on-first-use) against a persistent known_hosts by default; set SSH_HOST_KEY_CHECKING=yes for strict verification against a pre-seeded file.

AWS ECS Terminals #

Exec into a Fargate container with aws ecs execute-command --interactive over the SSM session-manager-plugin.

1. Enable ECS Exec on your task definition / service (enableExecuteCommand: true).
2. Add an AWS account in Admin → AWS Accounts (access key ID + secret key, stored AES-256-GCM encrypted; optional default region/cluster/role ARN). Users then pick the account by name in the ECS connect form — no AWS credentials on the Warden host required. Selecting "host credentials" falls back to the host's ambient AWS config/instance role.
3. The Docker image bundles the AWS CLI + session-manager-plugin — nothing to install on the host.

In the UI: switch to the AWS ECS tab, pick an AWS account, enter cluster + task ID (or ▾ List to browse running tasks), then connect.

Required IAM permissions

Credentials are shared by all Warden users, so apply least privilege — scope Resource to the specific cluster/task ARNs you expose rather than "*", and prefer a separate, narrowly scoped role per environment.

{
  "Effect": "Allow",
  "Action": [
    "ecs:ExecuteCommand", "ecs:ListTasks", "ecs:DescribeTasks",
    "ssm:StartSession", "ssm:TerminateSession", "ssm:DescribeSessions"
  ],
  "Resource": [
    "arn:aws:ecs:REGION:ACCOUNT:cluster/YOUR_CLUSTER",
    "arn:aws:ecs:REGION:ACCOUNT:task/YOUR_CLUSTER/*"
  ]
}

AWS Accounts #

Admin-managed AWS credentials, encrypted at rest and shared across users — so engineers never handle raw AWS keys.

• Created in Admin → AWS Accounts: a name, access key ID, secret key (AES-256-GCM encrypted), and optional default region / cluster / role ARN.
• Users select an account by name in the ECS connect form; the secret never leaves the server and is passed only to the aws subprocess via a minimal environment.
• The non-admin list endpoint returns only names/metadata — never secret material.

Saved Connections #

SSH and ECS connection profiles are stored server-side per user so common targets are one click away.

• SSH configs (/api/configs): host, user, port, and credentials — secrets AES-256-GCM encrypted at rest.
• ECS configs (/api/ecs-configs): cluster + task references, pointing at a stored AWS account (account_id) rather than embedding credentials.

When you connect with a saved config, Warden resolves it server-side, then runs the same approval gate and argument validation as a manual connection.

Access Approvals #

Gate sensitive environments behind time-boxed, approver-granted access with a full audit trail.

Admins define environments and attach connection resources to them — an AWS account or ECS cluster (for ECS) and/or an SSH host glob. An environment marked restricted (requires_approval) needs an active, time-boxed grant to connect; each environment has a list of approvers.

• Users request access from the terminal page (My Access): environment + duration-or-until + justification. Approvers see the request (a ~5 s polling banner, or the admin Access Grants table) and approve / deny; admins can also grant directly.
• The gate runs at connect time and is re-checked on reattach; a running session is killed when its grant expires.
• ECS gating keys on both the AWS account and the cluster, so "host credentials" can't be used to dodge an account-scoped gate. SSH matches the host glob via path.Match.
• Every request and decision is auditable in Admin → Access Grants.

Environment fields

Grants are a state machine: pending → approved/denied/cancelled, approved → revoked; expired is derived. An active grant is approved and not expired. Approve / deny / revoke self-authorize (approver-for-env or admin).

Resumable Sessions #

A session keeps running server-side when you log out or close the tab. Reattach later with the screen restored.

• Because the liveSession owns the PTY, closing the browser only detaches — the remote process keeps running.
• Reconnect by sending resumeSessionId on the /ws connect frame (the UI's Running Sessions list does this for you). Ownership and access are re-verified, then the buffered scrollback is replayed to restore the screen.
• Detached sessions are reclaimed after SESSION_IDLE_TIMEOUT (default 2h); each user is capped at SESSION_MAX_PER_USER concurrent live sessions (default 20), with a global cap of MAX_LIVE_SESSIONS (default 500).

Live Session Sharing #

Share a running terminal with another user — view-only or with control — for pairing, debugging, or supervision.

• The owner invites a user to a running session; the invitee accepts and attaches as a subscriber to the session hub via /ws/share/{id}, receiving the replayed scrollback.
• A viewer can request control; the owner approves and the viewer is upgraded to control live — the share mode is re-checked per message, so no reconnect is needed.
• Revoking a share, or disabling the user, immediately disconnects active subscribers.

Sharing is managed through the /api/share/* endpoints (create, accept/decline, request/grant/deny control, revoke) — see the API Reference.

Session Recording #

Opt-in per environment. Captured as asciicast v2, gzipped and AES-256-GCM encrypted on disk, played back and downloaded by admins with speed control and scrubbing.

• Recording is off by default. A session is recorded only when its target's environment has record_sessions=true — independent of whether the environment requires approval.
• On finalize, output is gzipped → AES-GCM encrypted → written to {RECORDINGS_DIR}/{id}.cast.gz (magic header WER1), with recording_path + recording_size stored in the DB. On a file-write failure it falls back to an encrypted DB column.
• Admins browse and play recordings in Admin → Session recordings (and via /api/admin/sessions/{id}/recording). Playback handles legacy plaintext columns and legacy unencrypted gzip transparently.

Tabs, Tile & Broadcast #

Work many connections at once.

• Tabs — keep multiple SSH/ECS connections open and switch between them.
• Tile layout — view several terminals side-by-side.
• Broadcast — optionally mirror your keystrokes to every open terminal at once, for fan-out operations across a fleet.

Running and saved sessions are listed in the left rail; a running session shows a reattach (↻) indicator.

Authentication #

Warden is passkey-only (WebAuthn) — there are no passwords to phish, reuse, or leak.

• Registration is invite-driven: an admin sends a magic link (one-time token, 24 h) which the user opens to register a passkey. The very first admin is created from the first-run setup link.
• Login uses the registered passkey; the WebAuthn sign counter is persisted on each login.
• Browser sessions are http_sessions cookies — 7-day rolling with an absolute 30-day cap. https:// auto-enables Secure cookies + HSTS.
• Auth endpoints are protected by a per-IP rate limiter; magic tokens are one-time; disabling a user drops their sessions and kills live terminals.

Security Model #

Built-in protections across the request, subprocess, and storage boundaries.

• Input validation (the RCE boundary) — host/username/port and ECS fields that become process arguments are rejected if they could be parsed as options (e.g. ssh -oProxyCommand=…). Any user value reaching exec goes through validate.go.
• SSH host keys — verified via accept-new (TOFU) against a persistent known_hosts by default; SSH_HOST_KEY_CHECKING=yes for strict.
• WebSocket — origin checked against APP_URL; per-connection read limit; keepalive with read deadlines.
• Secrets at rest — SSH/AWS credentials and recordings are AES-256-GCM encrypted. Subprocesses receive a minimal environment — the AES key / DB URL / SMTP password are never passed to ssh / aws.
• Headers — CSP, X-Frame-Options: DENY, nosniff, Referrer-Policy: no-referrer; HSTS when SECURE_COOKIES.
• Auth — passkey-only; per-IP rate limiting; one-time magic tokens; absolute session lifetime; disabling a user drops sessions and kills live terminals.

Hardening Checklist #

Before exposing Warden to the internet:

• Put TLS in front (the bundled Caddy service, or Nginx) — see Deployment & HTTPS.
• Set APP_URL to your https:// domain and RP_ID to its host.
• Set SECURE_COOKIES=true and TRUST_PROXY=true (only when actually behind a trusted proxy that sets X-Forwarded-For / X-Real-IP).
• Keep BIND_ADDR=127.0.0.1 unless you front it with TLS; never publish the app port directly without TLS.
• Generate a strong ENCRYPTION_KEY and back it up — losing it makes all encrypted secrets and recordings unreadable.
• Use sslmode=require (or verify-full) for any non-loopback DATABASE_URL.
• Prefer strict SSH host keys (SSH_HOST_KEY_CHECKING=yes with a seeded known_hosts) for sensitive fleets.
• Scope AWS IAM to specific cluster/task ARNs; use a narrowly scoped role per environment.

Configuration #

All settings are environment variables. Copy .env.example to .env to get started; Docker Compose reads .env automatically.

Server & networking

Database

Encryption & cookies

Sessions & limits

SSH & ECS

Recordings

SMTP (optional — magic links print to stdout if unset)

Deployment & HTTPS #

The recommended deployment is Docker Compose with a TLS reverse proxy in front.

Compose services

The bundled docker-compose.yml runs the warden app (read-only root FS, all caps dropped, tmpfs /tmp + /home/warden, persistent /data volume) and a pinned postgres:16-alpine with healthchecks. The app port binds to ${BIND_ADDR:-127.0.0.1} so it isn't reachable off-host without a proxy.

HTTPS with the bundled Caddy

Uncomment the caddy service in docker-compose.yml and edit the Caddyfile with your domain — Caddy obtains and renews a Let's Encrypt certificate automatically. Requirements: a public domain pointing at the host, ports 80 + 443 open.

ssh.yourdomain.com {
    reverse_proxy warden:8080 {
        # Forward the real client IP (replace, don't append, so a client-supplied
        # X-Forwarded-For cannot survive into the chain and spoof the rate-limiter).
        header_up X-Real-IP {remote_host}
        header_up X-Forwarded-For {remote_host}
        flush_interval -1          # snappier WebSocket streaming
    }
    header {
        Strict-Transport-Security "max-age=31536000; includeSubDomains"
        X-Content-Type-Options    nosniff
        X-Frame-Options           SAMEORIGIN
        Referrer-Policy           strict-origin-when-cross-origin
    }
}

Then set APP_URL=https://ssh.yourdomain.com, RP_ID=ssh.yourdomain.com, SECURE_COOKIES=true, and TRUST_PROXY=true.

Database Schema #

Schema is applied at startup via CREATE TABLE IF NOT EXISTS + ALTER TABLE … ADD COLUMN IF NOT EXISTS — there is no separate migration tool. All of it lives in db.go:schema().

HTTP API Reference #

All /api/* routes require an authenticated session cookie; /api/admin/* requires an admin (or admin_only) role. State-changing requests are CSRF-guarded. WebSocket endpoints are origin-checked and connection-rate-limited.

WebSockets & pages

Auth & user

Connections — SSH / ECS / AWS

Sharing

Environments & access grants

Sessions & admin