Skip to content
Docs menu

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.

View .md

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. --sudo settles 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 off answers 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.