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

Command	Description	Example
shellguard record [command...]	Record a command or interactive shell session to JSONL.	shellguard record -o session.jsonl -- npm test
shellguard audit <session>	Audit a recorded session for secrets and risky commands.	shellguard audit session.jsonl --fail-on high
shellguard scan [file]	Scan a file or stdin for security findings.	shellguard scan deploy.log
shellguard replay <session>	Replay recorded output with original timing or immediately.	shellguard replay session.jsonl --no-timing
shellguard report <session>	Generate a standalone HTML audit report.	shellguard report session.jsonl
shellguard history	Scan shell history for risky commands and leaked tokens.	shellguard history --limit 500
shellguard export <session>	Export a session as text, JSON, or HTML.	shellguard export session.jsonl --format text
shellguard rules	List built-in audit rules.	shellguard rules

Configuration

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

Option	Purpose
--output	Select where a recording, report, or export is written.
--shell	Run a recorded command through the current shell.
--fail-on	Return exit code 2 when findings meet a severity threshold.
--json-output	Print scanner or auditor results as JSON.
--speed	Adjust replay timing.
--path	Scan a specific shell history file.
--limit	Restrict history scanning to the most recent commands.

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.