Audit Trail

The Audit Trail page at /dashboard/audit provides a complete, immutable record of every action taken by agents, users, and the system. Every entry is part of a cryptographic hash chain, making the log tamper-evident and verifiable.

Header

The page header displays:

Audit Trail
Immutable event log · Hash chain integrity · 2,847 events

                                        [Chain verified ✓]

Filters

Two rows of filter controls appear below the header:

Type Filters

Filter events by category. Each filter shows its event count:

Each filter button displays a colored dot (not an emoji) followed by the label and a count badge:

[● All (2,847)]  [● Tasks (1,203)]  [● Reviews (892)]  [● Deploys (445)]  [● Incidents (307)]

Risk Filters

Filter events by risk level using pill-shaped buttons:

[● All]  [● Low]  [● Medium]  [● High]  [● Critical]

System Events Toggle

A "System events" toggle appears alongside the filter controls. When disabled (the default), GitHub and Vercel webhook events are hidden from the timeline. These events include push notifications, deployment status updates, and CI/CD triggers that can add noise when reviewing agent activity. Enable the toggle to see the full, unfiltered event stream.

Search Bar

A search input below the filters searches across multiple fields:

• Actor — who performed the action
• Action — the event type
• Detail — the event description
• Project — the associated project name
• Event ID — the unique event identifier

Search is performed client-side on the currently loaded events and triggers a server-side search for broader results when the user presses Enter.

🔍 Search events by actor, action, detail, project, or event ID...

Event Table

The main content area is a table displaying audit events. Events are ordered newest-first.

Table Columns

Actor Color Coding

The formatActor function resolves Slack UIDs to human-readable display names. For example, U0ABC123XY becomes "Sarah Chen" if that mapping exists. Otherwise, the raw UID is displayed.

Action Badges

Action types are displayed in monospace (JetBrains Mono) font with a subtle background:

task.complete    review.start    deploy.request    incident.detect

Risk Badges

Result Badges

Example Table Row

● 3m ago  Sarah Chen  task.complete  "Added health check endpoint at /api/h…"  LOW  SUCCESS  ▸

Expandable Rows

Clicking the chevron (or anywhere on the row) expands it to show full event details:

┌─────────────────────────────────────────────────────────────┐
│ ● 3m ago  Sarah Chen  task.complete  "Added health…"  LOW  │
├─────────────────────────────────────────────────────────────┤
│ Event ID:   evt-a1b2c3d4-e5f6-7890-abcd-ef1234567890       │
│ Timestamp:  2025-03-20T14:32:15.847Z                        │
│ Project:    codespar/codespar                                │
│ Hash:       sha256:9f86d08...c7e8c                           │
│ Full Detail: Added health check endpoint at /api/health     │
│              that returns server status, uptime, and         │
│              database connectivity information.              │
└─────────────────────────────────────────────────────────────┘

Pagination

The audit trail uses server-side pagination:

← Previous    Page 1 of 143    Next →

• Page size: 20 events per page
• Previous / Next buttons navigate between pages
• Page indicator shows current page and total page count
• Filters and search are applied server-side, so pagination reflects the filtered result set

LIVE Indicator

When the dashboard is connected to a live backend and actively polling for new events, a LIVE indicator appears in the top-right corner of the audit trail:

● LIVE

The dot pulses gently to indicate active polling. New events appear at the top of the table automatically without requiring a page refresh.

When the backend is unreachable or polling is paused, the indicator disappears.

Hash Chain Verification

The audit trail's hash chain provides tamper evidence. Each event's hash is computed from:

1. The event's own data (ID, timestamp, actor, action, detail, risk, result)
2. The hash of the previous event

hash(event_n) = SHA-256(event_n.data + hash(event_n-1))

The "Chain verified" badge in the header confirms that the dashboard has validated the chain for all displayed events. If a chain break is detected (a hash doesn't match the expected value), the badge changes to a red warning:

[Chain broken ✕]

This would indicate that an event has been modified or deleted outside of normal operation.

API Endpoints

The audit trail page interacts with these endpoints:

All requests include the x-org-id header for tenant isolation.

Next Steps

• Agent Detail — view activity for a specific agent
• Settings — configure team roles and policies
• Security — learn about RBAC and approval flows