opschain secret audit

Included from Basic tier

opschain secret audit [--mount <kv-mount>] [--summary]

Walks a secret vault and classifies every stored field value by its encryption state — read-only, and it never prints a secret value. Because it exits non-zero when any value is unrecoverable, it doubles as a health check: run it after rotating or restoring the transportable key, before a migration, or whenever changes start failing to resolve secrets.

Unlike its siblings under opschain secret, audit (and migrate) operate on the secret backend a server would use, not the per-user CLI store — the backend the vault: block of $OPSCHAIN_HOME/server/config.yaml selects. Note the RUNNING server's backend is a SecretsProvider connection since (the config.yaml provider keys are retired and refuse server start once seeded); this host-local, offline tool keeps reading the file and the OPSCHAIN_VAULT_* environment directly, so point it at the vault with those variables (or a temporary vault: block it alone reads) when auditing a provider-backed estate.

Backend selection

vault.type in config.yaml selects the backend: age (also accepted as file or local) is the local age file store; openbao and hashicorp are a KV v1 vault (they share one client). With no vault.type, a configured address + token infers a vault backend, the age file store otherwise. Each vault: key overrides the same-named OPSCHAIN_VAULT_* environment variable (address, token, mount_path, client_options) — the same precedence opschain server start applies.

Each value is probed with the configured transportable key (vault.transportable_key or vault.transportable_key_path in config.yaml, or the OPSCHAIN_TRANSPORTABLE_KEY_PATH environment variable) and classified:

Class	Meaning
plaintext	Stored in the clear.
{AES}	Legacy universal key — ships with the product; weakly protected.
{AES2}/U	Universal key — ships with the product; weakly protected.
{AES2}/T	Customer transportable key — decryptable, or UNRECOVERABLE when the configured key cannot decrypt it.

Flags

Flag	Meaning
--mount <kv-mount>	KV v1 mount to audit (openbao/hashicorp backends only; default: the configured mount).
--summary	Print the per-class counts only, without listing every field.

The global --no-keychain flag applies when the backend is the age file store (its master key otherwise falls back to the OS keychain — see opschain docs cli/secret).

Output

Without --summary, one line per field — tag, <path>.<field>, and a risk note — then the summary:

opschain secret audit --summary
audit of https://bao.example.com:8200 (mount opschain): 12 field(s) across 5 node(s)
  plaintext:               2  (stored in the clear)
  {AES}:                   0  (legacy universal key — ships with the product; weakly protected)
  {AES2}/U:                3  (universal key — ships with the product; weakly protected)
  {AES2}/T decryptable:    7
  {AES2}/T UNRECOVERABLE:  0  (no usable transportable key — restore the key or re-create these secrets)

Exit codes

Code	Meaning
0	Audited; every {AES2}/T value decrypts.
1	The audit failed, or at least one {AES2}/T value is unrecoverable.
2	Usage error.

Named errors

• <n> {AES2}/T value(s) cannot be decrypted with the configured transportable key — restore the key, or re-create those secrets with new values — the unrecoverable outcome (exit 1).
• the <type> secret backend needs an address and a token (config.yaml vault: address/token, or OPSCHAIN_VAULT_ADDRESS/OPSCHAIN_VAULT_TOKEN) — an openbao/hashicorp backend with no reachable configuration.
• unknown vault.type "<type>" (accepted: age, openbao, hashicorp).
• --mount applies to the openbao/hashicorp backend; the age file store has no mounts (exit 2).

Related settings

• config.yaml vault: block — type, address, token, mount_path, client_options, transportable_key, transportable_key_path.
• OPSCHAIN_VAULT_ADDRESS, OPSCHAIN_VAULT_TOKEN, OPSCHAIN_VAULT_MOUNT_PATH, OPSCHAIN_VAULT_CLIENT_OPTIONS — the environment fallbacks.
• OPSCHAIN_TRANSPORTABLE_KEY_PATH — an alternative transportable-key source.

See also

• opschain docs cli/secret-migrate — act on what the audit found.
• opschain learn 3.5 — secrets and vault, guided.