# 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`](./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.

```bash
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:read` on the organization it returns the
  organization's rows, and only then may `actor` name 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:read` and human-only; the dashboard's audit view keeps those columns for an
  owner.
- **Untrusted fields.** `intent` (what the caller said it was doing), `targetId`, `clientId` and the
  changed keys can carry text an outsider wrote. They are scrubbed, scanned for injection, capped
  and listed in the answer's `trust.untrustedFields`. Treat them as data.
- **It is audited.** Every call writes an `audit.search` row 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.
