Audit: what is logged and where
There are three records, each answering a different question.
| Record | Where it is | What it answers |
|---|---|---|
| Bouncer's approval log | Bouncer's PostgreSQL database | Who asked for what, who decided, which grants ended, and what changed in the config |
| The server's log | The container's output (docker compose logs bouncer) | What the server did and why it failed, for troubleshooting |
| OpenBao's audit log | OpenBao's audit device, if you turned one on | Every request made to OpenBao, by Bouncer and by requesters reading secrets |
An accessor identifies an OpenBao token without letting you read secrets with it. An authorised OpenBao operator can use it to look up or revoke that token. Keep full exports private. Bouncer's normal server log shows only the first six characters, which are not a unique token ID.
On 0.5.6 and earlier, bouncer-admin log export includes request and
grant IDs, but no token-issuance entries or accessors. To match an approved
grant to successful secret reads, match its exported grant_id with
auth.metadata.bouncer_grant in OpenBao's audit log. Those read records also
carry auth.metadata.bouncer_issuance, which matches the issuance ID in the
server's log.
For those versions, match a revoke by taking that successful read record's
auth.accessor HMAC and finding the same value in the revoke record's
request.data.accessor. Both records must come from the same OpenBao audit
device. If the token was revoked without ever being read, or its read record
is missing, this link is unavailable.
Match token records to OpenBao
From 0.5.7, the admin export
(bouncer-admin log export) also includes
token_issued and backend_revoke. They are never sent to the device log,
event stream or push notifications. The export carries no OpenBao token,
wrapping token or secret value.
This order is checked against Bouncer's source and an earlier OpenBao test, not yet run end to end with the new export (How this was checked).
| Field | What it identifies |
|---|---|
grant_id, request_id, requester, resource | The grant and its recorded context |
at | On token_issued, when Bouncer sent the issue request; on backend_revoke, when the attempt started. Whole seconds; OpenBao's event is at the same time or shortly after |
token_audit.issuance_id | The particular token or wrapped read |
token_audit.role | The token role at issuance, even if the configuration later changes. It is null for a wrapped personal-credential read, which uses no token role, and for older issuances without a recorded role |
token_audit.accessor | The full accessor, for an exact audit-log match. Omitted when no usable accessor is available: token_audit.accessor_status is withheld if a 2xx reply omitted it or gave an unusable value, or absent if no usable issue reply arrived |
token_audit.revoke_outcome | null on token_issued; on backend_revoke, OpenBao's result: revoke_confirmed, already_expired (OpenBao found no such token), revoke_failed or unknown |
If an audit device logs accessors in plain text (hmac_accessor set to false,
or log_raw on), compare the exported accessor directly. For OpenBao's
normal HMAC-protected audit output, use the following order:
-
Export the approval log with a
bouncer-adminfrom the same version as the server (See it and export it). Find the grant and itstoken_issuedentry. Match laterbackend_revokeentries bygrant_idandtoken_audit.issuance_id. -
Choose the OpenBao audit device whose log you are investigating. An authorised OpenBao operator hashes the full accessor with that device's salt:
ACCESSOR='<token_audit.accessor from the export>' bao write -format=json sys/audit-hash/file input="$ACCESSOR" | jq -r .data.hashReplace
filewith the device's path. Each audit device has its own salt, so repeat this for each device's log. The server log's six-character prefix cannot produce the same hash. -
Look for that hash in the creation-response field from the table below, in
auth.accessoron later uses of the token, and inrequest.data.accessoronauth/token/revoke-accessor. On the creation record itself, the top-levelauth.accessorbelongs to Bouncer's own server token, not the issued one. Bouncer's grant and issuance metadata give another check on successful secret reads.
The accessor depends on what Bouncer released:
| What Bouncer handed out | Exported accessor | OpenBao creation-response field to compare |
|---|---|---|
| Direct token | The issued token's accessor | response.auth.accessor |
| Wrapped token | The inner token's accessor | response.wrap_info.wrapped_accessor |
| Wrapped personal-credential read | The wrapping token's accessor; Bouncer can revoke it while unused | response.wrap_info.accessor |
A wrapped personal-credential read releases the saved value on unwrap. It does not create a new token governing that value's later use. Revoking its unused wrapping token cannot recall a value already unwrapped.
What a missing or repeated record means
token_issued records an observed or possible issuance. Its optional
token_audit.issuance_status marks a refused credential or an uncertain
issuance; a normal release omits that field. None of these records proves
that the caller received or used the credential. backend_revoke records a
backend attempt, not the grant cutoff or the end of a downstream session.
During an OpenBao outage, retries can create repeated revoke_failed
entries. A call that never reached OpenBao has no matching OpenBao audit
event. Local expiry without a
backend call creates no backend_revoke entry. Records are not added for
tokens issued before the upgrade, so revoking one of those afterwards gives
a backend_revoke with no token_issued and a null role. SSH certificates
have neither record: they are not OpenBao tokens, and their revoke is the
KRL entry.
Normal issuance records and backend revoke records commit with their Bouncer state changes. After an issuance failure, Bouncer saves the failure state and conservative lifetime bound first, then tries to write its audit records. A failed audit write logs a warning and keeps that state and the original error. The OpenBao call happens outside those database transactions. If the process stops or the database fails after OpenBao acts and before Bouncer commits, the export may have no record of that call. A failed backend revoke transaction also loses the saved revoke outcome; the sweeper retries and recovers it. A later retry records a later attempt, not the missing one.
If the requester disconnects during issuance, the connector cleans up the token, but its evidence does not reach the server for an export record. A failed cleanup can leave a token until it expires, as reported in the server log.
Refused wrapped personal-credential reads still have no issuance or export record. This path does not revoke their wrapping token; it is never released and expires at its OpenBao wrapping TTL.
A token the server refuses after recording it also has a token_issued record followed by a backend_revoke: for example, when its kind is wrong, it would outlive the request, or the grant ended while OpenBao was issuing it. The credential is not released, and the revoke outcome still needs checking.
A token issue refused by the connector has a token_issued record marked
token_audit.issuance_status: refused. Its attempted revoke has a matching
backend_revoke, including the outcome and the same checked accessor. The
credential was not released; a failed revoke does not prove that it ended.
When a 2xx issue reply omits the accessor or gives an unusable value, the
token record omits it and uses token_audit.accessor_status: withheld.
A lost or unusable answer uses
absent. Both have token_audit.issuance_status: may_have_been_issued, so
they do not establish that a token exists. Bouncer adds no revoke record
without an actual attempt. For a lost answer, the entry's time is the
original issue attempt, not when the failure was recorded.
Without an accessor, use the issuance ID to investigate OpenBao's creation
request. OpenBao's audit log HMACs Bouncer's metadata there, so submit that
ID to sys/audit-hash on the same audit device and look for the result in
request.data.meta.bouncer_issuance on auth/token/create requests. The
transaction and crash limits above still apply: missing Bouncer evidence
does not prove that OpenBao issued nothing.
These logs do not record a child command's later actions, every use of a copied secret, or whether a downstream session ended.
The approval log
Every entry has a time, a kind, and whichever of these apply: the request, the grant, the requester, the resource, the person, the device, the channel (app or notification), the durations, and a short detail. The kinds, as of 0.5.2, with later additions marked:
| Area | Kinds |
|---|---|
| Requests | request_filed, approved, denied, decision_rejected, request_expired, request_cancelled |
Credential lifecycle (from 0.5.3, where lifecycle is on) | credential_expired, credential_expiry_scheduled, credential_replaced, credential_version_viewed, credential_lifecycle_refused |
| Grants | grant_expired, grant_revoked, grant_suspended, review_due, review_confirmed |
| Devices | device_paired, device_revoked |
| Requesters | requester_created, requester_key_issued, requester_disabled |
| Admin and config | kill_switch, config_loaded, policy_loosened |
| Values | secret_written, secret_write_failed, secret_viewed, secret_view_refused |
| Downstream credentials | downstream_rotation_due, downstream_rotated |
| Personal credentials | sharing_changed, sharing_refused |
| Tokens (admin export only, from 0.5.7) | token_issued, backend_revoke |
| Resource provisioning (from 0.5.7) | resource_provisioning_changed |
| Device reports (from 0.5.2) | reported_screenshot, reported_capture_started, reported_capture_stopped, reported_copy, reported_protection_failed |
decision_rejected records an approval that failed a check (a bad signature, a used challenge, a duration outside policy). It is never counted as a decision.
Device reports
From 0.5.2, the apps tell the server when a screenshot, a screen recording or a copy happens on a screen that shows a secret, or on a form where one is being typed. Each becomes one entry whose kind starts with reported_:
| Kind | What the device said |
|---|---|
reported_screenshot | A screenshot was taken |
reported_capture_started, reported_capture_stopped | The screen started or stopped being recorded or mirrored. If a recording is still running when the screen closes, the app sends the stop then, so the app sends a stop for every start. A stop can still be missing from the log, because a report isn't guaranteed to arrive (see below) |
reported_copy | The person copied a value they had viewed. The server only accepts this within an hour of a view of that value on the same device |
reported_protection_failed | Windows couldn't keep Bouncer's window out of screen capture |
These entries are the device's word. The server can't check them, and every one says so in its detail: "reported by the device; not verified by the server". The person, the device and the entry's time come from the server, never from the device.
A missing entry proves nothing. No platform reports every capture:
| Platform | Screenshot | Recording or mirroring | Copy |
|---|---|---|---|
| Android 14 and later | Reported | Reported on Android 15 and later | Reported |
| Android 9 to 13 | Not detected | Not detected | Reported |
| iPhone | Reported | Reported | Reported |
| Windows | Not detected | Not detected | Reported |
Windows keeps Bouncer's window out of captures but can't tell when someone tries. A camera pointed at the screen is never detected, on any platform. Reports wait in the app's memory until they're sent, so one that hasn't been sent when the app closes is lost.
A report entry has one extra object, report, and no other entry has it:
| Field | Meaning |
|---|---|
event_id | An ID the app made for the event. The same event sent twice is recorded once |
observed_at | When the device saw it. The entry's own at is when the server received it |
screen | stored_value (a saved secret was showing; the entry names the resource) or draft (a form; no resource) |
protection | blocked: the app had asked the system to keep the screen out of captures. not_blocked: the platform can't (iPhone), or Windows refused (a reported_protection_failed entry). allowed_by_setting: the person had turned on Allow screenshots. test_build: an internal test build, which never blocks |
view_id | The secret_viewed entry this report followed, if that device viewed the value in the hour before |
An example, with made-up IDs:
{"id": "log_01…", "at": "2026-11-15T19:53:28Z", "kind": "reported_copy", "resource": {"id": "demo-api-key", "name": "Demo API key", "kind": "stored_api_key", "credential_class": "openbao-token", "static_exposure": true}, "person": {"issuer": "bouncer:local", "subject": "alex", "name": "Alex"}, "device": {"id": "dev_01…", "name": "Alex's phone", "platform": "android"}, "detail": "reported by the device; not verified by the server", "report": {"event_id": "00c3bf7a6af3f058e68c5ba48b119720", "observed_at": "2026-11-15T19:53:28Z", "screen": "stored_value", "protection": "blocked", "view_id": "log_01…"}}
The fields that are null in a real entry are left out here. A report never holds an image, a value, anything typed or what was copied: the server refuses a report with any field it doesn't define.
Each device may send up to 30 reports in 10 minutes. After 100 of a device's report requests are refused in 10 minutes, the server stops accepting more from it for a while. Either way the server answers rate_limited and writes nothing.
There's no setting to turn device reports off. What decides whether they're recorded is the server, not a version number: a server that takes them says so in its health answer, and the apps send them only to a server that does. To check yours:
curl -s http://127.0.0.1:8080/v1/health | jq .instance.device_reports
Expected result: true. If it prints null, this server doesn't take device reports, and the apps send it none.
See it and export it
People see the ordinary approval log in the apps. The token records above are available only through the admin export.
Upgrade a stand-alone export command with the server. The bouncer-admin
inside the server container always matches the server. A separate copy, for
example one run by cron on the host, does not. A 0.5.6 or earlier
bouncer-admin cannot write token_issued, backend_revoke, resource_provisioning_changed or ssh_ca_changed records. It stops at the first one with Can't write an entry as JSON. Everything before that entry has already been written, including earlier entries from the same page. With --cursor-file it does not save the new cursor, so later runs repeat that output and stop at the same entry.
Admins export it:
docker compose exec -T bouncer bouncer-admin log export --since 7d > bouncer-log.jsonl
Expected result: one JSON object per line, oldest first, and a note on the screen such as bouncer-admin: Wrote 37 entries to stdout. To carry on from here: bouncer-admin log export --after 37.
| Option | Meaning |
|---|---|
--since, --until | A time such as 2026-11-01T00:00:00Z, or how long ago, such as 24h or 7d. --until is exclusive |
--after <cursor> | Carry on after an earlier export |
--cursor-file <file> | Read the cursor from the file and save the new one there when done. For a job that ships only what's new each time |
--out <file> | Write to a new file with mode 0600 instead of standard output |
To list only the device reports in an export, filter on the kind with jq:
jq -c 'select(.kind | startswith("reported_"))' bouncer-log.jsonl
Expected result: one JSON object per line, each a device report like the example above, and nothing at all if there were none.
For a short table instead (time, kind, person, device, resource, and whether capture was blocked):
jq -r 'select(.kind | startswith("reported_")) | [.at, .kind, .person.name, .device.name, (.resource.name // "(a form)"), .report.protection] | @tsv' bouncer-log.jsonl
Expected result: one line for each report, with tabs between the columns, such as:
2026-11-15T19:53:28Z reported_copy Alex Alex's phone Demo API key blocked
2026-11-15T19:53:29Z reported_screenshot Alex Alex's phone (a form) blocked
With the compose kit, the container's filesystem is read-only, so --out and --cursor-file only work for a path on a writable volume. The simplest approach is to redirect standard output on the host, as above. The read-only setting in compose.yaml, with no writable /tmp, means --out /tmp/x.jsonl inside the container fails with "Read-only file system". This is checked against source.
Ship it somewhere else
The approval log lives on the server it describes. If the server is lost, so is the log, and after a restore you have nothing to compare against. Ship it off the machine regularly, for example from cron on the host:
cd ~/bouncer/deploy/compose && \
docker compose exec -T bouncer bouncer-admin log export --since 25h | logger -t bouncer-audit
Delivery is at least once: each entry's id is unique, so your log store can drop repeats. Nothing in the kit sets this up for you.
From 0.5.7 the export includes full token accessors.
Send it only to a log store that people without OpenBao rights can't read,
and filter out the token_issued and backend_revoke entries first if that
store is shared.
The server's log
RUST_LOG in .env sets the level (info by default). Useful lines: bouncer-server is up, config reloaded, push sent, and start-up errors. The server never logs a requester key, device token, pairing code, OpenBao token or secret value. Container logs rotate at 10 MB, 5 files.
OpenBao's audit log
With the dedicated OpenBao from deploy/openbao, an audit device is already on; with your own OpenBao, turn one on in its configuration (OpenBao for Bouncer). Everything Bouncer does appears under its AppRole's display name, and each requester's secret read appears under the token Bouncer issued for it. Don't configure OpenBao to keep fields such as secret_id in plain text; the role kit's --verify reports that as drift on its own mount.
How this was checked
The export above and the kinds seen in it came from the fake-data test. The read-only filesystem behaviour is checked against compose.yaml. The full list of kinds comes from the contract schema (contracts/schemas/bouncer.v1.json).
The device report entries were sent to our staging server and read back both ways, in the app's log and in the export. That run used a script standing in for a phone, so it shows how the server records a report. Both jq filters above were run on that export, where they picked out the 7 device reports among its 13 entries, and the health check printed true for that server. Detection itself was checked on an Android 16 emulator. It hasn't been checked on a physical phone, and the iPhone code hasn't run on a device yet.
The token-record fields and the order above, from 0.5.7, were checked against the source and its automated export tests.
Those tests cover matching issuance and revoke IDs, pagination, retries and
exclusion from the device log. The OpenBao steps were run earlier on
OpenBao 2.7.2 for a wrapped token. There, the sys/audit-hash result for its
full accessor matched response.wrap_info.wrapped_accessor, the read's
auth.accessor and the revoke's request.data.accessor. That run took the
accessor from a test setup, not from the export, and did not cover direct
tokens or wrapped personal-credential reads. The whole join, from the new
export to OpenBao's audit log, has not been run end to end.