Skip to content
VeraFrame Docs

Audit trail

The audit trail is VeraFrame’s structured record of what happened: what was generated, who reviewed it, what decisions were made, and why. It is the artifact that lets you answer, months or years later, “who approved this specific AI output, on what basis, and against what source material?”

Audit trail is enabled on tenants with the audit_trail feature — part of the Compliance Edition tier and commonly used together with workflow-enabled compliance_ready and high_risk_ready compliance profiles.

What gets recorded

An audit event is written for each of the following actions:

  • validation_created — a new validation was generated. Includes mode, user, request summary, source groups, confidence, and issue count.
  • review_required — a review case was created and entered pending_review because tenant workflow settings required it.
  • approved / rejected / edited — a reviewer acted on the validation. Includes actor ID, role, timestamp, and required note.
  • review_handed_off — the validation was handed to an external review system, with external reference.
  • external_review_approved / external_review_rejected — the external system decision was recorded.

Each event is a structured JSON record with a stable schema.

Where it is stored

Audit events are written to DynamoDB in the same region as the tenant’s data (EU). Each record uses the tenant’s customer ID as the partition key, and a sortable timestamp + event ID as the sort key, so events can be retrieved in strict chronological order per tenant.

The records are append-only: VeraFrame’s code writes events but never overwrites or deletes individual events. The only way an event leaves the audit trail is through TTL-based retention (see below).

Retention

Every audit event is written with a time-to-live (TTL). DynamoDB automatically removes records after the TTL expires.

  • Default retention: 365 days for audit events.
  • Configurable per tenant via the audit_retention_days compliance setting.
  • The current implementation accepts tenant-specific retention values and uses the configured number of days.

Validation history (the request + response + trust report itself) has its own shorter retention — default 90 days — via HISTORY_TTL_DAYS. Audit events outlive validation history so that the decision trail remains even after the underlying data has been purged.

Export

For tenants with audit_trail enabled there is one default pull-based audit pipe for enterprise integrations:

  • Business and audit events come from VeraFrame’s audit export API.
  • Technical runtime logs stay in the cloud platform’s native logging service (CloudWatch on AWS, Azure Monitor / Application Insights on Azure).

For audit events themselves there are two export formats and matching UI actions:

JSON export

A structured export of all events in the selected range. Use this for ingestion into internal audit systems or for producing evidence bundles.

CSV export

A flattened export — one row per event, key fields as columns. Use this for spreadsheet-based review or for finance / compliance teams who prefer tabular data.

Both exports are accessible from the Compliance tab in the Admin dashboard, or programmatically via:

POST /api/v1/audit/export
{
  "date_from": "2026-01-01",
  "date_to":   "2026-03-31",
  "format": "json"
}

The default export profile is enterprise_v1. It returns a normalized and sanitized event structure intended for customer-operated reporting, compliance review, and downstream ingestion:

  • stable schema_version
  • one event object per audit action
  • pseudonymized actor_ref instead of the raw actor identifier
  • payload_summary instead of unrestricted free-text payload fields

If you need the earlier raw event structure for backwards compatibility, request:

POST /api/v1/audit/export
{
  "date_from": "2026-01-01",
  "date_to":   "2026-03-31",
  "format": "json",
  "profile": "raw"
}

This split is intentional: the audit export API is the default system-of-record for business and review events, while low-level exception traces, timing logs, and infrastructure diagnostics belong in your cloud logging stack.

What the audit trail does not record

  • User credentials or payment data. Authentication events record user IDs, not passwords; billing events reference Stripe IDs, not card numbers.
  • Raw source material. The audit trail records which sources a validation used (by file reference and hash), but not the full content of the sources. Source content lives in your tenant’s S3 bucket.
  • Third-party system internal state. For handoffs, VeraFrame records the external reference but does not fetch the external system’s own logs.
  • Raw technical runtime logs. Lambda / Function execution traces and infrastructure logs are not duplicated into the audit export.

Typical use cases

  • Quarterly compliance review — export the quarter, sample validations, verify reviewer decisions match organizational policy.
  • Incident response — a customer complains about an output; retrieve the specific validation, trust report, and reviewer note in seconds.
  • Supplier audits — when your customer audits your AI governance, hand over the audit export for the relevant period.
  • Regulatory inquiry — produce decision traces on specific outputs upon request.