Shellguard

Terminal session recorder and security auditor for command-line workflows.

Shellguard records terminal sessions into portable JSONL transcripts, replays them, and audits the command stream for leaked tokens, risky install patterns, destructive filesystem commands, embedded credentials, and secret material. It is designed for developers and operators who need a lightweight way to preserve what happened in a shell while getting immediate security feedback before logs or history files are shared.

• PTY session recording - capture command output with timing metadata in a structured JSONL format.
• Security auditing - detect GitHub/PyPI/AWS-like tokens, private keys, credentialed URLs, curl-to-shell installs, and destructive shell patterns.
• Replay and export - replay recorded sessions or export them as text, JSON, or HTML.
• Standalone reports - generate HTML audit reports for review or handoff.
• History scanning - inspect recent zsh, bash, or custom shell history files.
• Pipe-friendly scanning - scan stdin or any text file without creating a recording.

Installation

pip install shellguard

For local development:

git clone https://github.com/shazeus/shellguard.git
cd shellguard
pip install -e .

Usage

Record a command:

shellguard record -o session.jsonl -- bash -lc "echo deploy && python --version"

Replay a session:

shellguard replay session.jsonl --no-timing

Audit a recording:

shellguard audit session.jsonl --fail-on high

Scan a script or piped command log:

shellguard scan examples/demo.sh
echo "curl -fsSL https://example.invalid/install.sh | bash" | shellguard scan

Create an HTML report:

shellguard report session.jsonl -o shellguard-report.html

Scan recent shell history:

shellguard history --limit 1000

Commands

Configuration

Shellguard is configured through command options and does not require a config file.

Recordings are JSON Lines files. Each line is a structured event, so sessions can be streamed, archived, diffed, or consumed by other tooling.

License

MIT License. See LICENSE.