Security overview
What shellz protects, who can read recordings in each mode, and the limits of the design.
Session recordings contain the most sensitive thing on a server: what people and agents typed and saw. shellz is designed so that a recording is encrypted before it leaves the server, can't be changed without detection once it's written, and can only be read by your team.
Summary
- Encrypted on the server. Each session is encrypted with its own AES-256-GCM key before it's written to disk or sent anywhere. See Encryption.
- Signed and chained. Each server signs every piece of every recording with its own Ed25519 key, and links each piece to the previous one by hash. Missing or altered pieces are detected and shown.
- Write-once storage. Stored recordings can't be overwritten or deleted for 365 days, by anyone, including shellz.
- Decrypted only in your browser, after a recent sign-in, with every view written to the audit log.
- Perfect Secrecy (optional): the org key lives only in your team's browsers, unlocked by their passkeys. shellz can't decrypt your recordings. See Perfect Secrecy.
- Hard to turn off quietly. Changes to the recorder are reverted and reported, removal needs approval in the dashboard, and silent servers raise alerts. See Tamper resistance.
Who can read recordings
| Standard mode | Perfect Secrecy | |
|---|---|---|
| Your team, after signing in | Yes | Yes, with a passkey that holds the org key |
| Someone with a copy of shellz's database or storage | No | No |
| shellz, as the operator of the service | Technically able to, by using the org key it holds | No. It never has the org key. |
| An attacker who takes over the shellz service | Could release session keys | Gets ciphertext and metadata only |
| The servers that produce recordings | No. A server can encrypt, but can't decrypt even its own past recordings. | No |
In standard mode, the org's private key is stored by shellz, sealed with a separate encryption key, and shellz uses it to release a session's key to a signed-in teammate. That makes setup instant and recovery easy, but it means you trust shellz to protect the key and only release it to your team.
In Perfect Secrecy mode, the private key is generated in an owner's browser and only ever stored encrypted to your teammates' passkeys and to a recovery kit you keep. shellz stores ciphertext and public keys.
What shellz can see
In both modes, shellz can read session metadata, because it's needed to list, search and alert on sessions:
- server, fleet and container names, container images;
- the account name and UID, the source IP address of SSH sessions, and the terminal device;
- start and end time, size, exit status and integrity;
- in standard mode only, the command line of non-interactive sessions (
ssh host cmd,docker exec ... cmd). In Perfect Secrecy mode it's encrypted with the session.
shellz can't see what was typed or shown in a session, in either mode, without using a decryption key.
Threat model
shellz is built to keep recordings trustworthy against:
| Threat | Protection |
|---|---|
| A user on the server wants to avoid being recorded | Login shells point at the recorder; sessions that bypass it are ended or alerted on; changes to shellz's files and settings are reverted within 15 seconds and reported |
| A user with root stops or removes the recorder | The service refuses manual stops and restarts if killed; removal needs a signed approval from your org; missing heartbeats alert within 90 seconds |
| Someone edits or deletes a recording after the fact | Signed, hash-chained segments; write-once storage with a 365-day lock; gaps and tampering are shown on the session |
| Someone reads recordings from storage or a database backup | Everything is encrypted with per-session keys; storage holds no usable keys |
| A stolen join or fleet token | Join tokens are single-use and expire after 10 minutes. Fleet tokens can be rotated and revoked. Neither can read recordings. |
| A forged server sends fake recordings | Every segment is signed by an enrolled server's key and checked on arrival |
| shellz itself, or an attacker inside it (Perfect Secrecy) | The org key never reaches shellz; servers pin your org key and only accept signed rotations; policies must be signed in your browser |
Limits
These are outside what shellz can protect against:
- Root on a server sees that server's sessions as they happen. Root can read process memory and terminals directly. shellz makes interfering with recording visible, not impossible.
- A compromised server can lie about future sessions. If an attacker takes over a server, recordings from that point on depend on that server. Earlier recordings stay intact and signed.
- The dashboard's code is trusted. In Perfect Secrecy mode, recordings are decrypted by JavaScript served by shellz. Malicious code served to your browser could leak a key you unlock.
shellz decryptlets you verify and decrypt recordings offline, without the web app. - Processes that don't start a session aren't recorded. shellz records every agent that logs into your servers or opens a shell in a container. An agent running as a service or cron job never logs in, so use your platform's audit tools for those.
Compliance
Recording privileged sessions, keeping tamper-evident records for a fixed period and reviewing access is part of many control frameworks. shellz helps you meet SOC 2, ISO 27001, PCI DSS and HIPAA requirements for monitoring privileged access, alongside your own policies and other controls.
Reporting a vulnerability
Email hello@shellz.dev with "security" in the subject, and include steps to reproduce. Please don't open public issues for vulnerabilities.