Skip to content
Docs menu

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.

View .md

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 --json

The 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.