Screen Recording and Auditing
Relevant source files
The following files were used as context for generating this wiki page:
The Screen Recording and Auditing system in sshpiper provides robust mechanisms for capturing, storing, and live-viewing SSH session activity. It serves as a security and compliance layer by allowing administrators to log terminal output in standardized formats or monitor live sessions through a web-based dashboard.
The system supports two primary offline recording formats: asciicast (v2) and typescript. Additionally, it includes an administrative gRPC API and a corresponding web interface (sshpiperd-webadmin) for real-time session auditing, live-streaming of terminal output, and session termination. Sources: README.md:144-145, cmd/sshpiperd/main.go:193-205, cmd/sshpiperd-webadmin/main.go:14-16
Recording Formats and Storage
sshpiperd can be configured to record session data to a specified directory using either the asciicast or typescript format. These recordings are stored on the filesystem and can be organized by username.
Available Formats
| Format | Description | Replay Tool |
|---|---|---|
asciicast | JSON-based format (v2) compatible with asciinema. Stores terminal output and timing data. | asciinema play |
typescript | Legacy format compatible with the standard Linux scriptreplay tool. Generates .timing and .typescript files. | scriptreplay |
Sources: README.md:144-177, cmd/sshpiperd/main.go:193-205
Configuration Flags
Recording behavior is controlled via several command-line flags or environment variables:
--screen-recording-dir: The root directory where session logs are saved.--screen-recording-format: Specifies eitherasciicastortypescript.--username-as-recorddir: If enabled, creates subdirectories named after the downstream username to organize recordings.
Sources: cmd/sshpiperd/main.go:193-205
Administrative Auditing (Admin UI)
The project provides an optional administrative interface for live auditing. This is composed of a gRPC API on sshpiperd and an aggregator service called sshpiperd-webadmin.
System Architecture
The diagram shows how multiple sshpiperd instances expose gRPC admin endpoints to the webadmin aggregator, which then serves a web UI to the browser. Sources: README.md:112-127, cmd/sshpiperd-webadmin/main.go:14-23
Live Session Streaming
Live sessions can be audited in real-time through the browser using Server-Sent Events (SSE). The web interface utilizes xterm.js to render terminal output and supports browser-side recording of the live stream into an asciicast file.
The sequence illustrates the flow of terminal data from the daemon through the aggregator to the web browser. Sources: cmd/sshpiperd-webadmin/internal/httpapi/web/src/app.js:415-470, libadmin/admin.pb.go:732-740
Admin Data Structures
The system uses specific Protobuf messages for auditing tasks:
- Session: Contains metadata such as
id,downstream_user,upstream_addr, and astreamableflag indicating if output capture is active. - SessionFrame: A container for either an
AsciicastHeaderor anAsciicastEvent. - AsciicastEvent: Captures terminal data with a timestamp, event type (
ofor output,rfor resize), and raw data bytes.
Sources: libadmin/admin.pb.go:153-204, libadmin/admin.pb.go:343-435
Session Auditing Capabilities
The web administration console provides several active auditing features:
- Session Listing: Aggregated view of all live sessions across multiple
sshpiperdinstances. Sources: cmd/sshpiperd-webadmin/internal/httpapi/web/index.html:150-165 - Live Viewing: Real-time terminal output visualization for sessions where a shell or exec channel is active. Sources: cmd/sshpiperd-webadmin/internal/httpapi/web/src/app.js:345-360
- Browser Recording: Users can start a browser-side capture of a live-viewed session, which is then downloaded as an
asciicast v2file. Sources: cmd/sshpiperd-webadmin/internal/httpapi/web/src/app.js:255-320 - Session Termination: Administrative "kill" command to force-close active connections via the gRPC
KillSessionRPC. Sources: libadmin/admin.pb.go:728-732, cmd/sshpiperd-webadmin/internal/httpapi/web/src/app.js:235-250
Security of Auditing Data
The admin gRPC API is protected by several security layers:
- Mutual TLS (mTLS):
sshpiperdcan be configured to require client certificates from administrators, verified against a specific CA. Sources: cmd/sshpiperd/main.go:34-56, README.md:104-106 - Insecure Mode: An
--admin-grpc-insecureflag exists for trusted local networks, though its use is discouraged for production. Sources: cmd/sshpiperd/main.go:310-315 - Read-Only Mode:
sshpiperd-webadmincan be started with--allow-kill=falseto provide an audit-only view without management capabilities. Sources: cmd/sshpiperd-webadmin/main.go:87-91
Summary
The Screen Recording and Auditing system provides comprehensive oversight of SSH traffic. By combining persistent filesystem logging (asciicast/typescript) with real-time gRPC-based streaming and session management, the project enables both forensic post-mortem analysis and active live monitoring of proxied sessions.