Manual for Bouncer 0.5.7. Chapters state version and distribution limits. Source cdd3b59, site build 20 November 2026. Your server or app may run an earlier version.
What's covered and what isn't
This page lists the threats Bouncer's design addresses, with the limits of each. It's based on the project's threat model for requests, approvals and grants, and on the server source. That threat model hasn't been reviewed by anyone outside the project yet.
Covered
| Threat | How Bouncer handles it |
|---|---|
| A requester approves its own request | A requester key can't approve. Only a device's signature does |
| A replayed approval | Each approval signs a single-use challenge, valid for one request and revision. A second use is refused |
| An approval moved to another request | The signature covers a hash of the resource, requester, duration, reason and policy revision. Anything different is refused |
| An approval made on one Bouncer used on another | The instance ID is inside every signature |
| Approval by someone who isn't an approver | The server checks the approver list from the config on every decision |
| Access outliving its approval | Every check compares the server's clock with the grant's end. Tokens never outlive the grant |
| A restart bringing access back | Expiry and revocation are stored and computed, so they survive restarts. Used challenges and pairing codes stay used |
| A slow or failing revoke | Bouncer records the grant's end first, so no new tokens are issued. Revokes run even if the caller disconnects, and failed ones are retried |
| Policy loosened quietly | A reload that loosens policy is logged and announced. Standing grants are suspended when their policy changes |
| Secrets in push notifications | Pushes carry only an event ID. Details are fetched from your server |
| Secret values in Bouncer's database | PostgreSQL holds access records and hashes of requester keys, device tokens and pairing codes, not stored secret values. The server handles plaintext when a device views or saves a secret, and when someone creates a personal credential; OpenBao holds the values |
| Guessing pairing codes | Codes are 60 random bits, single-use, short-lived, and limited to 10 wrong tries per address per 10 minutes |
| A stolen requester key used from elsewhere | The key can ask and use its active grants. A human requester's key can also receive access covered by a personal credential's Always approved mode. Replace the key and review its grants (Approvals and access duration) |
| A lost phone | Revoke the device; it can't approve or see anything afterwards (Recovery) |
| Bouncer itself compromised | The role kit limits which paths the server can reach, but the server can still issue resource tokens, read viewing paths, and read and write personal credential namespaces. The role kit's emergency stop works independently of Bouncer. See "Bouncer chooses the resource" below |
Not covered, or only partly
| Threat | Why |
|---|---|
| A value already read | Can't be recalled. Rotate it (Copied secrets) |
| An unlocked, paired phone in the wrong hands | With a standard Android key, the phone being unlocked is the only check. Biometric keys and require_hardware_uv narrow this |
| A modified app claiming a stronger key | Android attestation can prove the key's hardware and biometric requirements only when the device declares Android. A modified app can declare iPhone or Mac and avoid attestation even under android_attestation: required (issue #282). From 0.5.7, the server checks a TPM attestation at enrolment when Windows supplies one, but no real PC has passed that check yet, and keys enrolled before it stay unchecked (Device keys) |
| Bouncer chooses the resource | OpenBao lets Bouncer issue a token for any configured resource; it doesn't know whether a person approved. A bug or compromise in Bouncer could issue tokens for every listed resource, a few minutes at a time, while it holds a login |
| Issued tokens are bearer tokens | Anyone holding a token can use it until it expires (minutes) |
| Which machine is asking | The host name and client name a requester sends are labelled "reported" because they aren't verified. Any holder of the key can ask |
| The server's own machine | Whoever has a shell there is the admin, and can loosen policy (which is logged). Whoever can write to PostgreSQL can forge grants |
| A restore bringing back revoked access | A database restore revives revoked devices, disabled requesters and replaced keys. The restore procedure puts them back, but needs a record of what changed |
| Source-host binding | A grant can't yet be tied to one requesting machine |
| Revocation timing under load | Revokes are designed to complete within seconds, but there's no timing test against a real OpenBao under load |
Out of scope
- The security of OpenBao itself, the host operating systems, and the phones and PCs.
- What a requester does with a secret once it has it.
- Network-level attacks on your private network or VPN.
How this was checked
From the project's threat model for requests, approvals and grants (in the repository's docs/security folder), which maps each covered threat to an automated test, the role kit's "Remaining risk" section, and the server source.