audit

Pre-Alpha. This page describes behavior that may change.

Ze keeps a local structured audit log for operator actions that change state or fail authentication. The log is append-only from the operator's point of view: there is a query command, but no command to delete or truncate records.

What is recorded

The audit trail covers config commit and discard, daemon reload, and failed authentication across SSH, web, REST, gRPC, MCP, CLI, and system surfaces.

Action	Surfaces
config-commit	SSH/CLI config editor, web config editor, REST config sessions, gRPC config sessions
config-discard	SSH/CLI config editor, web config editor, REST config sessions, gRPC config sessions
daemon-reload	SIGHUP and daemon reload command dispatch
auth-fail	SSH, web, REST, gRPC, MCP

Each entry carries timestamp, actor, remote-addr, surface, action, detail, and outcome fields. The detail field carries the config diff for commit and discard records when Ze has one.

Storage

When Ze starts from a real config file, the audit log is disk-backed and stored next to that file as <config-base>.audit.jsonl, one JSON object per line. The records survive a restart, so the evidence stays available.

For stdin configs (ze -) and web-only test mode, Ze uses memory-only storage. The in-memory query cache keeps the newest records up to a retention limit set in code. The default is 10,000 entries, with accepted bounds from 100 to 100,000.

Querying

Use show audit from the daemon CLI, or ze show audit from the shell. The response is structured data with entries and count. Filters can be combined.

Filter	Argument	Meaning
action	action name	Restrict to one action, for example config-commit.
actor	username	Restrict to one actor.
surface	surface name	Restrict to one surface, for example web.
since	RFC 3339 timestamp	Only entries at or after this time.
until	RFC 3339 timestamp	Only entries before this time.
count	number	Limit the number of returned entries.

ze show audit
ze show audit action config-commit
ze show audit actor alice
ze show audit surface web count 20
ze show audit since 2026-05-24T10:00:00Z until 2026-05-24T11:00:00Z

Time filters use RFC 3339 timestamps.

See also

• Authorization
• Health Checks
• Production Diagnostics

Adapted from main/docs/guide/audit.md.