Governance and audit in Relata DB 3.0

Relata DB 3.0
This page describes Relata DB 3.0, the current release. Paths use the new /v1 prefix; see the route restructure.

Governance in the query path

Policy is enforced where data is read and written, for every request on every supported interface (HTTP, GraphQL, MCP, A2A, search):

  • Type-level grants: RELATA_ACL_GRANT="TypeA:read+write,TypeB:read" grants on the named types. A bare type name is read-only.
  • Column masking: RELATA_CELL_POLICIES="Person.ssn=mask,BankAccount.iban=tokenize" hides or tokenizes columns at egress. tokenize needs RELATA_TOKENIZE_KEY.
  • Purposes: with RELATA_PURPOSE_MODE=strict and RELATA_PURPOSES, requests that do not declare a registered purpose are rejected.
  • Deny wins: any matching deny overrides all allows.

See Access control and permissions for walkthroughs and 403 troubleshooting. The retired protocol doors no longer have their own principals; see Migrating from retired doors.

Retrieval answers can additionally be made checkable: Retrieval evidence records the exact source versions cited and re-verifies them under the caller's current authorization.

The local audit log

The open edition keeps a minimal, local, append-only audit log. It is evidence of activity, not tamper-evident proof. GET /v1/audit/proof and POST /v1/audit/export are Enterprise routes and answer 501 enterprise-audit-chain-required. Read the log through GET /v1/audit/log and GET /v1/audit/count.

Application logs are separate: they go to stderr (RELATA_LOG_LEVEL, default warn) and Relata does not store them.

Layout and permissions

{RELATA_AUDIT_DIR}/                 default {data_dir}/audit, mode 0700
  audit-local.jsonl                 live segment, one JSON object per line, mode 0600
  audit-local.jsonl.<seq>.gz        sealed, gzipped segments
  audit-archive.manifest.json       what the archive has acknowledged (digest, size, time)
  archive/                          default archive destination

Startup creates the directory 0700, tightens a wider mode, and refuses to start if it cannot make it private (unless RELATA_AUDIT_PERMISSIONS_RELAXED=true). The directory must be owned by the account the server runs as. Put RELATA_AUDIT_DIR on its own volume so a full audit volume cannot take the WAL down.

Record fields

Each record carries executed_at (UTC nanoseconds), principal and tenant_id (PII redacted unless RELATA_AUDIT_REDACT_PII=false), purpose, query, decision (Allow, Deny or AuthFailure), the rejection reason, row_count, cost_units, latency_ms, request_id, trace_id, a break_glass marker, and source_ip and user_agent of the originating request. Credentials are scrubbed from every free-text field before the record exists.

Event classes

RELATA_AUDIT_EVENTS selects what is recorded. Default: authn,authz,admin,write,read-denied. Allowed reads (read) are off by default; RELATA_AUDIT_READ_SAMPLE_RATIO (for example 0.05) records a fraction of them per request id. Durable mutation audit is never filtered.

Bounded growth

ControlDefaultVariable
Rotation100 MB or dailyRELATA_AUDIT_SEGMENT_MAX_MB, RELATA_AUDIT_SEGMENT_MAX_AGE
gzip of sealed segmentsonRELATA_AUDIT_SEGMENT_COMPRESS_ENABLED
Retention365 daysRELATA_AUDIT_SEGMENT_RETENTION_DAYS (0 keeps forever)
Directory size cap10 GBRELATA_AUDIT_DIR_MAX_MB (0 disables)
Free-space warning and readiness1024 MB and 256 MBRELATA_AUDIT_MIN_FREE_MB, RELATA_AUDIT_MIN_FREE_CRITICAL_MB

Retention and the cap delete only segments the archive has acknowledged. Below the critical free-space threshold /health/ready answers 503 audit-sink-unavailable, and with RELATA_AUDIT_FAIL_CLOSED=true audited requests are refused too. Set RELATA_AUDIT_RETENTION_HOLD=true while an investigation, legal request or erasure proof needs the history; retention then deletes nothing.

Sizing: a record is typically 300 to 700 bytes and gzip shrinks sealed segments about 5 to 10 times. At 100 audited events per second expect about 3 GB per day live, or about 0.5 GB per day sealed. Reads are the usual cause of volume.

Archive and forwarding

Local disk is the only synchronous write. Sealed segments are shipped asynchronously: gzip, upload, read back, compare SHA-256, then record in the manifest. A local copy is removed only after acknowledgement plus RELATA_AUDIT_ARCHIVE_GRACE_SECS (default one hour). RELATA_AUDIT_ARCHIVE_URL selects a directory, s3://, gcs:// or azure:// destination. To restore from the archive, fetch segments, check each file's SHA-256 against the manifest, and read them with zcat audit-local.jsonl.*.gz | jq ..

To forward to a collector, tail {RELATA_AUDIT_DIR}/audit-local.jsonl with rotation handling and by inode (Vector, Fluent Bit and Grafana Alloy all work), or set RELATA_AUDIT_OTLP_ENDPOINT for best-effort OTLP/HTTP log export of security events. The local log stays the source of truth.

Not in a backup

The audit log is not part of a backup artefact. Archive sealed segments separately (Backup and restore).

What Enterprise adds

Hash-chained, tamper-evident audit with inclusion proofs, signing, SIEM export and compliance reports, managed users and roles, and KMS-backed keys belong to Relata Enterprise DB. See Editions.