Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Copied secrets and revocation limits

Most secrets Bouncer guards are static: a password, an API key or a token that stays the same until someone changes it. Bouncer controls who can read a static secret and for how long. It can't control what happens to the value after it has been read.

What a revoke stops, and what it doesn't

When a grant ends, by time or by revoke, Bouncer:

  • stops issuing new OpenBao tokens for it, at once;
  • asks OpenBao to revoke the tokens it already issued. If OpenBao is unavailable, Bouncer reports the unconfirmed revokes and retries until they succeed or the tokens expire. Check the revoke result rather than assuming every token was revoked.

For SSH access, Bouncer adds revoked certificates to its revocation list. Each host must fetch that list before it refuses them. Until a host fetches the new list or the certificate expires, the certificate can still start new logins. In 0.5.6 and earlier, hosts can't fetch a new list while OpenBao is sealed or unreachable. From 0.5.7, Bouncer serves the list from its database during an OpenBao outage, once it has read the CA public key (issue #281; SSH revocation).

It can't:

  • take back a value that was already read. If the requester copied the password into a config file, a log, its memory or (for an AI agent) a conversation, the copy still works;
  • close sessions already open. A database connection or SSH session opened while the grant was active may stay open until that system closes it;
  • revoke a credential at the system that issued it. A cloud API key or a Proxmox token is valid at its own system until someone removes or regenerates it there.

bouncer revoke says this in its output: A secret value that was already read can't be recalled. If it was read, rotate it.

Rotate what may have leaked

Rotating means changing the secret at its source (a new database password, a regenerated API key) and saving the new value in OpenBao. After that, old copies stop working. Rotate when:

  • a grant was approved by mistake, or from a device that was lost;
  • a requester's machine or key may be compromised;
  • an AI agent was given the value and the conversation may be stored somewhere you don't control;
  • someone who could read the secret leaves.

Tracking credentials from other systems

For a resource whose value was issued by another system, add a downstream block to its config (Resources and policy). Bouncer then tracks when a value was released under a grant that has since ended, and marks it due for rotation:

docker compose exec bouncer bouncer-admin downstream list

Rotate each one marked ROTATE yes at its system, update the secret in OpenBao, and record it:

docker compose exec bouncer bouncer-admin downstream rotated example-api-key

Limits of this tracking:

  • Bouncer counts any issued token as a possible read. It can't tell whether the value was actually read.
  • It only knows about grants. A value copied outside Bouncer (an old .env, a backup) isn't tracked.
  • Bouncer never contacts the other system, so it takes your word that you rotated.
  • The kill switch ends every grant, so afterwards every released downstream credential is due.

Ways to limit exposure

  • Prefer short grants. A 15-minute grant gives a smaller window than a week.
  • Use bouncer exec with a command you trust to avoid returning the value directly to a terminal or model. Check the command's output with fake data first (Patterns for workloads).
  • Use SSH host resources for SSH instead of a stored private key. Each use gets a certificate that expires within minutes, so there's nothing long-lived to copy.
  • Keep secrets you'd hate to rotate away from agents.

How this was checked

The revoke output above is from our test run. The downstream tracking is from the server source and the project's docs/security/downstream-credentials.md, which records a real case: a copied static token kept working at its own system after a Bouncer revoke, as this page describes.

This manual covers Bouncer 0.5.7. Built from source commit cdd3b5958d5be0b33e865b1b56b770f6bccffaf7 (workspace version 0.5.7+34).