Audit logging — bRRAIn Docs

What bRRAIn audit logs record, how long they're retained, and how to query them.

Audit logging

Every action on bRRAIn is logged. The audit log is the authoritative record of who did what, when, and how. This page covers what's logged, where to find it, and how it's protected.

What's logged

Every API call, every Console action, every SDK request, every webhook delivery, every authentication attempt, every authorization decision — logged.

Action metadata

For each entry:

  • Timestamp — millisecond precision.
  • Actor — user ID, service-account ID, or system component.
  • Actor context — IP, user-agent, session ID.
  • Verb — the action performed (read, create, update, delete, sign-in, etc.).
  • Resource — what was acted on (record ID, member ID, extension slug, integration ID, etc.).
  • Scope — the zone or project context.
  • Outcome — succeeded, failed, denied (with the policy name on denial).
  • Reason — free-text reason if the actor provided one.

Specific events

Categories include:

  • Authentication — sign-in attempts (success and failure), MFA challenges, SSO redirects, sign-outs, session expirations.
  • Authorization — role checks, policy decisions, scope checks, approval-gate decisions.
  • Vault — record reads, writes, edits, deletes, zone creations, ontology changes.
  • Document Portal — uploads, downloads, shares, deletes.
  • Members — invitations, role changes, removals, suspensions.
  • Marketplace — installs, updates, uninstalls, scope approvals.
  • Integrations — credentials added, edited, removed; OAuth refreshes; test calls.
  • MCP Gateway — outbound and inbound calls (with payload sizes; not bodies by default).
  • Pod lifecycle — provisions, restarts, upgrades, stops.
  • Configuration — settings changes, theme changes, retention changes.
  • Billing — subscription changes, payment events.
  • Security — key rotations, BYOK operations, break-glass actions.
  • Audit-of-audit — audit-log access and exports.

What we don't log

  • Vault record contents.
  • Vault search query terms (we log that a search occurred, not what was searched).
  • Personal data within audit fields (we redact known PII patterns).
  • Webhook payload bodies (only sizes, signatures, and outcomes).

Retention

Default retention is 365 days. Plan-tier minimums:

| Tier | Minimum retention | Maximum | |---|---|---| | Free | 90 days | 90 days | | Team | 365 days | 365 days | | Business | 365 days | 3 years | | Enterprise | 365 days | 7 years | | Sovereign-Cloud | per contract | per contract |

Compliance-tagged organizations get retention forced to the regulatory minimum for tagged event classes (e.g., HIPAA-tagged organizations get 6-year minimum on PHI-affecting events).

Tamper-evidence

Audit log entries are append-only:

  • Each entry is hash-chained to the previous entry.
  • The chain head is signed daily and the signature published to a tamper-evident timeline.
  • Any modification or removal of an entry breaks the chain and is detectable.

We can't change entries; you can't change entries; an attacker can't change entries without it being obvious.

Querying the log

The Console exposes a search UI under Console → Observability (the same page as live telemetry):

  • Search by actor, verb, resource, time range, outcome.
  • Structured filter syntax (actor:usr_123 verb:vault.write).
  • Faceted result view for narrowing.
  • Export selected results as CSV or JSON.

Programmatic access via the audit-log API:

GET /api/orgs/{org_id}/audit?from=&to=&actor=&verb=&limit=
Authorization: Bearer {service-account-token}

Returns paginated entries.

Real-time stream

Subscribe to the audit log as a stream via webhook:

  • Subscribe to audit.high_severity for security-tagged events only.
  • Subscribe to audit.all for the full firehose (high volume; use with care).

Useful for piping into your SIEM (Splunk, Elastic, Sumo Logic, Datadog, custom).

Export for SIEM

For organizations with established SIEM tooling:

  • Daily, weekly, or monthly batch exports as JSON Lines.
  • Configurable export schema (cherry-pick fields, redact others).
  • Delivered to your S3-compatible bucket or via secure file transfer.

Joint access

For incident-response, you can grant our security team time-bounded read access to your audit log. Useful when we're helping you investigate a suspected incident. Granted access is itself audit-logged.

Compliance value

The audit log is the single most important compliance artifact bRRAIn produces. It evidences:

  • Access controls in operation.
  • Encryption keys handled correctly.
  • Approval gates respected.
  • Configuration changes documented.
  • Personnel access controlled.
  • Incident response actions taken.

Most regulatory regimes (HIPAA, SOC 2, GDPR, ISO 27001, PCI DSS, NIST) accept the bRRAIn audit log as primary evidence for the controls it covers.

Where to next