Guardrail

📄 Read the white paper

A policy firewall for AI agent tool calls.

Your agent wants to run a shell command, send an email, or move money. Guardrail checks that request against rules you wrote, before it happens, and either lets it through, asks a human, or blocks it — with a plain- English reason every time.

60-second quickstart

git clone <this repo> && cd agent-guardrail
pip install -r requirements.txt

python3 cli.py check --agent trading-agent-001 --tool wallet.transfer \
  --args '{"amount": 9999, "to": "0xabc"}'

Or pip install guardrail-mcp gives you a guardrail command directly — same output, no repo checkout required (falls back to the policy bundled in the package if you don't point --policy at your own file):

guardrail check --agent trading-agent-001 --tool wallet.transfer \
  --args '{"amount": 9999, "to": "0xabc"}'

{
  "decision": "BLOCK",
  "matched_rules": [
    {"rule": "numeric_cap_exceeded", "severity": "BLOCK",
     "message": "amount=9999.0 exceeds cap 5 for 'wallet.transfer' (unknown agent)"}
  ]
}

That's it — no server, no account, no API key. policies/default.yaml is the file that decided this; open it and change the numbers to match your own rules.

Why this, not another "AI risk scoring" tool

Most "AI agent security" projects (including an earlier project of mine) lean on statistical risk scores computed from data nobody can actually verify at build time — wallet age, "reputation," contract "risk" — which either requires paid data feeds you don't have yet, or quietly becomes mock data pretending to be real. Fine for prototyping, dishonest to ship.

Guardrail only makes claims it can back up. Every check is a deterministic rule — a blocklist entry, a regex match, a numeric cap, a rate limit — evaluated against a policy file you write and can audit yourself, backed by a real, persistent audit log (SQLite) you can query. Nothing here pretends to know something it doesn't.

It's also not blockchain-specific. Shell execution, email, HTTP requests, file deletion, database writes, crypto transactions — same engine, same policy file, same rules.

Four ways to use it

1. CLI — for testing a policy by hand

Shown above. No setup, instant feedback while you write rules.

2. MCP server (mcp_server.py) — the easy on-ramp, advisory

Exposes guardrail_check, guardrail_record_outcome, and guardrail_agent_history as MCP tools any MCP-compatible agent (Claude Desktop, Claude Code, custom MCP clients) can call.

{
  "mcpServers": {
    "guardrail": {
      "command": "python3",
      "args": ["/absolute/path/to/agent-guardrail/mcp_server.py"],
      "env": { "GUARDRAIL_POLICY": "/absolute/path/to/agent-guardrail/policies/default.yaml" }
    }
  }
}

Then tell your agent (in its system prompt) to always call guardrail_check before spending money, deleting data, messaging someone externally, or running code.

Be clear-eyed about its limit: like any MCP tool, nothing stops the calling model from just not invoking it. This only helps if the agent is instructed to always check first — for a guarantee it can't skip, see #3.

3. guardrail.decorator.enforce — the real guarantee

Wraps the actual Python function that performs a tool's side effect. The check runs in your code, before that function executes — the model never gets a chance to call the real function directly.

from guardrail.decorator import enforce, BlockedActionError

@enforce(engine, tool_name="send_email")
def send_email(agent_id: str, to: str, subject: str, body: str):
    ...  # only runs if the decision is ALLOW, or WARN-and-confirmed

Use this if you're building your own agent loop (LangChain, CrewAI, a custom MCP host, a Slack bot with tool access). Run python3 examples/example_agent_usage.py to see it block a real function call.

4. guardrail.mcp_enforced_server.EnforcedGuardrailMCPServer — the real guarantee, over MCP

The MCP server in #2 above is honest about being advisory: the model gets a guardrail_check tool, but nothing stops it from calling the actual tool (exposed by some other MCP server, or by the model's own direct access) without checking first, or checking one thing and doing another. If the model talks to your infrastructure only over MCP - no Python decorator possible - this is the same #3 guarantee for that case: the operator registers real action executors (the code that holds real credentials and performs the real side effect) as the only way the model can invoke that action at all.

from guardrail.mcp_enforced_server import EnforcedGuardrailMCPServer

def do_transfer(request):
    wallet = get_wallet_for(request.agent_id)  # real credentials, held here - never exposed to the model
    tx_hash = wallet.transfer(to=request.arguments["to"], amount=request.arguments["amount"])
    return {"tx_hash": tx_hash}

server = EnforcedGuardrailMCPServer(policy_path="policies/default.yaml")
server.register_action(
    "wallet.transfer", "Transfer funds from the agent's wallet.",
    input_schema={"type": "object", "properties": {"to": {"type": "string"}, "amount": {"type": "number"}}, "required": ["to", "amount"]},
    executor=do_transfer,
)
server.serve_stdio()

The model is given exactly one MCP tool named wallet.transfer - there is no separate, unguarded way to move funds through this server. A BLOCK decision means do_transfer never runs. Both this and enforce() share one implementation of "check, maybe route WARN to a human, run only if not blocked, report the real outcome back" (guardrail/enforcement.py) - not two independently-maintained copies of the same guarantee.

Getting a human to actually confirm a WARN

on_warn is the hook — Guardrail ships two ready-made implementations:

Local web UI (guardrail/confirmation/web_ui.py) — a tiny built-in server (stdlib only, no Flask) with Approve/Reject buttons. The wrapped function blocks until someone clicks one, or times out (fails closed — timeout means reject, not "allow by default").

from guardrail.confirmation.web_ui import ConfirmationServer

confirmation = ConfirmationServer(port=8787, timeout_seconds=300)
confirmation.start(open_browser=True)

@enforce(engine, tool_name="wallet.transfer", on_warn=confirmation.request_confirmation)
def transfer(...): ...

Try it live: python3 examples/example_web_confirmation.py, then open http://localhost:8787.

Terminal prompt (guardrail/confirmation/cli_ui.py) — for scripts and local testing where a browser is overkill:

from guardrail.confirmation.cli_ui import cli_confirm

@enforce(engine, tool_name="wallet.transfer", on_warn=cli_confirm)
def transfer(...): ...

Neither is required — on_warn is just a function (decision) -> bool, so a Slack message, a ticket, or anything else you already use works too.

Writing a policy

Policies are plain YAML — see policies/default.yaml for a real, working starting point (11 confirmation-gated tools, 10 destructive-pattern checks, numeric caps, domain rules, rate limits, all commented).

numeric_caps limits each tool independently — wallet.transfer capped at 1000/day and wallet.approve capped at 1000/day separately means an agent using both can still move 2000/day combined. aggregate_caps closes that: every tool listed in the same group draws from one shared running total, e.g.

aggregate_caps:
  daily_money_movement:
    tools:
      wallet.transfer: amount
      wallet.approve: amount
    window_seconds: 86400
    max_unknown_agent: 5
    max_known_agent: 1000

Only confirmed spend counts toward the total: a BLOCKed request never adds anything, and a request that's provisionally recorded (because its own check passed) is refunded if the real action later turns out not to have succeeded — engine.record_outcome(request_id, "error"), called automatically by both enforce() and the enforced MCP server (they share one implementation of this, guardrail/enforcement.py) when the real executor raises, or when a WARN a human rejects results in a BlockedActionError. Real enforcement of this therefore has the same caveat as everything else that depends on record_outcome being called: it works fully under enforce() and the enforced MCP server (see below); under the advisory-only MCP server (#2 above), a provisionally-recorded amount just stays recorded, since nothing ever reports back whether the action actually happened. See guardrail/storage/aggregate_spend.py's module docstring for the full picture.

No code changes needed to adjust any of this — edit the YAML, restart the process (or the MCP server).

Running the tests

pip install -r requirements.txt
PYTHONPATH=. python3 -m unittest discover -s tests -v