Audit log, signed actions and compliance
Verify the hash-chained permission audit log, the signed log of every command and file write, offline audit exports and Venom Cloud compliance packs.
Venom leaves three kinds of evidence, all local, all checkable offline:
| Evidence | Holds | Check with |
|---|---|---|
| Permission audit log | every permission decision: what was asked, allowed or denied, by whom and why | venom audit verify |
| Signed action log | every command the agent ran and every file it wrote, one hash chain per session, signed by this machine | venom actions verify |
| Audit export | a period's signed commit receipts, approvals and policy versions in one signed directory | venom audit verify-export |
| Compliance pack (Venom Cloud) | the org's side: members, keys, spend, controls and their changes | venom compliance verify |
Permission audit log
Every decision is appended to ~/.venom/audit.jsonl: time, session, directory, mode, tool, summary, verdict,
outcome, via (rule, user, auto-classifier, egress-proxy …), reason, rule and agent. Bash records also say whether
the command was sandboxed and with what network. Blocked sandbox connections are recorded as tool: "network". An
organisation policy's audit.path gets the same records, and the user can't turn it off.
Each line carries chain (the writer's id), seq and prev (the SHA-256 of that writer's previous line), so an
edited, deleted, reordered or truncated record is caught. Each process chains only its own records: several venom
processes can append to one write-only log with no lock.
venom audit verify # the default log
venom audit verify audit.jsonl.1 audit.jsonl # rotated files, oldest first
venom audit verify --witness <hash> # also catch lines cut from the end since you kept that head
venom audit verify --jsonThe default file is the policy's audit.path, else ~/.venom/audit.jsonl. Keep the printed head somewhere else and
pass it back with --witness. Exit 0 when nothing is broken, 1 on a break (each named by line), 2 on usage.
Signed action log
A tamper-evident record of what the agent did on your machine. It goes nowhere unless you share the session, and then only the seal (head, count, signature) goes with it.
| Tool | Record |
|---|---|
bash |
kind: "command", the command line, error: true when it failed |
write, edit |
kind: "write", the absolute path, the file's SHA-256 and size after the call |
apply_patch |
one write record per file it touched |
| A tool's own nested calls (workflows, code mode) | kind: "nested" with redacted arguments and status; results are never recorded |
Calls the permission engine refused never ran, so they are in the audit log, not here. Subagents keep their own logs.
The file is ~/.venom/actions/<session>.jsonl (0600). Each line's prev is the SHA-256 of the line before. When the
session ends, a seal line signs the session id, line count and head with an Ed25519 key that belongs to this
machine. A resumed session continues the chain and is sealed again.
venom actions list # sessions with a log, newest first
venom actions show [session] [--json] # what the agent did (default: the newest session)
venom actions verify [session|file] [--head <hash>] [--key <kid>] [--json]
venom actions key # this machine's key id and where it is kept| Flag | What it does |
|---|---|
--head <hash> |
Check that a head kept elsewhere (for example the one Venom Cloud stores with a shared session) is one of the log's sealed heads. This catches lines cut from the end |
--key <kid> |
Accept only seals by these key ids (repeatable) |
--json |
Machine-readable output |
A session can be named by a unique prefix of its id. verify exits 0 when the chain and every seal hold and 1
otherwise, naming each broken line; records after the last seal are reported as unsealed.
The machine key is made the first time a session has something to seal. It lives in the macOS Keychain, the
Secret Service (with secret-tool), or ~/.venom/keys/actions-ed25519.key (0600); VENOM_KEYSTORE picks one. The
key id is the first 16 hex digits of the SHA-256 of its public key. If the keychain can't be reached, the log stays
unsealed and verify says so.
Shared sessions. venom session share attaches the last seal; Venom Cloud checks the signature before storing
(422 bad_signature otherwise) and shows the count, key id, head and the venom actions verify … --head … line to
run on the machine that did the work.
Audit export
For audits that need "who approved what" on a laptop:
venom audit export --month 2026-10 --out ./audit-2026-10
venom audit verify-export ./audit-2026-10 --trust <key id> --policy-keys ./policy-keys| File | Content |
|---|---|
receipts.jsonl |
each commit in the period (on --rev, default HEAD) that carries a signed provenance receipt, and whether it still matched the commit at export (bound) |
approvals.jsonl |
the audit log's ask records in the period: every call the policy sent to a person, with the answer |
policies/<seq>.json |
the signed policy envelopes issued in the period, byte for byte, from ~/.venom/policy-history (written by venom policy sync) and the current policy |
manifest.json |
the period, each file's SHA-256 and size, counts (commits, commits without a receipt, approvals, human approvals, policy versions), the audit log's chain state, and an Ed25519 signature by this machine's provenance key |
venom audit export flag |
What it does |
|---|---|
--month YYYY-MM |
The period, in UTC |
--since <date> --until <date> |
Or a [since, until) range, YYYY-MM-DD |
--out <dir> |
Where to write; refuses a non-empty directory |
--rev <rev> |
Whose history to read receipts from (default HEAD) |
--audit <file> |
Audit log files to read (repeatable) |
--policies <dir> |
Policy history directory |
--json |
Print the result as JSON |
venom audit verify-export <dir> checks the manifest signature (signer is this machine's key or one named with
--trust), every file's hash, that no other file is present, every receipt's signature, every approval line, and
every policy envelope against the policy keys (/etc/venom/policy-keys, else the key venom cloud login pinned, or
--policy-keys <dir>). With no policy keys it fails unless you pass --skip-policy-signatures. Exit 0, 1 when
anything fails, 2 on usage.
The signature proves the bundle is what the exporting machine's key signed, not that the machine was honest; the receipts and policy envelopes carry their own signatures. Commits without a receipt are counted, not hidden.
Compliance packs
An org admin downloads a compliance pack from Venom Cloud (Settings → Compliance): a signed ZIP with members, keys
(never the secrets), spend, provider keys, the controls in place, every control change with before and after, the
audit log, incidents, signed session shares and a readable summary.html. It is signed with the org's policy key,
the same key members' CLIs already trust. Check it offline:
venom compliance verify pack.zip --fingerprint "3f2a 9c41 07be d5e8"| Flag | What it does |
|---|---|
--fingerprint "<fp>" |
Trust the signing key when its 16-hex-digit fingerprint matches the one the console shows |
--key <file|base64url> |
Trust this exact public key (repeatable) |
--policy-keys <dir> |
Trust the keys in this directory instead of /etc/venom/policy-keys or the pinned key |
--json |
Machine-readable output |
It checks the Ed25519 signature over manifest.json, every listed file's SHA-256 and size, and that the ZIP holds no
file the manifest doesn't list. Exit 0 when everything holds, 1 when anything doesn't, 2 on usage.
Related
- Permission modes and rules
- Organisation policy: the signed policy and its keys.
- Egress map: the hosts each session contacted.