Compliance evidence report

vanzik report turns the audit log into a report you can hand to an auditor: what Vanzik decided over a period, whether the log that recorded it was changed, and which SOC 2 criteria that evidence bears on.

The report is supporting evidence. It is not a SOC 2 report, a certification or an audit opinion. It shows what the audit log recorded. An auditor decides what that proves and whether it is enough.

Generate it#

From the audit log files (the default). This also verifies the seal chain, as vanzik audit verify does. Without --key-file, a log sealed with a key still gets every check but its hashes (every entry after the seal is sealed, seq has no gaps, each prev_hash links up), and the report says the hashes were not checked:

vanzik report --since 2026-09-01 --until 2026-10-01 \
  --audit-log /var/lib/vanzik/audit.jsonl \
  --key-file /var/lib/vanzik/audit-seal.key \
  --policy /etc/vanzik/default.yaml \
  --output html --out-file september.html

From a running server, when you can't read its files:

vanzik report --url https://guard.internal --api-key "$KEY" \
  --since 7d --output json > week.json

Without --since and --until the report covers the 24 hours before now. --since is inclusive and --until exclusive, so back-to-back reports (--since 2026-09-01 --until 2026-10-01, then --since 2026-10-01 …) never count an entry twice or miss one. Times are RFC 3339, a date (midnight UTC), or a duration back in time: 90m, 24h, 7d (d is 24 hours; Go durations have no day unit, so the report adds it). All flags: CLI.md § vanzik report.

Formats: md (Markdown, the default), json (the stable shape below) and html (one page with inline CSS and no scripts, so it can be mailed or archived as is). Every value taken from the log is escaped in Markdown and HTML, so an agent id can't add markup to the report, and a URL or an address in it does not become a link. In both, control characters (but tab and newline) and the bidi controls that reorder text are replaced with U+FFFD, so a value can't move a terminal's cursor or read as something else. JSON keeps every value exactly as logged; its encoder escapes the C0 controls.

Exit status: 0 written; 1 written, but the audit log failed verification; 2 command-line mistake; 3 the log, a key file, the policy file or the server can't be read.

Files or server#

The server is asked for the period with since and until, which GET /v1/audit takes from 1.4 (they came with the sessions work). A server that predates them ignores them; the report drops entries outside the period itself, so the numbers are the same, and source.outside_period says how many were dropped. A server older than 1.4 also has no GET /v1/audit/head, so the seal status is then "unknown".

The report pages by time, not by offset: each page starts a moment before the last entry of the one before, and an entry seen twice is counted once. An offset into the server's live file stops meaning anything when the file rotates. Rotation still loses the entries left in the old file, which the server no longer serves; on a sealed server the report notices (the seal head names a new file afterwards) and adds a warning to the report. The report stops with exit 3 if a server sends the same page over and over, or after 50,000 pages, 10 million entries or 30 minutes: report on that much from the files.

--url must not hold a user name or password (http://user:pass@host): it would be written into the report. Give the key with --api-key.

What the report holds#

• Summary. The period, when the report was made, the Vanzik version, where the entries came from, and the policy file with its SHA-256.

• Audit log integrity. intact, broken, not_sealed, not_verified (the log says it is sealed, but the hashes were not checked: server mode, or no --key-file) or unknown. With the seal type (HMAC key or plain SHA-256), the latest seal anchor (seq and hash), the files read, and audit verify's warnings.

• Activity. Entries by decision (ALLOW, DENY and REQUIRE_APPROVAL are always listed), scope, transport, tenant and agent. Entries written without a transport count as sdk, and without a tenant as local, as everywhere else.

• Top rules. The rules behind DENY and REQUIRE_APPROVAL decisions, by count. A DENY that no rule matched shows as (default deny).

• Approvals. Approval ids sent for approval in the period, approved by a person, denied by a person, and with no outcome on record (see Limits). "Timed out" is always unknown.

• Agents and sessions. How many were seen, and their ids (the first 100 by name).

• Posture checks. Each is pass, warn, fail or unknown:

  Check	How it is decided
  Audit log sealed	Passes only when the chain verified. Fails when it is broken. A seal the report could not verify is a claim: a _meta header anyone who can write the file can forge (warn, files read without --key-file), or the server's word (unknown)
  Seal uses a secret key	HMAC-SHA256 passes only when it verified with --key-file; read from an unverified header it is unknown. Plain SHA-256 warns (anyone who can write the file can recompute it)
  Seal chain verified	audit verify's result; unknown in server mode
  Entries outside the seal chain	Files: entries written before sealing began, or fail when the chain breaks (nothing after the break is protected). Server: entries in the period that came without seq or hash
  Unreadable lines	Lines of the files that are not entries, or files that end early
  Secrets masked in the log	Fails when a request or reason still matches the built-in secret patterns of --audit-redact. Otherwise unknown: masked values ([REDACTED]) with no unmasked secret are consistent with masking being on, but not proof, since an agent's own text can contain the marker; with neither, the log can't show it
  Audit API requires an API key	Server mode: whether GET /v1/audit answers without the key

• Control mapping. See below.

• Limits. What the report can't show, in the report itself.

Control mapping#

The report maps its evidence to five SOC 2 Trust Services Criteria. Each row says what the report shows and in which sections. It never says a criterion is met.

Limits#

• The report counts what the audit log recorded. An action that never reached Vanzik (an agent not wired to it, a tool outside the gateway) is not in it.
• The audit log has an entry when an action is sent for approval, one when a person approves or denies it (matched_rule: approval:resolved:<via>, with how the call was authenticated and the caller's address, not a named person), and another when the agent comes back with the approval id. It does not record a request that timed out. The report's Approved and Denied counts come from the entries written when the agent comes back, so "No outcome on record" covers requests that timed out, were decided but not retried, were decided after the period, or are still pending. The resolution entries count in the decision totals, and a deny's rule shows among the deny rules.
• The policy SHA-256 is of the file when the report is made. The log does not record which version of the policy made each decision; keep the policy in version control and match the hash to a commit.
• The secret check uses the built-in patterns only, not a policy's notifications.redaction.extra_patterns.
• Reading files: archives that no file links to, and archives already pruned (--audit-max-backups, --audit-max-age-days), are not read. Entries a running server still holds in its buffer or overflow file are not in the log yet. Keep archives for as long as your audit period needs.
• Server mode: the chain is not verified, rotated archives of a file backend are not included, and only one tenant is covered.
• A passing verify shows the log was not changed by anyone without the key; it does not rule out the newest entries being cut off. Check published anchors with vanzik audit verify --anchor for that (OPERATIONS § Sealing and anchoring).

JSON shape#

--output json prints one object. Its shape is stable for 2.x: fields are only added, never renamed or removed. format_version (now 1) changes only if that ever stops being true. Times are RFC 3339 UTC.

The renderers and the numbers live in pkg/report, with golden files in pkg/report/testdata/ for each format.