---
title: Organisation policy and risk tiers
description: Enforce rules for every venom on a machine with /etc/venom/policy.json or a signed policy from Venom Cloud, and score the risk of a change with venom risk.
section: security
order: 40
audience: [operator, builder, agent]
sources: [packages/harness/src/permissions/policy.ts, packages/harness/src/permissions/policy-signing.ts, cli/src/policy.ts, cli/src/policy-sync.ts, cli/src/policy-test.ts, cli/src/risk.ts, packages/harness/src/risk/index.ts, examples/policy/policy.json]
features: [security.policy, security.risk]
---

An organisation policy is the administrator's layer. It wins over the user's `~/.venom/permissions.json`, a project's
config, project trust, `--approve`, the CLI's flags and the environment. Without a policy nothing changes. A policy
only tightens: it has no `allow` list.

## Quick start {#quick-start}

Write the file, install it root-owned, and check it with `venom doctor`:

```json
{
  "version": 1,
  "description": "Engineering laptops",
  "contact": "it-help@example.com",
  "deny": ["read(~/.kube/**)", "bash(terraform apply:*)"],
  "ask": ["bash(git push:*)"],
  "modes": { "allowed": ["plan", "default", "accept-edits"], "default": "default" },
  "sandbox": { "required": true, "network": { "allow": ["registry.npmjs.org", "*.example.com"], "defaults": false } },
  "mcp": { "allow": ["github"] },
  "web": true,
  "browser": false,
  "orchestrator": { "baseUrl": "https://venom.example.com/v1" },
  "audit": { "path": "/var/log/venom/audit.jsonl" },
  "risk": { "medium": 3, "high": 7, "sensitive": ["infra/", "billing/"] }
}
```

```bash
sudo install -d -m 0755 -o root -g root /etc/venom          # macOS: -g wheel
sudo install -m 0644 -o root -g root policy.json /etc/venom/policy.json
# the audit log: every user may append, none may read or truncate it
sudo install -d -m 0755 /var/log/venom
sudo install -m 0622 /dev/null /var/log/venom/audit.jsonl
sudo chattr +a /var/log/venom/audit.jsonl                   # macOS: sudo chflags sappnd …
venom doctor
```

The file's permissions are the trust root for a hand-installed policy. On Windows the path is
`C:\ProgramData\venom\policy.json`.

## Keys {#keys}

| Key | Type | What it does |
|---|---|---|
| `version` | `1` | Required |
| `description`, `contact` | string | Shown by `venom doctor`; `contact` ends every refusal message ("ask …") |
| `deny`, `ask` | list of rules | Always win: no allow rule, trust, mode, "allow always" or hook lifts them |
| `modes.allowed` | list of modes | The only modes a user may pick. A forbidden mode from config is capped; `alt+m` skips it |
| `modes.default` | mode | The start mode |
| `sandbox.required` | boolean | Bash runs in the OS sandbox in every mode |
| `sandbox.network` | object | A ceiling every other network allowlist is intersected with (`allow`, `defaults`) |
| `mcp.allow` | list of names | The only MCP servers that may start, from any source |
| `mcp.servers` | object | The org's approved MCP servers, connected by `venom mcp enable` and `venom mcp connect` |
| `web` | boolean | `false` removes `web_fetch` and `web_search`, and refuses `venom review --post` |
| `browser` | boolean | `false` removes the browser tools and refuses `--chrome*` |
| `orchestrator.baseUrl` | URL | Pins the provider; a different `VENOM_BASE_URL` is refused |
| `audit.path` | path | A JSONL copy of every permission decision the user can't turn off |
| `risk` | object | Thresholds for [risk tiers](#risk): `medium`, `high`, `sensitive` |
| `plugins` | object | `install: "org"` or `"any"`, and `deny`, a list of plugin names |
| `supplyChain` | object | The dependency check: `action` (`ask` or `deny`), `minAgeDays` (0 to 365, default 7), `registry` (boolean). See [Guardrails](/docs/security/guardrails.md#supply-chain) |
| `repos` | list | Extra `deny` and `ask` rules for checkouts whose git remote is in `match` |

Unknown keys at any level, malformed rules or hosts, and an unreadable file stop every command that starts a
session with exit 2 and every error listed, so a typo never means "no policy". `venom doctor` still runs and reports
it.

## What it refuses {#refusals}

Conflicting flags fail before the session starts, with exit 2 and the file named:

```text
venom: --yolo is not allowed by the organisation policy (/etc/venom/policy.json): permission mode yolo is off; allowed: plan, default, accept-edits.
```

This covers `--yolo`, `--plan` and `--permission-mode` for a forbidden mode; `--sudo` and
`--dangerously-skip-permissions` under a policy that limits modes, requires the sandbox or caps its network;
`--no-sandbox` under `sandbox.required`; `--chrome*` under `browser: false`; another `VENOM_BASE_URL` under a pinned
orchestrator. `venom serve` answers a forbidden mode or `sandbox: false` with 403 `policy_forbidden`. An SDK host
gets the caps applied with a diagnostic.

## Signed policies from Venom Cloud {#signed}

Teams on Venom Cloud don't hand-copy files. An admin sets each key group's policy in the console (a key group holds API keys, daemons, policies and GPU grants, not people; the API calls it `team`); the cloud signs it as an
Ed25519 envelope with a sequence number, and machines fetch it.

```bash
venom cloud login      # pins the org's policy key in ~/.venom/policy-keys and fetches the policy
venom policy sync      # fetch and install the latest signed policy now
```

`venom policy sync` verifies the signature, expiry and sequence number (against `~/.venom/policy-seq`) before it
writes anything. Exit 0 installed, 1 refused or unreachable, 2 usage.

| Setup | Keys trusted | Where the policy is written | Binding |
|---|---|---|---|
| Keys installed by an administrator in `/etc/venom/policy-keys` | those keys | `/etc/venom/policy.json` (needs root) | enforced |
| No system keys and no system policy | the key `venom cloud login` pinned in `~/.venom/policy-keys` | `~/.venom/policy.json` (the user policy) | by agreement: the user can delete it |

venom also syncs at start (TUI, `venom serve`, `venom acp`) when you are logged in and use the user policy, within a
3-second budget. A problem with the user policy is one warning, and venom starts without it.

Signed policy versions are kept in `~/.venom/policy-history` for [audit exports](/docs/security/audit.md#export).

### Environment variables {#env}

| Variable | Where | What it does |
|---|---|---|
| `VENOM_POLICY_FILE` | CLI | Another policy file, for tests and containers. Ignored whenever anything exists at `/etc/venom/policy.json`, so a user can't swap the administrator's file through the environment. When set, the user policy is not read |
| `VENOM_POLICY_SIGNING_KEY` | Venom Cloud deployment | The deployment's policy signing key (`{kid, pkcs8_b64}`), used when an org has no key of its own. Without either, policy writes and compliance packs answer `503 policy_signing_not_configured` |

## Replaying a draft policy {#policy-test}

Before you change the `risk` block, see what it would change:

```bash
venom policy test --policy draft.json --limit 50
```

It replays the last first-parent commits of `--base` and prints which ones would change tier. The policy in force
(the `risk` block of the active policy, else the defaults) is the "before". Offline and advisory.

| Flag | Default | What it does |
|---|---|---|
| `--policy <file>` | required | The draft: a policy file or just its `risk` block |
| `--base <ref>` | `HEAD` | The history to replay |
| `--limit <n>` | `100` | How many changes, 1 to 5000 |
| `--json` | off | Print `venom.policy-test/v1` |

Exit 0 when it ran, 2 on a usage error or an unreadable policy.

## Risk tiers {#risk}

`venom risk` scores a change from its touched paths, co-change history, test-impact coverage, permission surface and
how hard it is to undo, and prints `low`, `medium` or `high` with the reasons. It is advisory: a tier routes a change
(merge on green, a closer review, a human signature) and never grants a permission.

```bash
venom risk                    # the work tree against HEAD, untracked files included
venom risk --base origin/main
git diff main | venom risk -  # a diff on stdin
venom risk --line             # "risk: <tier> (<reasons>)"
```

| Argument or flag | What it does |
|---|---|
| `<diff-file>`, `-` | Score a unified diff (`-` reads stdin) |
| `--base <ref>` | Score the work tree against a ref (default `HEAD`) |
| `--json` | Print the assessment as JSON |
| `--line` | Print one line |

Thresholds come from the policy's `risk` block: `medium` (default 3) and `high` (default 7) are the lowest scores for
each tier, and `sensitive` adds path fragments that raise the score. Exit 0 when it ran, 2 on a usage error.

## Troubleshooting {#troubleshooting}

- **"the organisation policy … is invalid".** Fix each listed error; the message names who to ask.
- **`venom policy sync` refuses the response.** The signature, expiry or sequence number didn't verify. A lower
  sequence number than the last installed is a rollback and is refused on purpose.
- **`venom doctor` warns the policy file is writable by you.** Reinstall it root-owned, including the target of a
  symlink and every directory above it.

## Related {#related}

- [Permission modes and rules](/docs/security/permissions.md)
- [Guardrails](/docs/security/guardrails.md): the org, key group and member layers in Venom Cloud.
- [Audit](/docs/security/audit.md)
- [The cloud section](/docs/cloud.md): setting key group policies in the console.
