VN-02 · Browser SSH Session

Status: Delivered (control plane, byte relay, and live terminal). Multi-pod gateway scale-out and server-derived recording storage are later work. Roles needed: Operator (or tenant admin); plus an auditor for the read-only check

What the client asked for

"Remote SSH management should be scoped through contracts before implementation: browser SSH via WebSocket/TLS, session recording, command logging, JIT access, tenant RBAC, and timeouts."

What this proves

An authorized operator can open a real SSH terminal to an enrolled machine from the browser — with no inbound ports on the tenant network — and every session is time-boxed, recorded by reference, command-logged, and audited. Auditors and other tenants cannot drive it.

How it works (at a glance)

The session only becomes active after the agent confirms the tunnel is open. Until then the terminal stays read-only.

How the shell is authorized (no passwords): the agent stays a dumb TCP relay to the endpoint's sshd. The gateway terminates SSH server-side and, per session, mints a throwaway key pair; the agent installs the public key into its own user's authorized_keys for the life of the session and removes it on close (the AWS EC2 Instance Connect model). The operator never types an SSH password or key — they are already authenticated to the portal and authorized by the session grant. You log into the endpoint as the OS user the agent runs as.

Where to look in the portal

• Assets then select an SSH-capable asset
• The browser SSH panel on the asset detail
• Audit

Validation walkthrough

Exact labels match the portal. Run the rebuilt endpoint agent on a machine that also runs sshd (the agent connects to 127.0.0.1:22).

#	Action	What you should see
1	Sign in to the OneProtect portal as a user with the operator role (or tenant admin).	The console loads with the left navigation (Assets, Alerts, …).
2	Open Assets and find the enrolled host running the agent.	The host row shows a recent Last seen (updates every ~30s) and is SSH-capable.
3	Open the host detail and find the Live terminal panel. Click Open terminal.	The panel prints OneProtect browser SSH and Waiting for the endpoint agent to accept the tunnel...; the state chip shows connecting then pending; typing does nothing yet.
4	Wait ~1–2 seconds for the agent to accept the tunnel.	The terminal prints [session_active], the sub-title reads Terminal connected., and the cursor becomes active.
5	Type whoami and press Enter.	The shell returns the OS user the agent runs as (real output from the endpoint, not placeholder text).
6	Type uname -a then ls / (Enter after each).	Real command output renders; resizing the browser reflows the terminal correctly.
7	Type exit (or close the panel).	The terminal prints [session_closed: …] and the session moves to ended.
8	Open Audit.	There are entries for this session id: SSH session started and ended.
9	Sign out, sign in as an auditor, open the same host.	The session record is visible read-only; there is no Open terminal button.

Pass / fail checklist

• Operator opens a live browser terminal to the enrolled host and reaches [session_active]
• Terminal input is disabled until the session is active
• Real shell output renders — whoami returns the agent's OS user (no fabricated output)
• No SSH password or key is entered in the browser (per-session ephemeral key, provisioned by the agent)
• Session ends on exit/close and on idle/absolute timeout
• Session record carries a recording reference; Audit shows session start and end
• An auditor sees the record read-only with no Open terminal control
• An operator from a different tenant cannot open this session

Intentionally not in Phase 1

• Multi-pod gateway routing (the Phase 1 gateway runs in-process on the API service; it proves the end-to-end protocol).
• Server-side parsing of the byte stream into a verbatim transcript, and long-term recording storage in object storage. Phase 1 logs commands and references the recording; the bytes are relayed live.
• Remote desktop, file transfer.

Evidence to capture

• Screenshot of the live terminal showing a real command and its output.
• Screenshot of the session detail (duration, command log, recording hash).
• Screenshot of the SSH audit entries.