Guide

Audit Trail

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

What Is Recorded

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 (the Discard button, the web terminal and the CLI bar, discard <path> included), REST config sessions, gRPC config sessions. A rollback in the SSH editor or the web terminal also writes one
config-download web GET /config/download
config-upload web POST /config/upload, once the uploaded config is applied
daemon-reload SIGHUP, and request reload through the daemon on any surface
data-key-change delete data key and update data key through the daemon on any surface, which ze data rm and ze data write also send while ze runs
data-config-import update data config through the daemon on any surface, which ze data import also sends while ze runs. The detail holds the name and the placeholder in place of the content
auth-fail SSH, web, REST, gRPC, MCP

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

A daemon command records an entry only when it succeeds: a refused or failed command records nothing. Its detail is the command line as typed, with every credential value and the value after content replaced by <redacted>, so a key's bytes never reach the log.

A discard record's detail lists only the changes that discard dropped. discard <path> keeps your changes outside that path, so they are not in its record, and they appear in the commit record that later applies them. One exception: the SSH editor's diff lines carry no path, so when two places hold the same pending line (two peers both changed to the same hold time, say) and discard <path> drops one of them, the SSH record can also name the line you kept. The web records are exact. A whole discard run with nothing pending still writes a record, with an empty detail, on every surface, so the trail shows every discard an operator ran. A rollback record's detail is the rollback itself (the command in the web terminal, rollback <backup> in the SSH editor), a download record's is the file name, and an upload record's is uploaded configuration.

Storage

For a daemon started from a real config file, the audit log is stored next to that file as <config-base>.audit.jsonl. For stdin configs (ze -) and web-only test mode, Ze uses an in-memory audit log.

The in-memory query cache keeps the newest records up to the configured retention limit in code. The default is 10,000 entries, with accepted bounds from 100 to 100,000.

Each record rewrites the file. When a write fails (a full disk, a directory ze cannot write), the action still goes ahead and the record stays in memory; show doctor reports doctor-audit-record-failed with the file, the error, the time and how many writes failed, whichever surface wrote. The next write that lands rewrites the file with every record still held, and the row clears.

Querying

Use show audit from the daemon CLI or ze show audit from the shell:

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

The response is structured data with entries and count. Filters can be combined. Time filters use RFC 3339 timestamps.

Authorization Notes

Web config mutations now use the same profile authorizer as SSH, API, and MCP command dispatch. A read-only user can still open /show/ pages, but POST /config/set/, add, delete, rename, commit, and discard are denied before the draft is changed.

REST and gRPC without a configured token or per-user authenticator use the built-in api identity in read-only mode. Read commands work. Command writes and config sessions return 403.