Skip to content

Audit Presentation Model v1

Purpose

Audit rows are immutable evidence records. The raw fields in audit_logs remain the source of truth, but operator and v3 evidence surfaces need a stable display model that does not force every UI to understand every raw action string.

The API therefore returns an additive presentation object on audit read models. This object is backend-owned and safe for generic UI rendering.

Contract Shape

Each audit row keeps the existing raw fields:

  • actor_user_id
  • actor_service_account_id
  • actor_role
  • action
  • target_type
  • target_id
  • result
  • correlation_id
  • occurred_at
  • metadata

Each row may also include:

  • presentation.actor_label
  • presentation.target_label
  • presentation.target_type_label
  • presentation.action_label
  • presentation.action_category
  • presentation.action_family
  • presentation.summary
  • presentation.result_label
  • presentation.severity
  • presentation.safe_details
  • presentation.debug_refs

The presentation object is additive. Consumers must not treat it as a replacement for immutable audit evidence.

Ownership

Backend owns the action registry and classification. UI owns layout only.

When adding a privileged action, the owning backend domain should add or confirm the presentation rule in cmd/api/audit_presentation.go:

  • category, such as Access, Finance, Fleet, Operations, or Platform
  • family, such as Credentials, Platform roles, or Allocation lifecycle
  • operator action label
  • target type label
  • default success and failure severity
  • safe metadata keys that may appear in presentation.safe_details

Unknown actions still render with fallback labels, but that fallback is for survivability only. Domain-owned actions should be registered explicitly when they become part of an operator workflow.

Safe Details

presentation.safe_details is allowlisted and intentionally smaller than raw metadata. It is for scan-level display and filtering, not forensic completeness.

Do not add raw tokens, raw credentials, SSH key material, full request/response payloads, payment instrument data, or end-user PII to safe details.

Debug Pivots

presentation.debug_refs carries stable pivots for operator investigation:

  • correlation_id
  • optional trace_id
  • optional request_id
  • optional actor_ref
  • optional target_ref

These values let Evidence pages pivot into logs, traces, object history, or target-specific detail pages without parsing raw metadata in the browser.