ENABLE AND QUERY VAULT READ AUDITS

This guide shows you how to enable vault read-access auditing and query the resulting audit trail.

Enable auditing on a new vault

Pass --audit-reads when creating the vault:

$ swamp vault create local_encryption my-secrets --audit-reads

INF vault·create Created vault: "my-secrets" ("Local Encryption")

The vault configuration will include auditReads: true:

id: 9fb93509-4e26-4278-9d48-49aeb19af35a
name: my-secrets
type: local_encryption
config:
  auto_generate: true
  base_dir: /path/to/repo
createdAt: "2026-07-13T20:53:54.367Z"
auditReads: true

Enable auditing on an existing vault

Open the vault configuration file and add auditReads: true:

$ swamp vault edit my-secrets

Add the field at the top level of the YAML:

auditReads: true

Reads from this vault will be recorded from this point forward.

Query the audit trail

Use swamp vault audit-trail to see recorded reads:

$ swamp vault audit-trail

INF vault·audit-trail 2 vault read(s):
INF vault·audit-trail   "2026-07-13T20:54:21.586Z"  "my-secrets" ("local_encryption")/"api-key"  by "cli:vault-read-secret"
INF vault·audit-trail   "2026-07-13T20:55:31.276Z"  "my-secrets" ("local_encryption")/"api-key"  by "expression:vault-resolve"

Filter by vault, key, or time range

To narrow results to a specific vault and key:

$ swamp vault audit-trail --vault my-secrets --key api-key

To query a specific time window:

$ swamp vault audit-trail --since 2026-07-01 --until 2026-07-13

To limit the number of entries returned:

$ swamp vault audit-trail --limit 10

Refer to the vaults reference for the full list of options and the audit entry format.

For background on how vault read-access auditing relates to the command-level audit system, see The Audit System.