agent-guardrail
About
Deterministic policy firewall for AI agents that evaluates tool calls before execution and returns ALLOW, WARN, or BLOCK decisions.
Details
- Author
- rudimentall1
- Categories
- Other
Jump to
Setup
Install agent-guardrail in your MCP client (Claude Desktop, Cursor, Windsurf, and others).
Repository: https://github.com/rudimentall1/agent-guardrail
Follow the installation instructions in the repository README, then restart your MCP client.
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.
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"}'
Orpip install guardrail-mcpgives you aguardrailcommand directly — same output, no repo checkout required (falls back to the policy bundled in the package if you don't point--policyat 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.yamlis 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 alsonot blockchain-specific. Shell execution, email, HTTP requests, file deletion, database writes, crypto transactions — same engine, same policy file, same rules.
Shown above. No setup, instant feedback while you write rules.
2. MCP server (mcp_server.py) — the easy on-ramp, advisory
Exposesguardrail_check,guardrail_record_outcome, andguardrail_agent_historyas 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 callguardrail_checkbefore 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). Runpython3 examples/example_agent_usage.pyto see it block a real function call.
Getting a human to actually confirm a WARN
on_warnis 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 (failsclosed— 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 openhttp://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_warnis just a function(decision) -> bool, so a Slack message, a ticket, or anything else you already use works too.
Policies are plain YAML — seepolicies/default.yamlfor a real, working starting point (11 confirmation-gated tools, 10 destructive-pattern checks, numeric caps, domain rules, rate limits, all commented).
No code changes needed to adjust any of this — edit the YAML, restart the process (or the MCP server).
pip install -r requirements.txt PYTHONPATH=. python3 -m unittest discover -s tests -v
46 tests: rule evaluation, the full engine pipeline (real SQLite-backed rate limiting and audit persistence), theenforcedecorator (proving aBLOCKgenuinely prevents the wrapped function from running), the hand-rolled MCP server's JSON-RPC handling over an actual stdio pipe, the confirmation web UI over real HTTP requests against a live server, and a dedicated suite that checks theshippedpolicies/default.yaml— not just synthetic test policies — actually catches what it claims to.
- Single-process SQLite by default.Fine for one agent process; for multiple replicas sharing rate limits/audit history, point every process at the same file on shared storage, or swap in a real database (the storage classes are small and easy to re-target).
- Secrets/PII redaction in the audit log is on by default.AuditLogredacts values whose key looks sensitive (password,api_key,authorization, ...) and a couple of high-confidence value shapes (PEM private key blocks, JWT-shaped strings) regardless of key name, recursing into nested dicts/lists - seeguardrail/storage/redaction.pyfor exactly what is and isn't caught, and why general-purpose entropy heuristics were deliberately left out (too many false positives on ordinary UUIDs/hashes). PassAuditLog(redact=False)to store arguments as-submitted, orextra_sensitive_keys={...}to redact additional field names specific to your tools.
- The default policy is a reasonable starting point, not a complete threat model.It catches well-known destructive shell/SQL patterns and obvious credential formats — extendargument_patternsfor whatever your agents actually touch.
- The confirmation web UI has no auth.It binds to127.0.0.1by design (not exposed on the network), but anyone with local access to that port can approve/reject. Fine for a single developer's machine; put it behind your own auth if multiple people share the host.
None of these are mocked or faked — they're just not built yet, and they're the honest next steps if you adopt this.
Publishing this / getting people to actually use it
SeePUBLISHING.mdfor a concrete checklist: MCP directories to submit to, what a listing needs, and what "done" looks like.
Same author, same principle applied elsewhere:
- agentic-wallet-guardian-v3- a security decision layer for AI agents transacting on-chain. MIT, 112 tests.
- x402-attest- cryptographically signed (Ed25519), independently verifiable attestations for agent-to-agent payment policy decisions. Early proof of concept.
- open-agent-attestation- vendor-neutral open spec (JWT+EdDSA) for signing agent policy decisions, verifiable by anyone. x402-attest above uses a custom format; this is the generalized version. Draft v0.1.
guardrail/ __main__.py CLI implementation — also the guardrail console command mcp_server.py MCP stdio server — also the guardrail-mcp-server console command core/ models.py ActionRequest, RuleMatch, GuardrailDecision (stdlib only) policy.py Policy loader (the one place PyYAML is used) rules.py Deterministic rule evaluators storage/ rate_limiter.py SQLite-backed sliding-window rate limiter audit.py SQLite-backed persistent audit log engine.py GuardrailEngine — orchestrates rules + rate limit + audit decorator.py enforce() — the unbypassable integration point confirmation/ web_ui.py Local web UI for human approve/reject (stdlib http.server) cli_ui.py Terminal-prompt confirmation policies/default.yaml Copy of the default policy bundled into the installed package policies/default.yaml Canonical, editable default policy (git-clone workflow) cli.py Thin shim -> guardrail/__main__.py (for python3 cli.py) mcp_server.py Thin shim -> guardrail/mcp_server.py (for python3 mcp_server.py) pyproject.toml Package metadata — pip install . gives you guardrail + guardrail-mcp-server .github/workflows/ci.yml Runs the test suite + policy validation + package build on every push examples/ example_agent_usage.py Decorator basics example_web_confirmation.py Real browser-based approve/reject, live tests/ 46 unit tests, all runnable with just PyYAML installed CONTRIBUTING.md How to add a rule type, ground rules CHANGELOG.md Version history PUBLISHING.md How to actually get this in front of people landing/index.html Static one-page site (open directly or host on GitHub Pages)
Transaction-complete hotel booking over MCP — 300K+ properties, real hotel confirmation numbers, loyalty points, secure checkout. Hotels are merchant of record. Builders set their own booking fee via Stripe Connect. Built on proven distribution infrastructure.
An MCP server for AI video generation. MCP server for AI video generation. Lets Claude, ChatGPT, OpenClaw , Hermes & other agents create AI videos and publish them to YouTube, TikTok, Instagram etc..
Institutional research and manager diligence reports on hedge funds, venture capital and private equity managers. Summary of filings, personnel changes, media screening and social signals delivered to you in minutes.
ALTER - identity infrastructure for the AI economy
D2C eCommerce fulfillment platform: manage orders, inventory, shipments, campaigns, and billing via AI agents
Apigene MCP Gateway is the runtime layer that connects AI agents to APIs and MCP servers via Model Context Protocol.
MCP to interface with multiple blockchains, staking, DeFi, swap, bridging, wallet management, DCA, Limit Orders, Coin Lookup, Tracking and more.
MCP server for Bitnovo Pay integration with AI agents. Provides cryptocurrency payment capabilities through Bitnovo Pay API. Features include payment creation, status checking, QR code generation, and webhook management with support for multiple tunnel providers (ngrok, zrok, manual).
Shop for gift cards, esims, phone topups. Pay with cards and crypto.
You built it, now get users! GoToMarket MCP server
Sign in to leave a review
Use Google, GitHub, or an email account so ratings stay tied to real people.
No reviews posted yet.
