Remote Access: Terminal, Desktop & File Browser

Prerequisites

Remote access features require the SPOG agent to be installed, online, and connected via its persistent tunnel. Each access type has its own RBAC permission.

• SPOG agent installed and online on the target host
• Agent tunnel connected (persistent WebSocket between agent and backend)
• Role with hosts.use_terminal for terminal sessions
• Role with hosts.use_remote_desktop for desktop sessions
• Role with hosts.use_file_explorer for file browser
• Organization secret configured (required if using credential elevation)

Terminal sessions

Terminal sessions provide browser-based command-line access to managed hosts, similar to SSH. The connection flows from your browser through the SPOG backend to the agent, which opens a PTY (pseudo-terminal) on the host.

1. Navigate to the target host and click Terminal
2. Select the credential mode: use the agent's service account, enter manual credentials, or checkout a PAM vault credential
3. If using manual credentials, enter the username and password when prompted
4. If using PAM checkout, select the credential and complete the checkout flow (reason + duration)
5. The terminal opens in a new panel. You have a full interactive shell.
6. When finished, close the terminal tab or click Disconnect

Credential modes

Session timeouts

Terminal sessions enforce two timeout limits to prevent abandoned connections:

Remote desktop

Remote desktop provides graphical access to host desktops directly in the browser. The agent captures the screen and streams JPEG frames to your browser, while your mouse and keyboard input is relayed back to the host.

1. Navigate to the target host and click Remote Desktop
2. Select the session mode: Console (attach to the active console session) or RDP (create a new remote desktop session)
3. Optionally adjust the image quality (1-100, default 60). Lower values reduce bandwidth; higher values improve clarity.
4. Select the credential mode: agent user, manual credentials, or PAM checkout
5. The desktop view opens. You can interact with the remote desktop using your mouse and keyboard.
6. Close the session when finished by clicking Disconnect

Session modes

Desktop protocol

The desktop connection uses a binary WebSocket protocol for efficiency. Screen frames are sent as compressed JPEG images, and input events (mouse movement, clicks, keystrokes, clipboard) are sent as compact binary messages. This keeps bandwidth low even over slower connections.

File browser

The file browser lets you navigate the remote host's file system, view and edit files, and transfer files between your machine and the host. It uses the same agent tunnel as terminal and desktop sessions.

1. Navigate to the target host and click File Browser
2. Optionally select a starting directory path (defaults to root)
3. Select the credential mode: agent user or su (elevate to a specific user)
4. The file browser opens showing the directory listing
5. Navigate directories, view files, upload, download, or manage files

Supported operations

Credential elevation (su mode)

When using su mode, you provide a username and password for the target host. These credentials are encrypted with AES-256-GCM using the organization secret before transmission. The agent uses them to execute file operations as the specified user, then discards the credentials when the session ends.

Session recording

All terminal and desktop sessions are recorded automatically. Recordings capture the full session for audit review and incident investigation.

Terminal recordings

Terminal sessions are recorded in asciicast v2 format, an industry-standard format for terminal replay. The recording captures both user input and terminal output with precise timestamps, enabling exact replay of what happened during the session.

Desktop recordings

Desktop sessions are recorded as binary frame sequences in SPOG's proprietary .spogdr format. The recording captures screen frames, cursor updates, clipboard transfers, and all user input events.

Encryption at rest

Recordings are encrypted using envelope encryption. Each recording has its own data encryption key (DEK), which is wrapped with the system master key. This means recordings cannot be read by accessing disk storage alone.

Integrity verification

Each recording has a SHA-256 integrity hash and an RSA-SHA256 signature. This provides tamper detection: if a recording is modified after the session ends, the integrity check fails, alerting administrators to potential tampering.

Recording retention

Recording retention is managed at two levels: account-wide defaults and per-organization overrides. The minimum retention period is 7 days.

Retention hierarchy

1. If the organization has a retention period configured, that value is used
2. If not, the account-level default retention period is used
3. If neither is set, the system default applies (90 days)

Configuring retention

1. Navigate to Organization Settings
2. Open the Recording Retention section
3. Set the retention period in days (minimum 7)
4. Set to blank/null to inherit from the account-level default

Account-level defaults are configured under Account Settings → Recording Retention.

Legal hold

Recordings can be placed on legal hold to prevent deletion, regardless of retention policy. A legal hold requires a reason and is tracked with the user who placed it and the timestamp. Recordings under legal hold are preserved indefinitely until the hold is explicitly removed.

Soft delete

When a recording is deleted (manually or by the retention scheduler), it is soft-deleted rather than permanently removed. Soft-deleted recordings retain their metadata and can be identified in audit logs, but the recording content is no longer accessible.

Security controls

Authentication

All remote access connections require a valid JWT token. The token is verified server-side before the WebSocket connection is established. Blacklisted tokens (from logout or revocation) are rejected.

RBAC enforcement

Each access type requires its own permission. A user with terminal access does not automatically get desktop or file browser access. Permissions are checked at connection time.

Host-level access control

Beyond RBAC permissions, users must have access to the specific host. Account administrators can access all hosts in their account. Organization-scoped users can only access hosts within their organization. RBAC host scope policies are also enforced.

Credential security

When manual or elevated credentials are used, they are encrypted with AES-256-GCM using the organization secret before being sent through the tunnel to the agent. Credentials never travel in plaintext. For PAM checkout mode, the full PAM audit trail applies (checkout reason, duration, auto-checkin, optional rotation).

Audit trail

Every remote access session creates an audit record that includes:

• The user who initiated the session (IDP or legacy user)
• The target host
• Session type (terminal, desktop, or file browser)
• Source IP address of the connecting browser
• Session start and end timestamps
• Whether a PAM credential was used (and which one)
• Recording reference (for terminal and desktop sessions)

Session approval

For sensitive hosts, sessions can be configured to require approval before connection. The approval workflow tracks who approved the session and when. Sessions that require approval but have not been approved are blocked.

Connection flow

Permissions reference

Troubleshooting