---
title: Audit log, signed actions and compliance
description: Verify the hash-chained permission audit log, the signed log of every command and file write, offline audit exports and Venom Cloud compliance packs.
section: security
order: 80
audience: [user, operator, builder]
sources: [packages/harness/src/permissions/audit-chain.ts, packages/harness/src/actions, cli/src/audit-cli.ts, cli/src/audit-export.ts, cli/src/actions-cli.ts, cli/src/compliance.ts, docs/signed-actions.md, docs/audit-export.md]
features: [security.audit, security.actions, security.compliance]
---

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 {#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](/docs/security/policy.md)'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.

```bash
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 {#actions}

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.

```bash
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 {#export}

For audits that need "who approved what" on a laptop:

```bash
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 {#compliance}

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:

```bash
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 {#related}

- [Permission modes and rules](/docs/security/permissions.md)
- [Organisation policy](/docs/security/policy.md#signed): the signed policy and its keys.
- [Egress map](/docs/security/egress.md): the hosts each session contacted.
