Organisation policy and risk tiers
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.
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
Write the file, install it root-owned, and check it with venom doctor:
{
"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/"] }
}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 doctorThe file's permissions are the trust root for a hand-installed policy. On Windows the path is
C:\ProgramData\venom\policy.json.
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: 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 |
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
Conflicting flags fail before the session starts, with exit 2 and the file named:
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
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.
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 nowvenom 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.
Environment variables
| 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
Before you change the risk block, see what it would change:
venom policy test --policy draft.json --limit 50It 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
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.
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
- "the organisation policy … is invalid". Fix each listed error; the message names who to ask.
venom policy syncrefuses 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 doctorwarns the policy file is writable by you. Reinstall it root-owned, including the target of a symlink and every directory above it.
Related
- Permission modes and rules
- Guardrails: the org, key group and member layers in Venom Cloud.
- Audit
- The cloud section: setting key group policies in the console.