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

Audit: what is logged and where

There are three records, each answering a different question.

RecordWhere it isWhat it answers
Bouncer's approval logBouncer's PostgreSQL databaseWho asked for what, who decided, which grants ended, and what changed in the config
The server's logThe container's output (docker compose logs bouncer)What the server did and why it failed, for troubleshooting
OpenBao's audit logOpenBao's audit device, if you turned one onEvery 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).

FieldWhat it identifies
grant_id, request_id, requester, resourceThe grant and its recorded context
atOn 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_idThe particular token or wrapped read
token_audit.roleThe 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.accessorThe 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_outcomenull 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:

  1. Export the approval log with a bouncer-admin from the same version as the server (See it and export it). Find the grant and its token_issued entry. Match later backend_revoke entries by grant_id and token_audit.issuance_id.

  2. 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.hash
    

    Replace file with 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.

  3. Look for that hash in the creation-response field from the table below, in auth.accessor on later uses of the token, and in request.data.accessor on auth/token/revoke-accessor. On the creation record itself, the top-level auth.accessor belongs 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 outExported accessorOpenBao creation-response field to compare
Direct tokenThe issued token's accessorresponse.auth.accessor
Wrapped tokenThe inner token's accessorresponse.wrap_info.wrapped_accessor
Wrapped personal-credential readThe wrapping token's accessor; Bouncer can revoke it while unusedresponse.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:

AreaKinds
Requestsrequest_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
Grantsgrant_expired, grant_revoked, grant_suspended, review_due, review_confirmed
Devicesdevice_paired, device_revoked
Requestersrequester_created, requester_key_issued, requester_disabled
Admin and configkill_switch, config_loaded, policy_loosened
Valuessecret_written, secret_write_failed, secret_viewed, secret_view_refused
Downstream credentialsdownstream_rotation_due, downstream_rotated
Personal credentialssharing_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_:

KindWhat the device said
reported_screenshotA screenshot was taken
reported_capture_started, reported_capture_stoppedThe 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_copyThe 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_failedWindows 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:

PlatformScreenshotRecording or mirroringCopy
Android 14 and laterReportedReported on Android 15 and laterReported
Android 9 to 13Not detectedNot detectedReported
iPhoneReportedReportedReported
WindowsNot detectedNot detectedReported

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:

FieldMeaning
event_idAn ID the app made for the event. The same event sent twice is recorded once
observed_atWhen the device saw it. The entry's own at is when the server received it
screenstored_value (a saved secret was showing; the entry names the resource) or draft (a form; no resource)
protectionblocked: 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_idThe 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.

OptionMeaning
--since, --untilA 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.

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