Audit Setup

shellfirm's audit trail records every command that triggers a check pattern, along with the outcome (allowed, denied, cancelled, or skipped), matched patterns, context signals, and blast radius data.

Enabling audit logging

Audit logging is enabled by default. You do not need to do anything to start logging.

To verify the current setting:

shellfirm config show

Disabling audit logging

Edit ~/.config/shellfirm/settings.yaml:

audit_enabled: false

Or use the interactive editor:

shellfirm config edit

Re-enabling audit logging

Set audit_enabled: true in your settings file, or reset to defaults:

shellfirm config reset

Log location

The audit log is stored at:

~/.shellfirm/audit.log

More precisely, it is in the same directory as your shellfirm configuration:

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

The log file is created automatically when the first event is recorded. If the file does not exist, no events have been logged yet.

What gets logged

Every command that matches at least one check pattern generates an audit event. Commands that match no patterns are not logged (they pass through silently).

Each event records:

Field	Description
event_id	Unique ID linking pre-challenge and post-challenge entries
timestamp	ISO 8601 UTC timestamp
command	The full command string
matched_ids	List of matched pattern IDs
challenge_type	The challenge presented (Math, Enter, Yes, Deny)
outcome	ALLOWED, DENIED, SKIPPED, or CANCELLED
severity	Highest severity among matched patterns
context_labels	Runtime context (e.g., branch=main, ssh=true)
agent_name	AI agent name (if applicable)
agent_session_id	Agent session ID (if applicable)
blast_radius_scope	Impact scope (if blast radius enabled)
blast_radius_detail	Impact description (if blast radius enabled)

Log format

Events are stored as JSON-lines -- one JSON object per line:

{"event_id":"abc123","timestamp":"2026-02-23T14:30:00Z","command":"rm -rf /tmp/data","matched_ids":["fs:recursively_delete"],"challenge_type":"Math","outcome":"ALLOWED","context_labels":[],"severity":"High"}

This format is easy to parse with jq, ingest into log aggregation tools, and process with standard Unix tools.

Log rotation

shellfirm does not rotate logs automatically. The log file grows over time. For long-running systems, consider:

Manual rotation

# Rotate the log (move to timestamped backup)
mv ~/.shellfirm/audit.log ~/.shellfirm/audit.log.$(date +%Y%m%d)

Logrotate (Linux)

# /etc/logrotate.d/shellfirm
~/.shellfirm/audit.log {
    weekly
    rotate 12
    compress
    missingok
    notifempty
}

Clearing the log

shellfirm audit clear

This deletes the audit log file entirely.