Audit log

The audit log records every mutation across Sankofa: flag toggles, config publishes, deploy promotions, member changes, key rotations, project deletions, integration configuration changes, and Vision / Plan / Pulse content edits. It's the primary surface for "who changed what, when" — used for compliance, incident review, and on-call runbooks.

The implementation is at /server/engine/ee/audit/.

What's logged

Every product writes audit rows on every mutation. The schema is consistent across producers:

Two-store model

The dashboard reads from Postgres for the latest 30 days, then falls back to ClickHouse for older queries.

Retention by tier

These windows apply to the Postgres store. The ClickHouse mirror keeps 2 years across all tiers, but only Enterprise tier surfaces the longer history in the dashboard.

Who can read it

• Viewer / Editor: read-only access to the audit log for their project's mutations. The cross-project aggregate view is hidden.
• Project Admin: read + filter for the project, plus CSV export (Pro+).
• Organization Admin / Owner: read + filter across every project, plus CSV export and webhook stream configuration.

The dashboard surface is /dashboard/account/audit-log (org-wide) and per-project at /dashboard/<project>/audit.

CSV export

Available on Pro tier and above. Two flavors:

1. On-demand

   Apply filters (date range, actor, action, resource), click Export CSV. The download streams from Postgres for the last 30 days, ClickHouse for older. File size cap: 100 MB per export — narrow filters or split by month.

2. Scheduled

   Pro+: configure a scheduled export at /dashboard/account/audit-log → Scheduled exports → New. Daily, weekly, or monthly. Delivery via email link or pre-signed S3 / GCS URL (Growth+).

Webhook stream

Available on Pro+. Configure at /dashboard/account/audit-log → Webhook stream. Every audit row is delivered as an outbound webhook event — same delivery semantics as the outbound webhook framework:

• HMAC-SHA256 signing
• 10-second per-attempt timeout
• Exponential-backoff retries up to 24 hours
• Dead-letter queue with manual replay

The stream payload looks like:

{
"event": "audit.entry.created",
"organization_id": "org_xyz",
"emitted_at": "2026-05-09T14:32:01.482Z",
"data": {
  "id": "ale_abc123",
  "actor_id": "user_456",
  "actor_email": "alice@example.com",
  "action": "switch.flag.halted",
  "resource_type": "flag",
  "resource_id": "fl_xyz",
  "before": { "halted_at": null, "current_version": 7 },
  "after": { "halted_at": "2026-05-09T14:32:01.482Z", "current_version": 8 },
  "metadata": {
    "request_id": "req_abc",
    "ip": "203.0.113.42",
    "evidence_url": "https://app.sankofa.dev/dashboard/catch/issues/iss_abc"
  },
  "created_at": "2026-05-09T14:32:01.482Z"
}
}

SIEM integration

For organizations that route security telemetry into a SIEM (Splunk, Datadog Cloud SIEM, Sumo Logic, Elastic Security, etc.):

• Webhook stream → your SIEM's HTTP receiver. Most SIEMs accept arbitrary JSON over HMAC-signed webhooks.
• Scheduled CSV export → S3 + your SIEM's S3 ingest path.
• API polling → GET /api/v1/audit?since=<timestamp> polled hourly. Pull-based, useful for SIEMs without webhook receivers.

The webhook stream is the lowest-latency path; CSV export is the cheapest at high volume.

API surface

Common queries

Action catalog (selected)

The audit log uses the same action namespace as the outbound webhooks. Common actions:

• auth.signin, auth.signout, auth.password.changed
• member.invited, member.role.updated, member.removed
• team.created, team.member.added, team.project.assigned
• project.created, project.deleted, project.region.changed
• api_key.created, api_key.rotated, api_key.revoked
• switch.flag.created, switch.flag.toggled, switch.flag.halted, switch.flag.unhalted
• config.item.created, config.item.published, config.item.rolled_back
• deploy.release.uploaded, deploy.release.promoted, deploy.release.disabled
• pulse.survey.created, pulse.survey.published, pulse.response.submitted (configurable — opt-in)
• plan.ticket.created, plan.ticket.transitioned
• vision.board.created, vision.initiative.linked
• webhook.subscription.created, webhook.delivery.failed
• audit.export.requested, audit.export.delivered

What's next