Audit Log

TameFlare maintains an append-only audit log that records every action request, policy decision, approval, execution, and system event. This page covers the audit architecture, schema, retention, export, and compliance evidence.

Architecture

Append-only design

The audit log is append-only. There is no API to delete, modify, or overwrite audit events. Every event is written once and never changed.

What gets logged

Every significant action in TameFlare creates an audit event:

Event schema

Every audit event contains these fields:

Event-specific details

action.requested

{
  "action_type": "github.pr.merge",
  "resource": {"provider": "github", "target": "acme/api", "environment": "production"},
  "parameters": {"pull_number": 42},
  "risk_score": 45,
  "risk_hints": {"production_target": true, "irreversible": false}
}

action.denied

{
  "decision": "deny",
  "reason": "Cannot delete protected branches",
  "matched_policy": "pol_github_branch_safety",
  "matched_rule": "block-protected-branch-deletion",
  "risk_score": 85
}

action.allowed

{
  "decision": "allow",
  "reason": "Development actions are auto-approved",
  "matched_policy": "pol_github_branch_safety",
  "matched_rule": "allow-dev-actions",
  "decision_token_kid": "configured_key",
  "risk_score": 10
}

approval.responded

{
  "approved": true,
  "responded_by": "alice@company.com",
  "response_time_seconds": 45,
  "note": "Reviewed PR, looks good"
}

kill_switch.activated

{
  "scope": "all",
  "activated_by": "alice@company.com",
  "reason": "Suspicious agent behavior detected"
}

Complete event type list

Retention

Per-tier retention

Cleanup job

Audit events older than the retention period are purged by the maintenance cleanup job:

# Manual cleanup
curl -X POST \
  -H "Authorization: Bearer $MAINTENANCE_SECRET" \
  https://tameflare.com/api/maintenance/cleanup

The cleanup job purges:

• Audit events older than AUDIT_RETENTION_DAYS
• Expired session tokens
• Used nonces older than 24 hours

Automated cleanup (cron)

# Daily at 3 AM
0 3 * * * curl -sf -X POST -H "Authorization: Bearer $MAINTENANCE_SECRET" https://tameflare.com/api/maintenance/cleanup

What happens after retention

• Events are permanently deleted from the SQLite database
• No archive is created automatically - export before retention expires if you need long-term storage
• The cleanup is irreversible

Export

CSV export (dashboard)

1. Navigate to Audit Log in the dashboard
2. Apply filters (event type, date range, agent)
3. Click Export CSV

The CSV includes all fields: event ID, type, agent, user, timestamp, and the full details JSON.

CSV export (API)

curl -H "Cookie: session=YOUR_SESSION" \
  "https://tameflare.com/api/dashboard/audit-export?event_type=action.denied&from=2026-01-01&to=2026-02-01" \
  > denied-actions-jan.csv

Query parameters:

• event_type - filter by event type
• from / to - date range (ISO 8601)
• agent_id - filter by agent

Webhook forwarding

Configure webhook_url on action requests to receive real-time event notifications:

{
  "action_spec": { "type": "github.pr.merge", ... },
  "webhook_url": "https://your-siem.example.com/ingest/TameFlare"
}

TameFlare sends a POST to the webhook URL when the action is decided (allowed, denied, or approved). The payload includes the full action spec, decision, and audit metadata.

SIEM integration

There is no native syslog output. For syslog integration, use a webhook-to-syslog bridge or export CSV and ingest via your SIEM's file collector.

Compliance evidence

Proving the approval chain

For auditors who need to verify that an action was properly authorized, TameFlare provides a complete chain of evidence:

1. action.requested  - Agent submitted the request (timestamp, action spec, risk score)
2. action.denied OR action.pending_approval - Policy evaluation result (matched policy, rule, reason)
3. approval.responded - Human approved/denied (who, when, note)
4. action.executed   - Gateway executed the action (timestamp, upstream status)

Generating an audit trail for a specific action

# Get all events for a specific action request
curl -H "Cookie: session=YOUR_SESSION" \
  "https://tameflare.com/api/dashboard/audit-export?action_request_id=act_abc123" \
  > action-trail.csv

Or view in the dashboard: Actions → (click action) → Audit Timeline

The action detail page shows the complete timeline:

What TameFlare can prove

What TameFlare cannot prove

For regulatory environments requiring tamper-evident logs, export events in real-time to an external SIEM with cryptographic integrity (e.g., AWS CloudTrail, Splunk with hash verification).

Next steps

• Security - full security model
• Deployment Topology - how components connect
• Compliance - data sovereignty and regulatory alignment