Audit events

Revaulter records security-relevant actions to a durable, append-only v2_audit_events table. This is separate from the application log (written to stdout): ordinary log messages still go to the log stream, while audit rows are the long-term history of who did what.

Each user can see their own events in the web UI, under Settings → Audit log. There’s no admin UI or REST API for reading the events of all users yet, so operators must query the table directly with SQL, or stream the events to a SIEM.

What gets recorded#

Each row records one action, such as a confirmed request, a regenerated request key, or a deleted passkey. Some failed and denied attempts are recorded too, such as failed logins.

Events are written through one of two paths:

• In the same transaction: for security-critical changes, the audit row is written in the same transaction as the change. If writing the audit row fails, the change is rolled back too. This guarantees that a “request confirmed” row exists if and only if the request was actually confirmed.
• Best-effort: for events that are only observational in nature (logouts, expired requests, login failures), the audit row is written separately. If writing it fails, Revaulter logs a warning, and the user’s action isn’t affected.

Schema#

Event types#

Event types are named <area>.<verb>, with both parts in snake_case. Revaulter records only the event types listed here, and rejects any other value.

Auth#

Requests#

The note field is included only when the request had a note. The jwt* fields are included only on request.create, when the request was authenticated with an OIDC token: they hold the token’s verified iss, sub, and jti claims, so the audit log shows which workload sent the request.

Signing keys#

What is never recorded#

Audit events never contain sensitive material. Specifically, audit rows don’t store:

• Request keys (rvk_…) or session tokens
• Wrapped primary keys, wrapped anchor keys, or any encrypted blob
• Raw WebAuthn credential JSON, attestation payloads, or signature bytes
• Encrypted request/response envelopes
• Webhook URLs or shared secrets
• Allowed-IP lists in full (only their count)
• ML-DSA / ES384 signatures of any kind

Retention#

Rows older than 30 days are deleted automatically by a background task that runs when Revaulter starts, and then every 24 hours.

When streaming to a SIEM is enabled, rows that haven’t been sent yet aren’t deleted, so a collector outage doesn’t lose events. Rows are kept for at most 90 days, after which they’re deleted even if they weren’t delivered. The revaulter_audit_stream_lag_seconds metric shows a backlog long before that.

Sample queries#

These queries use SQLite syntax. For Postgres, only the date calculations differ.

All events for a user in the last 24 hours

SELECT created_at, event_type, outcome, client_ip, metadata
FROM v2_audit_events
WHERE actor_user_id = 'user-123'
  AND created_at >= strftime('%s', 'now', '-1 day')
ORDER BY created_at DESC;

All denied or failed actions in the last week

SELECT created_at, event_type, actor_user_id, client_ip
FROM v2_audit_events
WHERE outcome IN ('failure', 'denied')
  AND created_at >= strftime('%s', 'now', '-7 days')
ORDER BY created_at DESC;

All signing key changes

SELECT created_at, event_type, actor_user_id, signing_key_id, metadata
FROM v2_audit_events
WHERE event_type LIKE 'signing_key.%'
ORDER BY created_at DESC;

Background expiries during a window

SELECT created_at, request_state, metadata
FROM v2_audit_events
WHERE event_type = 'request.expire'
  AND created_at BETWEEN ?1 AND ?2
ORDER BY created_at DESC;

Streaming to a SIEM#

Revaulter can send every audit event to an external HTTP collector as it’s written, such as Splunk HEC, Elastic, Vector, Fluent Bit, Cribl, Panther, or a plain webhook receiver. To enable this, set auditStreamUrl.

auditStreamUrl: "https://splunk.internal:8088/services/collector/raw"
auditStreamFormat: "ndjson"          # ndjson (default) | json
auditStreamKey: "Splunk 00000000-0000-0000-0000-000000000000"
auditStreamAuthHeader: "Authorization"
auditStreamBatchSize: 100            # 1–1000
auditStreamFlushInterval: "10s"      # 1s–5m
auditStreamEventTypes: []            # empty = all, "request.*" wildcards allowed

Events can be delivered more than once, so your collector must deduplicate on the event id. The id is a UUIDv7 that stays the same when an event is sent again. A collector that doesn’t deduplicate will count some events twice.

Only events created after you enable streaming are sent. Earlier rows are never sent.

Wire formats#

Both ndjson and json formats carry the same event object:

{
  "schemaVersion": 1,
  "source": "revaulter",
  "instanceId": "7Yk2…",
  "id": "019974c1-1f3a-7c4e-9b2d-6f1e8a4c0d55",
  "time": "2026-09-15T20:11:03Z",
  "eventType": "request.confirm",
  "outcome": "success",
  "authMethod": "session",
  "actorUserId": "u_9f2c…",
  "targetUserId": "u_9f2c…",
  "httpRequestId": "01JC…",
  "clientIp": "203.0.113.41",
  "userAgent": "Mozilla/5.0 …",
  "attributes": { "requestState": "3f7a…" },
  "metadata": { "operation": "decrypt", "algorithm": "A256GCM", "keyLabel": "prod-backup" }
}

• Nullable columns are omitted, never emitted as null
• attributes holds the correlation columns (requestState, signingKeyId, credentialId), which are set only on the event types they apply to. Entries with no value are dropped, and the object is omitted when none apply
• metadata is the event’s own data. It’s always present (as an empty object {} when there’s nothing to include) and it’s never merged with attributes
• time is RFC 3339 in UTC, with second precision. Sort and deduplicate on id, not on time
• schemaVersion, source, and instanceId are repeated on every event, so each NDJSON line still identifies its source after a collector splits the batch
• The internal shipping key (seq / xact_id) is never emitted

ndjson (the default) sends Content-Type: application/x-ndjson, with one compact object per line, and a newline after each line, including the last one. Splunk HEC /raw, Elastic, Vector, Loki, and Fluent Bit all accept it natively.

json sends Content-Type: application/json with a single envelope, for endpoints that want one well-formed JSON document per request:

{
  "schemaVersion": 1,
  "source": "revaulter",
  "instanceId": "7Yk2…",
  "sentAt": "2026-09-15T20:11:08Z",
  "count": 2,
  "events": []
}

events holds one event object per entry, in the same shape as an NDJSON line.

Request headers#

auditStreamKey is sent exactly as written, like webhookKey, so include the scheme yourself: Splunk abc123, Bearer …, and ApiKey … all work. Set auditStreamAuthHeader when your collector expects the credential in a different header.

Private addresses#

auditStreamUrl can point at a private or internal address, as most collectors are. Redirects are never followed, so a redirect can’t be used to reach other internal addresses, such as a cloud metadata endpoint.

Filtering#

auditStreamEventTypes limits which events are sent. Each entry is either an exact event type (request.confirm) or an area wildcard (request.*). An empty list sends everything. If an entry doesn’t match any event type Revaulter records, Revaulter fails to start, instead of silently sending nothing.

Events that the filter excludes count as processed, so a narrow filter doesn’t stop old rows from being deleted.

Metrics#

Alert on revaulter_audit_stream_lag_seconds: it catches collector outages, misconfiguration, and a stalled stream in a single metric.