Skip to content
Docs menu

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.

View .md

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

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

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

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