The audit catalogue
Bucker records one audit row for every act that changes who may do what, what is configured, what
data leaves or is kept, and what an agent did. This page explains the published catalogue of
those acts, audit-catalogue.json, so a buyer or an auditor can check
what is logged before relying on it, and the audit_search read that an agent or a security
reader uses to query the rows themselves.
What the catalogue lists
One entry per audit action, in alphabetical order. The file has no timestamp: it changes only when the vocabulary changes.
| Field | Meaning |
|---|---|
action |
The literal written to the row's action column, such as token.revoked. |
class |
The accountability ledger's filter: approval, remediation, agent_governance, issue, configuration, data_plane, production_lever or other. other is administration, not a failure state. |
family |
One of nine families (below). |
results |
The result literals the action writes (SUCCESS, DENIED, ...). Empty when the pinned tables record none. |
targetTypes |
The targetType literals its writers name; empty when the row is about no object. |
carriesBeforeAfter |
True when a writer records the target before and after the change (stored-tier scrubbed, at most 4 KB each, else a digest). |
principalKinds |
Which kinds of principal can produce the row: HUMAN, AGENT, SERVICE. |
securityRelevant |
Whether the family is one an investigator reads first. Provisional until the notable flag replaces it. |
status |
live, or planned for an act the action registry names that no writer produces yet. |
sites |
How many places in the code write the row; 0 when the action is written through a computed expression (the approvals engine re-emits the governed action under its own name). |
registry |
The action registry's row when the act is registered: mechanism, risk class, whether it is human-only. |
The top of the file also lists the result literals with how the ledger reads each (APPROVAL,
DECLINE or neither), every target type with the model it names, and counts by class and family.
The nine families
authentication, credentials, access, configuration, data access and export, agent activity,
security response, operator and support access, audit-system changes. A family is assigned by the
action's name, first match, in domain/src/modules/accountability/audit-families.ts; an action
that matches no rule is configuration.
What the principal kinds mean
principalKinds is the set of kinds that can produce the row, not a statement of who did. A
kind is absent only where the code excludes it: a human-only act, a row the deployment operator
console writes (no agent, no impersonation), or a system writer. A row written by a route or
service that audits for whoever authenticated lists all three, because a session, a personal access
token, an agent token and an organization CI token all reach it. The actual actor, mode and
transport of each row are in the row itself (audit_search).
Where it comes from
The catalogue is generated from the same tables the vocabulary tests pin
(api/test/accountability/action-taxonomy.test.ts, result-vocabulary.test.ts,
target-type-vocabulary.test.ts, and the per-package files in vocabulary/), the action registry,
and the audit call sites in the api, domain and MCP server. A new audit literal cannot be added
without being pinned by those tests, so it cannot be missing from the catalogue; a test fails when a
live act that gates an agent writes no audit row under its own name, unless the gap is listed and
argued for.
pnpm --filter @bucker/api exec tsx scripts/emit-audit-catalogue.ts # write
pnpm --filter @bucker/api exec tsx scripts/emit-audit-catalogue.ts --check # exit 1 on drift
audit_search
audit_search is an MCP tool in the security toolset (read, security:read, up to 1,200 tokens).
- Two readers. With any token that can reach the organization, it returns your own rows: what
the principal behind the token did. With
security:readon the organization it returns the organization's rows, and only then mayactorname someone else. Asking for another principal without the scope is refused, not quietly narrowed. - Filters. Action (a name, or a prefix ending in
*), actor, target type and id, result, mode (interactive,delegated_client,autonomous,system), transport, credential type, OAuth client, and a window. - Bounds. At most 30 days per call, newest first, paged by a cursor on (time, id); the cursor continues after the last row served.
- Each row names the action, its class and family, the result, the actor and the person it acted for, mode, transport, credential type, client, target, the approval id and plan digest a governed act is bound to, and the keys (never the values) a before-and-after diff changed.
- Never served to any MCP token: IP addresses, user agents, e-mail addresses or display names.
Personal data is
pii:readand human-only; the dashboard's audit view keeps those columns for an owner. - Untrusted fields.
intent(what the caller said it was doing),targetId,clientIdand the changed keys can carry text an outsider wrote. They are scrubbed, scanned for injection, capped and listed in the answer'strust.untrustedFields. Treat them as data. - It is audited. Every call writes an
audit.searchrow naming the scope served, the rows returned and the families they fell in, and the read ledger counts the call. A refused call writes nothing.
Natural-language filters are available only as nl-query phrases, which compile to these filters.