Audit logging

Oxagen writes an audit record for every action that matters: every sign-in, every IAM decision, every capability call, every billing change, and every org management action. Two independent stores hold the records, each built for a different query pattern. ClickHouse chains each row's hash to the one before it, so a removed or inserted row shows when you recompute the chain.

Two independent audit storesCopy Anchor Link

Postgres: security.security_eventsCopy Anchor Link

Relational, queryable, and indexed for point lookups and compliance reporting.

• Retention: 7 years, enforced by monthly RANGE partitions. Oxagen drops partitions older than 7 years.
• Schema: id, occurred_at, event_type, actor_user_id, org_id, workspace_id, capability, outcome, ip, user_agent, request_id.
• Query surface: Organization → Audit (filtered UI), or the query_audit_log capability over the API.
• Use cases: point lookups ("did this person call this capability?"), compliance dashboard queries, and access-review exports.

ClickHouse: audit_eventsCopy Anchor Link

Append-only ReplacingMergeTree, built for high-volume analytics, with chain-hash tamper evidence.

• Retention: 7-year TTL column.
• Tamper evidence: each row includes a chain_hash field, SHA-256(previous_chain_hash | event_id | capability). The rows form a hash chain, so recomputing it from any anchor point shows a deletion or insertion in the middle. Concurrent writes from more than one process can read the same predecessor chain_hash (a known race documented in emit-audit.ts), so verification is advisory rather than cryptographically strict.
• Use cases: high-volume analytics queries, SIEM pulls, tamper checks, and trend analysis over audit event volumes.

Independent code paths write the two stores. For each invoke() call, the Postgres write uses the kernel's emitSecurityEvent() (a pluggable emitter), and the ClickHouse write uses emitAudit(), called inside checkIAM(). Both are independent fire-and-forget calls, and not every event type reaches both stores. Auth and billing events go only to Postgres. ClickHouse receives only IAM capability decisions. A failed write in either path does not fail the capability call.

Event taxonomyCopy Anchor Link

The taxonomy in packages/compliance/src/security-event-types.ts defines the event names. The tables below describe common events and mark reserved names. Consult that file for additions.

Auth lifecycleCopy Anchor Link

API key lifecycleCopy Anchor Link

Billing mutationsCopy Anchor Link

Capability authorizationCopy Anchor Link

Org managementCopy Anchor Link

Org lifecycleCopy Anchor Link

Plugin governanceCopy Anchor Link

SecretsCopy Anchor Link

Data planes and model credentialsCopy Anchor Link

Agent run integrityCopy Anchor Link

Security policyCopy Anchor Link

Access reviewCopy Anchor Link

Privacy / GDPRCopy Anchor Link

Adding a new event kind takes one edit to the taxonomy source file. The CI test checks that the Postgres CHECK constraint and the ClickHouse schema match that file, so schema drift fails CI.

CompletenessCopy Anchor Link

Every invoke() call, from any surface (app, API, or MCP), emits either a capability.invoke_allowed or a capability.invoke_denied event. No path through the capability boundary skips the emit, and there is no opt-out. A write can still fail, and a failed write does not fail the call. This is the SOC 2 completeness argument.

Accessing audit logsCopy Anchor Link

In the appCopy Anchor Link

Organization → Audit is a filterable view of security.security_events. Filter by:

• Event kind
• Acting principal
• Time range
• Outcome (allowed or denied)
• Capability name

Via APICopy Anchor Link

POST https://api.oxagen.sh/v1/{orgSlug}/{workspaceSlug}/audit/log/query
Authorization: Bearer ox_…
Content-Type: application/json

{
  "eventType": "capability.invoke_denied",
  "from": "2026-01-01T00:00:00Z"
}

The response is a JSON object with events (newest first), total, hasMore, limit, and offset. Page through results with limit (up to 200) and offset.

SIEM exportCopy Anchor Link

SIEM export (Splunk, Datadog, S3, or a JSONL webhook) is not available. Call query_audit_log on a schedule to pull audit events into an external SIEM.

Audit event structureCopy Anchor Link

The two stores have different schemas. A capability call produces a row in each.

Postgres security.security_eventsCopy Anchor Link

{
  "id": "uuid",
  "occurred_at": "2026-06-07T12:34:56.789Z",
  "event_type": "capability.invoke_denied",
  "actor_user_id": "uuid",
  "org_id": "uuid",
  "workspace_id": "uuid",
  "capability": "change_member_role",
  "outcome": "deny",
  "ip": "192.0.2.1",
  "user_agent": "Mozilla/5.0 …",
  "request_id": "req_uuid"
}

ClickHouse audit_eventsCopy Anchor Link

{
  "occurred_at": "2026-06-07T12:34:56.789Z",
  "event_id": "uuid",
  "org_id": "uuid",
  "workspace_id": "uuid",
  "capability": "change_member_role",
  "scope_kind": "workspace",
  "scope_id": "uuid",
  "acting_principal_id": "uuid",
  "acting_principal_kind": "human",
  "human_principal_id": "uuid",
  "outcome": "deny",
  "decision_reason": "org.enforced_deny",
  "payload_hash": "sha256:…",
  "chain_hash": "sha256:…",
  "ip": "192.0.2.1",
  "ua": "Mozilla/5.0 …",
  "request_id": "uuid",
  "trace_jsonb": "{\"matched_rule\":\"org.enforced_deny\",\"policy_id\":\"uuid\"}"
}

Every capability.invoke_denied ClickHouse row has a trace_jsonb field. It holds the resolver's step log, so you can answer "why was this denied?" from the stored decision rather than reconstructing it from logs. Auth and billing events are written only to Postgres and produce no ClickHouse audit_events row.