Compliance Use Cases

shellfirm's audit trail provides a structured record of every risky command evaluated, the decision made, and the context in which it was run. This data is valuable for compliance frameworks, security monitoring, and incident investigation.

SOC2 compliance

SOC2 Trust Services Criteria require organizations to demonstrate that they have controls in place for:

• CC6.1 -- Logical access security: shellfirm's audit log records who (agent or user) ran what command, when, and with what outcome
• CC7.2 -- Monitoring activities: the audit trail provides continuous monitoring of command execution
• CC8.1 -- Change management: the log captures infrastructure and deployment commands

What the audit trail proves

• Every destructive command was evaluated against safety patterns
• Risky commands required explicit confirmation
• Denied commands were blocked and recorded
• Context signals (production environment, root access, SSH sessions) were factored into risk assessment

Retention policies

Default behavior

shellfirm appends to a single log file indefinitely. For compliance, you should implement a retention policy.

Recommended setup

# Daily rotation with 365-day retention
# /etc/logrotate.d/shellfirm
~/.shellfirm/audit.log {
    daily
    rotate 365
    compress
    missingok
    notifempty
    copytruncate
}

Archival

For long-term retention, archive logs to object storage:

# Archive monthly to S3
aws s3 cp ~/.shellfirm/audit.log.$(date -d 'last month' +%Y%m)*.gz s3://audit-logs/shellfirm/

SIEM integration

Forwarding to log aggregation

shellfirm's JSON-lines format is natively supported by most SIEM and log aggregation tools.

Datadog

# /etc/datadog-agent/conf.d/shellfirm.d/conf.yaml
logs:
  - type: file
    path: ~/.shellfirm/audit.log
    source: shellfirm
    service: shellfirm
    log_processing_rules:
      - type: multi_line
        name: json_lines
        pattern: '^\{'

Splunk

# inputs.conf
[monitor://~/.shellfirm/audit.log]
sourcetype = shellfirm:audit
index = security

ELK Stack (Filebeat)

# filebeat.yml
filebeat.inputs:
  - type: log
    paths:
      - ~/.shellfirm/audit.log
    json.keys_under_root: true
    json.add_error_key: true
    fields:
      source: shellfirm

Alerting

Critical event alerts

Set up alerts for events that require immediate attention:

# Monitor for denied commands in production
tail -f ~/.shellfirm/audit.log | jq -rc 'select(.outcome == "DENIED" and (.context_labels | any(startswith("k8s=prod")))) | "ALERT: Denied command in production: \(.command)"'

Agent misbehavior detection

# Alert when an agent session accumulates multiple denials
cat ~/.shellfirm/audit.log \
  | jq -r 'select(.outcome == "DENIED" and .agent_session_id != null) | .agent_session_id' \
  | sort | uniq -c | sort -rn \
  | awk '$1 > 3 {print "WARNING: Agent session " $2 " has " $1 " denied commands"}'

Unusual activity patterns

# Commands run outside business hours
cat ~/.shellfirm/audit.log \
  | jq -r 'select((.timestamp[11:13] | tonumber) < 8 or (.timestamp[11:13] | tonumber) > 18) | [.timestamp, .command, .outcome] | @tsv'

Analysis queries

Security audit report

Generate a summary for security reviews:

echo "=== shellfirm Audit Report ==="
echo ""
echo "Total events:"
wc -l < ~/.shellfirm/audit.log
echo ""
echo "Events by outcome:"
cat ~/.shellfirm/audit.log | jq -r '.outcome' | sort | uniq -c | sort -rn
echo ""
echo "Events by severity:"
cat ~/.shellfirm/audit.log | jq -r '.severity' | sort | uniq -c | sort -rn
echo ""
echo "Top 10 triggered patterns:"
cat ~/.shellfirm/audit.log | jq -r '.matched_ids[]' | sort | uniq -c | sort -rn | head -10
echo ""
echo "Agent sessions:"
cat ~/.shellfirm/audit.log | jq -r 'select(.agent_session_id != null) | .agent_session_id' | sort -u | wc -l
echo ""
echo "Denied commands:"
cat ~/.shellfirm/audit.log | jq -r 'select(.outcome == "DENIED") | [.timestamp, .command] | @tsv'

Incident investigation

When investigating an incident, query the audit log for the relevant timeframe:

# Commands around a specific time
cat ~/.shellfirm/audit.log \
  | jq -c 'select(.timestamp > "2026-02-23T14:00:00Z" and .timestamp < "2026-02-23T15:00:00Z")' \
  | jq .

# All commands from a specific agent session
cat ~/.shellfirm/audit.log \
  | jq -c 'select(.agent_session_id == "sess-incident-123")' \
  | jq .

# Commands that affected production
cat ~/.shellfirm/audit.log \
  | jq -c 'select(.context_labels | any(contains("prod")))' \
  | jq .

Privacy considerations

The audit log contains full command strings, which may include:

• Database connection strings with credentials
• API keys passed as command arguments
• File paths that reveal project structure

Ensure appropriate access controls on the audit log file and consider redacting sensitive data before forwarding to external systems.