Skip to content

audit-logging.md

Latest commit

 

History

History
600 lines (452 loc) · 13.3 KB

audit-logging.md

File metadata and controls

600 lines (452 loc) · 13.3 KB

Audit Logging

Compliance-ready audit trails for Loki Mode operations.

Overview

Audit logging captures all significant events for compliance requirements (SOC2, HIPAA), security monitoring, debugging, and usage analytics. Audit logging is enabled by default as of v5.37.0.

Configuration

Enable/Disable Audit Logging

Audit logging is on by default. To disable:

export LOKI_AUDIT_DISABLED=true

The legacy variable LOKI_ENTERPRISE_AUDIT=true still works and will force audit logging on regardless of LOKI_AUDIT_DISABLED.

Configuration File

# .loki/config.yaml
enterprise:
  audit:
    enabled: true              # Audit logging enabled (default)
    level: info                # Minimum level: debug, info, warning, error
    retention_days: 90         # Days to keep logs
    max_file_size: 100         # MB per file before rotation
    compress: true             # Compress rotated files
    integrity_check: true      # Enable SHA-256 chain hashing (v5.38.0)
    syslog_enabled: false      # Forward to external syslog
    exclude_events:            # Events to exclude
      - api.request
    include_metadata:          # Additional metadata fields
      - environment
      - deployment_id

Environment Variables

Variable Default Description
LOKI_AUDIT_DISABLED false Set to true to disable audit logging
LOKI_ENTERPRISE_AUDIT false Force audit on (legacy, audit is now on by default)
LOKI_AUDIT_LEVEL info Minimum log level: debug, info, warning, error
LOKI_AUDIT_RETENTION 90 Retention period in days
LOKI_AUDIT_SYSLOG_HOST - Syslog server hostname for forwarding
LOKI_AUDIT_SYSLOG_PORT 514 Syslog server port
LOKI_AUDIT_SYSLOG_PROTO udp Syslog protocol: udp or tcp
LOKI_AUDIT_NO_INTEGRITY false Disable SHA-256 chain hashing

Logged Events

Session Events

Event Description
session.start Session started with PRD
session.stop Session stopped (manual or automatic)
session.pause Session paused
session.resume Session resumed
session.complete Session completed successfully
session.fail Session failed with error

API Events

Event Description
api.request API request received
api.response API response sent
api.error API error occurred

Authentication Events

Event Description
auth.token.create Token created
auth.token.use Token used for authentication
auth.token.revoke Token revoked
auth.fail Authentication failed
auth.oidc.success OIDC authentication succeeded
auth.oidc.fail OIDC authentication failed

Task Events

Event Description
task.create Task created in queue
task.start Task started by agent
task.complete Task completed successfully
task.fail Task failed with error

Agent Events

Event Description
agent.spawn Agent spawned
agent.action Agent performed action
agent.complete Agent completed work
agent.fail Agent encountered error

Log Format

JSONL Format

Audit logs use JSON Lines format (one JSON object per line):

{
  "timestamp": "2026-02-15T14:30:00.000Z",
  "event": "session.start",
  "level": "info",
  "actor": "user",
  "details": {
    "prd": "./prd.md",
    "provider": "claude",
    "parallel": false
  },
  "metadata": {
    "hostname": "dev-machine",
    "pid": 12345,
    "version": "5.42.2"
  }
}

Fields

Field Type Description
timestamp ISO 8601 Event timestamp in UTC
event string Event type (e.g., session.start)
level string Log level: debug, info, warning, error
actor string Who performed the action (user, token:name, agent:type)
resource string Resource affected (optional)
details object Event-specific details
metadata object System metadata (hostname, PID, version)
chain_hash string SHA-256 chain hash for integrity (v5.38.0)

Log Location

# Audit log directory
~/.loki/dashboard/audit/

# Daily rotation
audit-2026-02-15.jsonl
audit-2026-02-14.jsonl
audit-2026-02-13.jsonl

# Compressed archives (after rotation)
audit-2026-02-12.jsonl.gz
audit-2026-02-11.jsonl.gz

CLI Commands

View Summary

loki enterprise audit summary

Output:

Audit Log Summary (Last 24 Hours)

Events by Type:
  session.start:    5
  session.complete: 4
  session.fail:     1
  api.request:     42
  auth.token.use:  15

Events by Level:
  info:    58
  warning:  3
  error:    1

Events by Actor:
  user:         10
  token:ci-bot: 35
  agent:dev:    13

Tail Recent Entries

# Last 20 entries
loki enterprise audit tail

# Follow new entries in real-time
loki enterprise audit tail --follow

# Filter by event type
loki enterprise audit tail --event session.start

# Filter by level
loki enterprise audit tail --level error

Search Logs

# Search by event
loki enterprise audit search --event auth.fail

# Search by date range
loki enterprise audit search --from 2026-02-01 --to 2026-02-15

# Search by actor
loki enterprise audit search --actor ci-bot

# Combined filters
loki enterprise audit search --event task.fail --from 2026-02-15 --level error

Export Logs

# Export to file
loki enterprise audit export --output audit-export.json

# Export with filters
loki enterprise audit export --from 2026-01-01 --level error --output errors.json

# Export as CSV
loki enterprise audit export --format csv --output audit.csv

API Endpoints

Get Audit Entries

# Recent entries
curl "http://localhost:57374/api/audit?limit=50"

# With filters
curl "http://localhost:57374/api/audit?event=session.start&limit=100"

# Date range
curl "http://localhost:57374/api/audit?start=2026-02-01&end=2026-02-15"

Query Parameters

Parameter Type Description
start ISO date Start timestamp
end ISO date End timestamp
event string Filter by event type
level string Filter by level (debug, info, warning, error)
actor string Filter by actor
limit number Max results (default: 100)
offset number Pagination offset

Get Summary

curl http://localhost:57374/api/audit/summary

Response:

{
  "period": "24h",
  "total_events": 62,
  "by_type": {
    "session.start": 5,
    "session.complete": 4,
    "api.request": 42
  },
  "by_level": {
    "info": 58,
    "warning": 3,
    "error": 1
  }
}

Log Integrity (v5.38.0)

Audit entries are chain-hashed with SHA-256 for tamper detection.

How It Works

Each audit entry includes a chain_hash field:

  1. First entry hashes against a genesis hash (0 * 64)
  2. Each subsequent entry hashes: SHA256(previous_hash + current_entry_json)
  3. Any modification to a past entry invalidates all subsequent hashes

Verification

# Verify integrity via CLI
loki audit verify

# Python verification
from dashboard.audit import verify_log_integrity

result = verify_log_integrity("~/.loki/dashboard/audit/audit-2026-02-15.jsonl")
print(f"Valid: {result['valid']}")
print(f"Entries checked: {result['entries_checked']}")
if not result['valid']:
    print(f"First tampered line: {result['first_tampered_line']}")

Disabling Chain Hashing

export LOKI_AUDIT_NO_INTEGRITY=true

SIEM Integration (v5.38.0)

Syslog Forwarding

Forward audit events to external syslog servers for SIEM integration:

export LOKI_AUDIT_SYSLOG_HOST=syslog.example.com
export LOKI_AUDIT_SYSLOG_PORT=514
export LOKI_AUDIT_SYSLOG_PROTO=udp

Details:

  • Uses Python stdlib logging.handlers.SysLogHandler
  • Facility: LOG_LOCAL0
  • Security actions forwarded at WARNING level
  • Fire-and-forget: syslog failures do not block audit writes
  • Supports both UDP and TCP protocols

Splunk

# Configure Splunk Universal Forwarder
/opt/splunkforwarder/bin/splunk add monitor ~/.loki/dashboard/audit/ \
  -sourcetype loki:audit \
  -index security

# Or use HTTP Event Collector
curl -H "Authorization: Splunk YOUR-HEC-TOKEN" \
     -d "$(cat ~/.loki/dashboard/audit/audit-2026-02-15.jsonl)" \
     https://splunk.example.com:8088/services/collector/raw

Datadog

# datadog.yaml
logs:
  - type: file
    path: /home/user/.loki/dashboard/audit/*.jsonl
    source: loki-mode
    service: loki-mode
    tags:
      - env:production
      - team:devops

Elastic SIEM

# Filebeat configuration
cat > /etc/filebeat/inputs.d/loki-audit.yml <<EOF
- type: log
  enabled: true
  paths:
    - /home/user/.loki/dashboard/audit/*.jsonl
  json.keys_under_root: true
  fields:
    log_type: audit
    application: loki-mode
  tags: ["loki", "audit"]
EOF

# Restart Filebeat
systemctl restart filebeat

Agent Action Audit (v5.38.0)

In addition to dashboard audit logs, agent actions are tracked separately.

Location

.loki/logs/agent-audit.jsonl

Tracked Actions

Action Description
cli_invoke CLI command executed by agent
git_commit Git commit performed by agent
file_write File write operation
file_delete File delete operation
session_start Agent session started
session_stop Agent session stopped

Entry Format

{
  "timestamp": "2026-02-15T14:30:00Z",
  "action": "git_commit",
  "agent": "development",
  "branch": "loki/session-20260215-143022-12345",
  "details": {
    "message": "Add authentication module",
    "files_changed": 3,
    "insertions": 150,
    "deletions": 20
  }
}

CLI Commands

# View recent agent actions
loki audit log

# Count total agent actions
loki audit count

# Filter by action type
loki audit log --action git_commit

# Show help
loki audit help

Compliance

SOC2

Audit logging supports SOC2 requirements:

  • CC6.1 - Logical access security (auth events)
  • CC7.2 - System monitoring (session and task events)
  • CC7.3 - Incident response (error events)

Configuration:

enterprise:
  audit:
    enabled: true
    retention_days: 365  # 1 year minimum for SOC2
    integrity_check: true
    syslog_enabled: true

HIPAA

For healthcare applications:

  • Enable all authentication events
  • Set retention to minimum 6 years
  • Enable log encryption
  • Forward to SIEM for monitoring

Configuration:

enterprise:
  audit:
    enabled: true
    retention_days: 2190  # 6 years
    encrypt: true
    integrity_check: true
    syslog_enabled: true

GDPR

For European deployments:

  • Log access to personal data
  • Provide data export capability
  • Support right to deletion
  • Enable audit trail for data access

Configuration:

enterprise:
  audit:
    enabled: true
    retention_days: 365
    gdpr_compliance: true
    log_data_access: true

Troubleshooting

Logs Not Being Created

# Check if audit logging is enabled
loki enterprise status

# Verify directory exists and is writable
ls -la ~/.loki/dashboard/audit/
mkdir -p ~/.loki/dashboard/audit/
chmod 700 ~/.loki/dashboard/audit/

# Check disk space
df -h ~/.loki/

# Test log write
echo '{"test": "entry"}' >> ~/.loki/dashboard/audit/test.jsonl

Missing Events

# Check minimum level configuration
loki enterprise audit summary

# Lower level to capture more events
export LOKI_AUDIT_LEVEL=debug

# Check exclude_events in config
cat .loki/config.yaml | grep -A 5 exclude_events

Disk Space Issues

# Check current usage
du -sh ~/.loki/dashboard/audit/

# Find large log files
find ~/.loki/dashboard/audit/ -type f -size +100M

# Manually clean old logs
find ~/.loki/dashboard/audit/ -name "*.jsonl" -mtime +30 -delete

# Enable compression
export LOKI_AUDIT_COMPRESS=true

Syslog Not Forwarding

# Test syslog connectivity
nc -zv syslog.example.com 514

# Check syslog configuration
echo $LOKI_AUDIT_SYSLOG_HOST
echo $LOKI_AUDIT_SYSLOG_PORT

# View syslog errors in audit log
loki enterprise audit tail --event syslog.error

# Test manual syslog send
logger -n syslog.example.com -P 514 "Test from Loki Mode"

Best Practices

Security

  1. Enable audit logging in production (enabled by default)
  2. Set appropriate retention period for compliance
  3. Enable integrity checking (SHA-256 chain hashing)
  4. Forward logs to external SIEM
  5. Restrict access to audit logs (file permissions 600)
  6. Encrypt audit logs at rest
  7. Monitor for suspicious patterns

Performance

  1. Use async logging to avoid blocking
  2. Rotate logs daily
  3. Compress rotated logs
  4. Set reasonable retention period
  5. Exclude high-volume low-value events (e.g., api.request)

Compliance

  1. Document audit logging configuration
  2. Test log integrity verification regularly
  3. Perform quarterly audit log reviews
  4. Export logs for long-term archival
  5. Integrate with compliance monitoring tools

See Also