agent-guardrails

Enterprise AI Agent Guardrails Toolkit: Governance-as-Code for Autonomous Coding & Tool-Calling Agents.
Zero external pip dependencies. Apache 2.0. Built for Claude Code, Cursor, Antigravity, OpenHands, and custom agent harnesses.
Created by Charitarth Bharti (safeaiguy.com).
Overview page: charitarth1.github.io/agent-guardrails

Guardrails built from first principles and refined through adversarial self-audits to run AI agents safely on developer machines and CI/CD pipelines without handing them the keys.

---

Security Model: Tripwire, Not a Sandbox

[!WARNING] Pattern-based hooks are tripwires, not security boundaries. A deterministic regex filter or PreToolUse hook running as the same OS user as the agent cannot withstand an active, malicious adversary who has arbitrary shell execution capabilities. If the agent can execute arbitrary Python or shell commands, it can inspect its own environment, read local files, or kill unprivileged parent processes.

True security confinement requires operating-system level isolation: running the agent in a rootless container (Docker/Podman), an isolated VM (Firecracker/gVisor), or a dedicated unprivileged user account without access to host secrets or network interfaces.

agent-guardrails is designed as a tripwire against accidental mutations, naive prompt injections, and inadvertent data leakage, and as a structured governance framework for enterprise compliance (NIST AI RMF, ISO/IEC 42001, GovTech ARC). Read docs/limitations.md before deploying in untrusted environments.

---

The Dual-Engine Architecture

A robust agent governance architecture cannot rely solely on prompt engineering (which fails under indirect injection) nor purely on external network firewalls (which cannot inspect tool semantics). This toolkit implements the Dual-Engine Model:

┌──────────────────────────────────────────────────────────┐
│             THE DUAL-ENGINE GOVERNANCE SYSTEM            │
└──────────────────────────────────────────────────────────┘
                           │
         ┌─────────────────┴─────────────────┐
         ▼                                   ▼
┌──────────────────┐               ┌──────────────────┐
│    THE BRAIN     │               │    THE BRAKES    │
│ (In-Context)     │               │ (Deterministic)  │
├──────────────────┤               ├──────────────────┤
│ Downloadable     │               │ PreToolUse Hook  │
│ Agent Skills     │               │ Runtime Engine   │
│ (`skills/`)      │               │ (`src/`)         │
├──────────────────┤               ├──────────────────┤
│ • Blast-Radius   │               │ • 4-Tier DLP     │
│   Calculation    │               │ • Nonce Fencing  │
│ • Safe TDD Gates │               │ • Out-of-Band    │
│ • Proactive      │               │   HMAC Gate      │
│   Self-Auditing  │               │ • SHA-256 Chain  │
└──────────────────┘               └──────────────────┘

1. The Brain (In-Context Guidance - skills/):

   • Downloadable agent skill packages conforming to modern SKILL.md specifications.
   • Teaches agents self-governance: blast radius surface triage, safe mutation tiers, mandatory TDD verification before claiming bugfixes, and terminal clearance workflows.
   • Single-command vendoring directly into your favorite agent harness:

     guardrails vendor-skills --target claude-code   # installs to .claude/skills/
     guardrails vendor-skills --target cursor        # installs to .cursor/rules/
     guardrails vendor-skills --target antigravity   # installs to .gemini/antigravity/skills/
     

2. The Brakes (Deterministic Runtime Firewalls - src/):

   • Hard, fail-closed enforcement at the tool-call boundary (Exit Code 2 = BLOCK; 0 = ALLOW).
   • Operates before terminal execution or API calls occur.
   • Operates independently of model context; does not rely on model self-policing.

---

以上为 README 的开头部分。其余内容请阅读原文。 查看完整 README ↗