shellrec

Terminal session recorder with Ed25519 chain-of-custody — DORA Art. 17 evidence artefact

v1.0.0

NixOS x86_64

Quick start

Install via jcli (recommended)

jcli install shellrec

If you don't have jcli yet, install it first with curl -fsSL https://cli.johlem.net/tools/jcli/install.sh | bash.

Install directly

curl -fsSL https://cli.johlem.net/install.sh | bash -s -- shellrec

Ed25519 signature verification is mandatory by default; set ALLOW_UNVERIFIED=1 to explicitly opt out (not recommended).

Run it

shellrec --help                # subcommand catalogue + flags
shellrec --full                # extended help across every subcommand
shellrec --about               # machine-readable attribution (JSON)
shellrec --version             # version string

What it does

shellrec wraps a child command in a pseudoterminal (portable-pty), captures every byte to a deterministic NDJSON log under $XDG_DATA_HOME/cli-johlem/shellrec/recordings/, and (on `sign`) appends a detached Ed25519 signature. Seven subcommands: record (PTY-wrapped), play (real-time replay with --speed), transcript (ANSI-stripped plain text), sign (auto-generates keypair on first use), verify, list, info (`-F jfind` emits a shellrec session record). File format `shellrec/v1`: NDJSON with header / out / in (when --capture-stdin) / footer / sig lines. Signature covers everything before the sig line; SHA-256 anchor is embedded for no-pubkey integrity checks. jfind/v1 output: asset-inventory for clean recordings (signed or not), policy-violation High when verify fails. Pre-fills DORA Art. 12 (ICT-related incident management — evidence retention) + DORA Art. 17 (incident reporting evidence basis) + NIS2 Art. 23 + ISO/IEC 27001:2022 A.5.28. The forensic answer to script(1): tamper-evident artefacts that bind a session to a specific operator and a specific keypair. Suite app: blueteam (incident-response evidence). 4 unit + 13 integration tests; zero warnings.

Authorisation and warranty: use only in environments where you have explicit written authorisation. This tool is provided as-is with no warranty. Report vulnerabilities privately at security@johlem.net.

Compliance crosswalk

This table lists controls where shellrec's output may form part of the evidence set presented to an assessor. It does not claim shellrec alone satisfies any framework — every control still requires assessor judgment and typically evidence from other sources.

Schema: compliance-crosswalk/v1 · Machine-readable: tools/shellrec/compliance.json

ISO27001 — ISO/IEC 27001:2022

Ref	Name	How	Coverage
`A.8.15`	Logging	Signed session recordings + Ed25519 chain of custody.	evidences

PCI-DSS — PCI-DSS v4.0

Ref	Name	How	Coverage
`Req. 10.2`	Audit logs (privileged actions)	Records privileged-session activity with tamper-evident signatures.	evidences

SOC2 — SOC 2 (Trust Services Criteria)

Ref	Name	How	Coverage
`CC7.2`	System monitoring — detection of unauthorized changes	Session recordings form the change-evidence artefact.	evidences

Release artefacts & provenance

Every signed release ships with checksum + signature sidecars plus a CycloneDX SBOM. Enterprise procurement can pin third-party components without unpacking the binary.

manifest.json — pinned SHA-256 + .sig URL + SBOM URL per platform
johlem-release.pub — Ed25519 public key used by signify -V (fingerprint: 4532510f…6748, pinned in jcli verify)
CHANGELOG.md — semver-tagged release notes
Security contact: security@johlem.net