Review the Audit Trail

Every tool execution decision in CoreLayer is recorded. This guide shows how to query and read audit entries.

Accessing Audit Logs

Audit entries are served by GET /api/audit and surfaced in the Control Center. They are a separate resource from approvals (/api/approvals) and from the event log (/api/events).

Log Entry Format

An entry records:

createdAt          2026-10-21T14:32:01Z
actor              jarvis
action             tool.execute
resource           filesystem:write /workspace/README.md
riskLevel          high
permissionDecision confirm
confirmedByUser    true
result             success
metadata           { ... }

Filtering Logs

GET /api/audit accepts:

• actor — who performed the action
• action — what was performed
• riskLevel — low | medium | high | critical
• since — ISO timestamp lower bound
• limit / offset — pagination

The response is { entries, total, count }.

Common Use Cases

Security Review

Check which high-risk actions were approved:

1. Query GET /api/audit?riskLevel=high&since=2026-10-01T00:00:00Z
2. Review resource and metadata for each entry
3. Confirm confirmedByUser is true where you expected a manual decision

Debugging

Find why a tool call did not run:

1. Filter by action
2. Check permissionDecision — deny means the policy blocked it
3. Cross-reference the run id in GET /api/runs/:id/events

Compliance

Produce a record of state-changing actions:

1. Query with riskLevel=high, then repeat with riskLevel=critical
2. Export the returned entries
3. Review every confirmedByUser: false entry — those were auto-decided

Log Retention

There is no retention setting. Entries live in the audit_log table of the configured database for as long as you keep them. An earlier version of this page documented a permissions.auditRetentionDays option that does not exist; prune with SQL or your database tooling if you need to limit growth.

Next Steps

• Permissions — configure policies
• Permission Guard — the safety model