ENABLE AND QUERY THE VAULT AUDIT TRAIL

This guide shows you how to enable vault auditing and query the resulting audit trail. Write operations (put, delete, annotate) are always recorded when an audit repository exists. Read operations (get) require opting in with auditReads.

Enable read 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 read 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. Write operations are already recorded regardless of this setting.

Query the audit trail

Use swamp vault audit-trail to see recorded operations:

$ swamp vault audit-trail

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

Filter by vault, key, action, or time range

To narrow results to a specific vault and key:

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

To see only write operations:

$ swamp vault audit-trail --action put

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 the vault audit trail relates to the command-level audit system, see The Audit System.