---
title: Guardrails
description: 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.
section: security
order: 60
audience: [user, operator, builder, agent]
sources: [docs/guardrails.md, packages/harness/src/guardrails, packages/harness/src/injection, packages/harness/src/supplychain, cli/src/guardrails-command.ts, services/nodejs-cloud/contracts/guardrail-catalog.json, services/nodejs-cloud/contracts/injection-rules.json]
features: [security.guardrails]
---

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 {#quick-start}

In the CLI, offline too, from `venom.yaml`:

```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 {#kinds}

| 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 {#config}

| 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 {#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](#supply-chain) |
| `GR-ME-CRED-900` | the [secrets vault](/docs/security/secrets.md#refusals) 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 {#wire}

Detection happens at the gateway, so guardrails hold for any client, plain OpenAI SDK calls included. A block is a
403:

```http
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 {#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 {#injection}

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 {#supply-chain}

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

## Related {#related}

- [Red team](/docs/security/redteam.md): test the guardrails in force.
- [Secrets vault](/docs/security/secrets.md)
- [Organisation policy](/docs/security/policy.md)
- [The cloud section](/docs/cloud.md): the Guardrails page and admin API.
