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 │
└──────────────────┘ └──────────────────┘
-
The Brain (In-Context Guidance - skills/):
-
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.
This is the beginning of the README. Read the rest at the original. Read the full README ↗
