Audit Log

Every decision Beekeeper makes (allow, warn, block, quarantine, nudge, and config change) is appended to an NDJSON audit log. Each line is a single JSON object.

A separate, opt-in corpus log records confirmed incidents for the local first-responder loop. It is a different file (corpus/beekeeper-corpus.ndjson), also append-only and owner-only and written through the same redaction step, but it carries a richer four-layer record (behavior, decision, outcome, context) in the frozen push-envelope shape rather than the flat decision record described here, and it never leaves the machine. See Security and Configuration.

Location

OS	Audit log
Linux / macOS	`~/.beekeeper/audit/beekeeper.ndjson`
Windows	`%APPDATA%\beekeeper\audit\beekeeper.ndjson`

The log is a single beekeeper.ndjson file with owner-only permissions (0600), written append-only. The shipped binary does not rotate or compress the audit log; there are no dated per-day files. Query it with the beekeeper audit subcommands below rather than reading dated files directly.

Reading the log

beekeeper audit tail   # stream live decisions (Ctrl+C to stop)

beekeeper audit tail --no-follow   # dump existing records and exit

Querying

beekeeper audit query --since 24h --decision block --limit 50

beekeeper audit query --since 2026-06-01T00:00:00Z --agent claude-code --tool Bash

--since accepts a Go duration (24h, 168h) or an RFC3339 timestamp
--agent, --tool, --decision (allow | warn | block), and --limit filter the results

Exporting

beekeeper audit export --format ndjson

beekeeper audit export --format csv --since 7d

beekeeper audit export --format otlp

--format is required and accepts ndjson, csv, or otlp. The same --since / --agent / --tool / --decision filters apply.

Nudge records

Package-manager nudge decisions are filtered with their own command:

beekeeper nudge audit --since 24h

A nudge record uses record_type:"nudge" with these key fields:

Field	Description
`nudge_action`	`advise` \| `proceed` \| `rewrite` \| `block`
`original_command`	the agent's original command string
`rewritten_command`	the rewrite (only when `nudge_action` is `rewrite`)
`reason_code`	structured reason (e.g. `pnpm-available-soft`, `pnpm-enforce-block`)
`pm_state`	flattened package-manager state for forensic provenance

Record examples

{"record_type":"decision","decision":"block","tool":"Bash","reason":"corroborated: 2 sources flag this package","agent":"claude-code"}
{"record_type":"nudge","nudge_action":"block","original_command":"npm install left-pad","reason_code":"pnpm-enforce-block","rewritten_command":"pnpm add left-pad"}
{"record_type":"config_change","reason_code":"nudge.mode","reason":"nudge.mode changed from \"block\" to \"soft\""}

Remote sinks and the redaction caveat

Beekeeper can fan audit records out to remote OTLP / HTTPS / syslog collectors.

Redaction is field-scoped, not content-scanning. The decision Reason field and raw/rewritten package-manager commands are redacted before records leave the machine, but Sentry-derived fields (accessed file paths, network destinations, process exe paths, correlated extension IDs) and catalog coordinates are written verbatim, and the behavioral-watch audit path does not route through RedactRecord at all. A credential embedded in a watched file path or network destination can therefore reach a remote sink unscrubbed. Account for this before forwarding audit logs off-host. The local file is owner-only (0600); remote sinks emit a "data leaving this machine" warning.