shellfirm audit

The audit command provides access to shellfirm's audit log -- a record of every intercepted command and its outcome.

Usage

shellfirm audit <SUBCOMMAND>

Subcommands

list

Display all audit events:

shellfirm audit list

Shows events in a human-readable format with timestamp, command, matched patterns, and outcome.

search

Search audit events with filters:

shellfirm audit search [OPTIONS]

Flag	Description
--outcome <OUTCOME>	Filter by outcome: allowed, denied, skipped, cancelled
--session <SESSION_ID>	Filter by agent session ID

Examples:

# Find all denied commands
shellfirm audit search --outcome denied

# Find commands from a specific agent session
shellfirm audit search --session sess-abc-123

clear

Delete the entire audit log:

shellfirm audit clear

This permanently removes the audit log file. The log will be recreated when the next event is recorded.

Log location

The audit log is stored at:

• macOS: ~/Library/Application Support/shellfirm/audit.log
• Linux: ~/.config/shellfirm/audit.log

Examples

# View all events
shellfirm audit list

# Find denied commands
shellfirm audit search --outcome denied

# Clear the log
shellfirm audit clear

Advanced analysis

For complex queries, use jq directly on the log file:

# Count events by outcome
cat ~/.shellfirm/audit.log | jq -r '.outcome' | sort | uniq -c

# Find critical severity events
cat ~/.shellfirm/audit.log | jq -c 'select(.severity == "Critical")'

See the Viewing Logs page for comprehensive jq examples.