Guardrails
Set content, routing, model, tool, spend and answer rules at the org, key group and member layer, read a guardrail code, and use the prompt-injection shield and supply-chain check.
Guardrails decide what may leave a person's machine, which models they may use, what the agent may run and how much may be spent. They come from three layers, merged into one set before anything is checked, so every request gets one decision, and "why was this blocked?" has an answer naming the layer, the rule and a stable code.
| Layer | Who sets it | Applies to |
|---|---|---|
| Org | owners and admins | everyone in the org |
| Key group | key group admins, within the org's limits; a reseller for each resold customer | the key group's or customer's keys |
| Member | each person, for themselves | only their own requests |
You can always make things stricter for yourself. You can relax a rule only when the layer above marked it relaxable.
Quick start: your own guardrails
In the CLI, offline too, from venom.yaml:
guardrails:
catalog: [emails, session_spend_warning]
rules:
- name: Mask my phone
kind: content
action: redact
match: { type: regex, pattern: '\+65 9123 \d{4}', label: my_phone }
- name: Clients stay local
kind: routing
action: keep_local
paths: ["~/clients/**"]
- name: Ask before push
kind: tools
action: ask
tools: ["bash(git push:*)"]In a session, /guardrails lists every rule that applies to you (your org's and key group's from the gateway's
GET /v1/guardrails, plus your own):
| Command | What it does |
|---|---|
/guardrails |
List the rules in force and where each came from |
/guardrails catalog |
List the catalog entries |
/guardrails add <id> |
Add a catalog entry to your venom.yaml |
/guardrails remove <id|code> |
Remove one of yours |
/guardrails off <code>, /guardrails on <code> |
Turn a relaxable org or key group rule off or on for yourself (Venom Cloud) |
/guardrails draft <sentence> |
Draft a rule from plain words; prints the YAML to paste. Never saved on its own |
What a guardrail can be
| Kind | Checks | Actions | Enforced by |
|---|---|---|---|
content |
keywords, a regex, or a detector (credentials, card numbers, national IDs, emails, phones, prompt injection) in prompts, answers and tool output | block, redact, keep_local, warn, log |
the gateway; the CLI for your own rules and tool output |
routing |
requests holding matched content, or files from paths or repos, go to local models only |
keep_local, block |
the gateway (content); the CLI (paths, repos) |
models |
allowed and denied models (* matches any run: gpt-5*) |
block |
the gateway, and the CLI before a request leaves |
tools |
permission rules such as bash(git push:*) |
deny, ask |
the CLI, in front of the permission engine |
spend |
per session, day or month | warn, block, downgrade |
Venom Cloud (day, month); the CLI (session) |
answers |
a required disclaimer, a length cap, banned phrases | rewrite, block |
Venom Cloud's response filter |
Every rule also has a mode: enforce, or monitor, which only records what it would have done. Org and key group rules
carry a lock: locked (no changes below), tighten (the default: only stricter) or relaxable (members may turn it
off).
How layers combine. The strictest action wins (block and deny, then keep local, downgrade, ask, redact and rewrite, warn, log). Denied models and tools from every layer add up; each layer's allowed models is one more list a model must match. Limits take the minimum. Admins see that a member has personal rules and how often they fire, never the patterns. Venom Cloud, the orchestrator and the harness run one resolver, checked against shared test vectors.
Model names compare in a canonical form in every list: invisible characters dropped, NFKC, trimmed, lowercased,
a trailing :latest dropped. A deny pattern also refuses known provider prefixes (openai/gpt-4o), dated
snapshots (gpt-4o-2024-08-06) and look-alike letters. An allow list admits only what it names.
venom.yaml reference
| Key | Type | Default | What it does |
|---|---|---|---|
guardrails |
object | none | Your own guardrails, applied by the CLI on top of your org's and key group's |
guardrails.catalog |
list of ids | [] |
Catalog entries to switch on |
guardrails.rules |
list | [] |
Your own rules |
guardrails.rules[].name |
string | required | What you call it |
guardrails.rules[].code |
string | assigned | GR-ME-<what>-<number>; the next free number of its kind when absent |
guardrails.rules[].description |
string | none | A note for yourself |
guardrails.rules[].kind |
content, routing, models, tools, spend, answers |
required | What it checks |
guardrails.rules[].action |
block, deny, keep_local, downgrade, ask, redact, rewrite, warn, log |
required | What it does; each kind takes some |
guardrails.rules[].mode |
enforce, monitor |
enforce |
monitor only notes what it would have done |
guardrails.rules[].enabled |
boolean | true |
Turn a rule off without deleting it |
guardrails.rules[].match |
object | none | content and routing: {type: keywords, words}, {type: regex, pattern} or {type: detector, detector} |
guardrails.rules[].direction |
request, response, both |
content: prompts, answers or both |
|
guardrails.rules[].paths |
list of globs | none | routing: files whose content stays on local models |
guardrails.rules[].repos |
list | none | routing: repositories whose files stay on local models |
guardrails.rules[].models |
{allow?, deny?} |
none | models: lists of patterns |
guardrails.rules[].tools |
list of rules | none | tools: commands, files or sites to deny or ask about |
guardrails.rules[].limit |
{usd, per} |
none | spend: per is session, day or month |
guardrails.rules[].answer |
{disclaimer?, max_chars?} |
none | answers |
What the CLI does with each kind:
| Kind | In the CLI |
|---|---|
content |
On every request it sends (block before anything leaves; redact the same way every turn so the prompt cache holds; warn) and on tool output (a block withholds it from the model) |
routing |
A file read under paths keeps the session local: every later request carries x-venom-keep-local: <code>, which Venom Cloud and the orchestrator honour |
tools |
Deny and ask rules ahead of the permission engine's; a denial names the code |
spend |
One warning past a warn limit; past a block limit, later turns are refused |
models |
Checked before a request leaves |
Codes
Every guardrail has a stable code, GR-<layer>-<what>-<number>: layer ORG, TEAM or ME; what it checks CRED,
CARD, PII, KW, RX, INJ, LOCAL, MODEL, TOOL, SPEND, ANS or TOPIC; then a number from 001.
Catalog entries switched on in config are numbered 101 plus their place in the catalog (emails is GR-ME-PII-104).
Numbers from 900 name built-in engines:
| Code | Engine |
|---|---|
GR-ORG-CRED-900 |
the secret scanner on answers through the cloud |
GR-ORG-MODEL-900, GR-ORG-MODEL-901 |
the key's own model lists; the key creator's role's |
GR-TEAM-MODEL-900 |
a resold customer's model list |
GR-ORG-SPEND-900 |
the org's monthly cap |
GR-ORG-SPEND-901 to 905 |
spend guards per key, key group, member, gear, customer |
GR-ORG-TOPIC-900 |
the prompt classifier |
GR-ORG-TOOL-900 |
the signed permission profile in the CLI |
GR-ORG-TOOL-901 |
the supply-chain check |
GR-ME-CRED-900 |
the secrets vault refused a {{secret:NAME}} use |
Each code has a page at /g/<code> (Venom Cloud, or the self-hosted orchestrator) saying what the rule checks, its
layer, its lock and how to ask for an exception. Word lists and patterns are never shown, and a member's own rule is
shown only to them.
On the wire
Detection happens at the gateway, so guardrails hold for any client, plain OpenAI SDK calls included. A block is a 403:
HTTP/1.1 403 Forbidden
x-venom-guardrail: GR-ORG-CRED-001; action=block; layer=org; url=https://cloud.usevenom.dev/g/GR-ORG-CRED-001
{"error": {"type": "guardrail_blocked", "code": "GR-ORG-CRED-001", "layer": "org", "action": "block",
"message": "Blocked by your organisation's guardrail \"Credentials\": a private key was found in your prompt. …",
"url": "https://cloud.usevenom.dev/g/GR-ORG-CRED-001", "request_id": "req_…", "param": null}}Redact, warn and keep-local don't fail the request: they add an x-venom-guardrail entry per rule that fired, and a
streamed chat answer ends with one more chunk carrying venom_guardrails. The Responses API gets an
event: venom.guardrails. Engines with their own errors keep them (403 model_not_allowed, 429
spend_limit_reached, 429 spend_cap_reached) and add error.guardrail. The matched text is never echoed.
Catalog
| Id | What it does |
|---|---|
credentials |
blocks API keys, tokens, private keys, cloud credentials, JWTs and passwords (locked) |
card_numbers |
blocks payment card numbers (locked) |
national_ids |
redacts US Social Security and Singapore NRIC/FIN numbers |
emails, phones |
redact email addresses and phone numbers in prompts |
profanity |
redacts common swear words in answers (relaxable) |
prompt_injection |
warns when untrusted content carries instructions aimed at the model |
client_files_local |
files under a clients folder go to local models only |
no_preview_models |
blocks models whose name ends in -preview |
session_spend_warning |
warns when one session has spent more than $2 |
daily_spend_limit |
blocks once a person has spent $20 in a day |
answer_disclaimer |
every answer ends with a note you write |
package_installs |
every command that adds a package asks first; set it to deny to refuse them |
Prompt-injection shield
Text the agent reads from outside (a web page, a fetched URL, a file, command output, an MCP result, an intake item)
can carry instructions meant for the model. The prompt_injection detector reads only untrusted text: tool results,
and in user or system messages only what sits inside an <untrusted_…> envelope. Your own prompt is never flagged.
It looks for override phrases ("ignore all previous instructions"), chat-template tokens and fake system tags, tool
call look-alikes, image links that carry data out, curl … | sh, "don't tell the user", hidden text (Unicode tag
characters, bidi overrides, zero-width runs, HTML hidden with CSS), and text addressed to an AI. One strong finding,
or weak findings of two kinds, flags the content.
In the CLI the shield works without any guardrail configured:
- Envelopes. Every outside tool result reaches the model inside
<untrusted_ID source="…">tags, and the static system prompt says nothing inside them is an instruction. - Hidden text is removed from web pages, browser reads and MCP results. File and command output keep their exact bytes and are flagged instead.
- Flags go to you: a note after the result, a warning line in the TUI and an audit record.
- Risky tools ask. While a flagged result is in context, a call the engine would allow asks instead when it could
act for the injection: bash beyond read-only, web and browser tools, MCP tools not marked read-only, subagents.
Reads and workspace edits pass.
--sudosettles these asks too.
With a guardrail, the action decides: warn (the catalog's default), redact (flagged lines become
[REDACTED:prompt_injection]), block (the output is withheld), log. Venom Cloud can also send borderline text to
a classifier as a second opinion, when an org admin turns it on.
Supply-chain check
Before the agent adds or upgrades a dependency, each new package is checked (GR-ORG-TOOL-901), in every mode,
yolo included. It covers install commands (npm install <pkg>, pnpm add, yarn add, bun add, pip install,
uv add, poetry add, go get, go install mod@v, cargo add, cargo install) and edits to package.json,
requirements*.txt, pyproject.toml, go.mod and Cargo.toml.
| Signal | How it is found | Network |
|---|---|---|
| typosquat | one or two edits from a popular package's name, or two letters swapped | none |
| new package | first published fewer than minAgeDays days ago (default 7) |
the registry the install would use |
| install scripts | npm preinstall, install, postinstall or node-gyp; a PyPI release without a wheel |
registry |
| maintainer change | the npm version was published by someone who didn't maintain the previous one | registry |
Any signal turns the call into an approval prompt listing the evidence; the auto classifier never takes it, and
headless runs deny it. Lookups go only to the registry the install itself would contact (npm_config_registry or
.npmrc, the first GOPROXY URL, PIP_INDEX_URL or UV_INDEX_URL), are cached for ten minutes, and a failed lookup
leaves only the name check, so it works offline. An organisation policy can set
"supplyChain": {"action": "deny", "minAgeDays": 14, "registry": true}.
Troubleshooting
- A request fails with 403
guardrail_blocked. Open the URL in the error: it names the rule and who to ask. /guardrails offanswers 403. The rule isn't relaxable, or the key isn't your own personal key.- A local-only session can't find a model. A keep-local rule fired and no local upstream serves the request.
Related
- Red team: test the guardrails in force.
- Secrets vault
- Organisation policy
- The cloud section: the Guardrails page and admin API.