Project Guardian

Project Guardian — An AI Guardian Firewall for Autonomous Agents

> Status: working product, v0.1.0 released. Rust workspace, 196 tests green. > Implemented through Phase 4 (hardening): the deterministic policy engine, the > tamper-evident audit log (optionally sealed-key signed), the advisory Checker, > the MCP gateway + stdio transport, the daemon + control socket, the terminal > approval cockpit (TUI), the AgentDojo eval harness, the network proxy with TLS > interception (broker-injected credentials, exfiltration inspection, default-deny > egress, cockpit ask-routing), the OS exec sandbox, the token broker (OS > keychain + least-privilege caveats), lightweight verifiable credentials, > adaptive suggestions + safety report, ed25519-signed community policy > packs, and an intrinsic critical-category floor (money / credentials / > exfiltration / irreversible deletion can never resolve to a silent allow, not even > via a signed pack). Getting started: [docs/user-guide.md](docs/user-guide.md). > Remaining for 1.0: signed/notarized packaging and the desktop GUI — see > [ROADMAP.md](ROADMAP.md). > > Evaluation: on AgentDojo with a local 12B agent, Guardian cuts the prompt-injection > attack-success rate on the banking suite from 100% → 0% (deterministic deny on > money-movement). Our own [GuardianBench](evaluation/guardianbench/) — a benchmark > built for an action-firewall — scores 0% false-negatives, 0% false-positives, 100% > refusal-correctness across 8 domains, plus 0% PII leaks in its tokenization layer > (the data broker, ADR-0005). See [evaluation/](evaluation/) for the full, > honestly-caveated scorecard (including where an action-firewall's scope ends — below). > > 📄 White paper: [design & threat model (PDF)](docs/whitepaper.pdf) — or read it > [on GitHub](docs/whitepaper.md) (with diagrams of how it works and its impact on the agent). > > License: [Apache-2.0](LICENSE) · Governance: [CONTRIBUTING](CONTRIBUTING.md) · > [SECURITY](SECURITY.md) · [CODEOFCONDUCT](CODEOFCONDUCT.md) · [ADRs](docs/adr/) > > This README is the canonical spec (idea, full feature set, architecture, threat > model). For how and in what order it's built, see ROADMAP.md; for what's > landed, see docs/changelog.md.

---

> ## ⚠️ Disclaimer — use at your own risk > > Guardian is early-stage software (v0.1.0) that can be configured to handle > sensitive data (credentials, personal data, financial details). It is provided > "AS IS", without warranty of any kind, under the [Apache-2.0](LICENSE) license > (see Sections 7–8). To the maximum extent permitted by law, the author accepts no > liability for any damage, data loss, security breach, financial loss, or other > harm arising from the use, misuse, or inability to use this software. You are > solely responsible for evaluating its fitness for your purpose, for how you > configure your policy, and for the security of any data you route through it. It is > not certified, audited, or production-hardened, and must not be relied upon as > the sole safeguard for high-stakes or regulated workloads. See [SECURITY.md](SECURITY.md) > for the threat model and how to report a vulnerability.

---

1. What it is (one paragraph)

Guardian is a local, user-space "firewall" that sits between an autonomous AI agent and the things it can touch — your files, your shell, the network, and the online services you delegate to it. It does not trust the agent. Every action the agent attempts is intercepted as a structured action at the agent's tool/MCP boundary, evaluated by a deterministic policy engine, and — when a decision needs a human — explained in plain language by a separate "translator" model before you approve or deny it. Guardian is agent-agnostic (it does not care whether the agent is driven by Claude, GPT, Llama, or anything else) and OS-friendly (it never installs a kernel module or fights the operating system for control).

Quickstart

Fastest — download a prebuilt binary (no toolchain needed) from the latest release. It's unsigned, so the OS asks once: macOS → right-click → Open; Windows → SmartScreen → More info → Run anyway; Linux → chmod +x guardian. Then guardian --help. (Windows is experimental/untested — see [docs/user-guide.md](docs/user-guide.md).)

Set it up in one command. guardian init creates ~/.guardian/{config.toml,policy.toml} for your role and prints the exact next steps + the MCP snippet to paste:

guardian init                         # or: --role personal-assistant
guardian-daemon                       # terminal 1 — the service
guardian ui                           # terminal 2 — the approval cockpit (TUI)

Then point your agent's MCP client at Guardian (the snippet guardian init prints — works for Claude Code, Cursor, or any MCP client):

{
  "mcpServers": {
    "guardian": { "command": "guardian", "args": ["mcp", "--daemon", "/tmp/guardian.sock"] }
  }
}

When an action needs your approval the daemon raises a desktop notification, so you don't have to watch the cockpit (set notifications = false in the config to disable).

Or build from source — requires the Rust toolchain:

cargo build --release

# 1) see the traffic-light mediation end to end (scripted, no setup)
cargo run -p guardian-cli -- demo

# 2) the internal red-team scorecard (deterministic, no model needed)
cargo run -p guardian-cli -- eval
#    ...and GuardianBench, our action-firewall benchmark (FN 0% / FP 0% / refusal 100%):
GUARDIAN_BIN=target/release/guardian python3 evaluation/guardianbench/guardianbench.py

# 3) the full loop for a real agent — three terminals:
GUARDIAN_SOCK=/tmp/g.sock cargo run -p guardian-daemon       # the service
GUARDIAN_SOCK=/tmp/g.sock cargo run -p guardian-cli -- ui    # the approval cockpit (TUI)
# then point an MCP client (e.g. Claude Code) at:
#   guardian mcp --daemon /tmp/g.sock

Run the tests with cargo test --workspace. Measuring Guardian's effect on an agent's attack-success rate: [evaluation/](evaluation/).

---

2. The problem

Agents went from "chatbots that talk" to "agents that act" — they read and write files, run shell commands, browse, buy things, send email, and increasingly touch sensitive accounts (banking, health records, public-administration portals). That creates four concrete risks:

1. Sensitive-data exposure & destructive mistakes. Giving an agent direct

access to accounts, email, and private documents exposes the user to privacy violations, hallucinated destructive actions, and external attacks.

1. Prompt injection. The dominant agent-security threat of this era: content

the agent reads (a web page, a PDF, an email, a tool result) can contain instructions that hijack the agent into doing something the user never asked.

1. Click fatigue / informed-consent failure. System-level agents pop up

approval requests for scripts and API calls. Non-technical users do not understand them and approve everything blindly, which nullifies the safety.

1. No human-facing control surface and no traceability. Existing tooling

(raw harness permission prompts, Docker) is built for programmers. There is no intuitive "control room," and no easy way to keep a tamper-evident record of what an agent actually did (relevant for transparency obligations such as the EU AI Act, Art. 50).

---

3. Design principles (non-negotiable)

These are the rules that decide every later trade-off.

1. The security boundary is deterministic. The LLM is never the boundary.

Enforcement (allow / ask / deny) is done by a rule engine whose behavior is predictable and testable. An LLM can be wrong and can be attacked via prompt injection, so it is used only to translate and risk-score, never to unlock.

1. Intercept structured actions, not the agent's prose. The policy engine

and the translator look at the real intercepted action (the tool call and its arguments, the actual HTTP request, the file operation) — never at the agent's natural-language claim about what it intends to do. The claim is manipulable; the action is not.

1. Agent-agnostic by construction. Control is applied at the action boundary,

which is identical regardless of which model produced the action.

1. User-space, not kernel-space. No kernel modules, no OS hooks that require

vendor-granted entitlements. (See §4 — this is the central decision.)

1. Local-first / privacy-first. Policy evaluation, learning, and the audit

log live on the user's machine. Sending anything to the cloud is opt-in and explicit.

1. Defense in depth. Mediation at the tool boundary is the primary control;

OS sandboxing and a network proxy are containment backstops, not the plan A.

1. Fail closed on the critical path, fail open on convenience. A failure in

the money/credential/exfiltration path blocks; a failure in a low-risk path degrades gracefully (logs, defers to existing harness defaults).

1. Tamper-evident by default. Everything Guardian decides is written to an

append-only, hash-chained, signable audit log.

---

4. THE KEY DECISION: where Guardian acts

Resolved: Guardian acts at the agent's action boundary — the harness / tool-call / MCP layer — in user-space. It does NOT act in the OS kernel.

Why not the OS kernel / OS hooks

• Deep OS interception (Linux LSM/eBPF beyond user-space, macOS Endpoint Security

& Network Extension, Windows minifilter/WFP kernel callouts) requires vendor-granted entitlements, code-signing, notarization, and per-platform certification. On macOS and Windows this is a wall for an open-source project and a solo/community maintainer.

• Kernel-level bugs crash the user's machine. The blast radius of a mistake is

the whole OS.

• It is the wrong altitude: at the syscall level you see write(fd, buf, n), not

"the agent is about to wire €4,000 to an unknown IBAN." Intent is legible at the action boundary, not at the kernel.

Why the harness/action boundary is the right choke point

Modern agent harnesses (Claude Code, Cursor, the OpenAI Agents runtime, and any MCP-speaking client) already mediate everything the agent does through a tool-call interface. The agent cannot touch the world except by calling a tool the harness exposes. The harness is already the choke point — Guardian's job is to be, wrap, or plug into that mediation layer instead of fighting the OS for a second, redundant one.

This gives us, for free:

• Structured actions (tool name + typed arguments) instead of guessed intent.
• Agnosticism — the tool boundary looks the same under any model.
• No entitlements, no kernel, no notarization headaches.
• Cross-platform parity — the same logic runs on macOS, Windows, Linux.

The honest caveat (and how we handle it)

Harness-level interception is only as complete as the harness's own mediation. The hard case is a raw Bash/exec tool: once bash runs, its sub-behaviors (subprocesses, interpreters, raw syscalls, base64 -d | sh) are not individually mediated. Text-scanning the command is not a security boundary. We handle this with a layered answer:

1. Prefer structured tools over raw shell. Where the harness allows it, expose

mediated, typed tools (readfile, writefile, httprequest, sendemail) instead of a raw shell. Structured tools are fully policy-able.

1. Contain the dangerous tools. When raw exec/shell/network must exist,

run that tool's execution inside an off-the-shelf OS sandbox (container, sandbox-exec/Seatbelt profile, bubblewrap, Windows AppContainer/Sandbox) and inside a network proxy (below). This is defense-in-depth using existing, user-space tooling — not custom kernel work.

1. Mediate the network regardless. A user-space **forward proxy with an

installed CA** (mitmproxy-style) catches all HTTP(S) no matter how it was made, which is where network policy, header signaling, and content watermarking actually happen.

So the layered model is: mediate at the tool boundary (plan A) → contain high-risk tools in a sandbox + route all traffic through the proxy (backstop).

---

5. Architecture

            ┌──────────────────────────────────────────────────────────┐
            │  Agent (any model: Claude / GPT / Llama / local / …)        │
            └──────────────────────────────────────────────────────────┘
                               │  structured action (tool call / MCP / HTTP)
                               ▼
   ┌───────────────────────────────────────────────────────────────────────┐
   │                            GUARDIAN CORE                                 │
   │                                                                          │
   │  ┌────────────────────┐   ┌──────────────────────┐  ┌────────────────┐  │
   │  │ 1. POLICY ENGINE    │   │ 2. CHECKER (LLM)      │  │ 3. AUDIT LOG    │  │
   │  │ deterministic       │──▶│ translator + risk     │  │ append-only,    │  │
   │  │ allow / ask / deny  │   │ score — ADVISORY ONLY │  │ hash-chained,   │  │
   │  │ (the boundary)      │   │ never unlocks         │  │ signable        │  │
   │  └────────────────────┘   └──────────────────────┘  └────────────────┘  │
   │           │ "ask"                                                         │
   │           ▼                                                               │
   │  ┌────────────────────┐   ┌──────────────────────┐  ┌────────────────┐  │
   │  │ 4. APPROVAL UI      │   │ 5. IDENTITY & TOKEN   │  │ 6. ADAPTIVE     │  │
   │  │ traffic-light       │   │ BROKER: scoped OAuth, │  │ LEARNING        │  │
   │  │ dashboard + report  │   │ macaroons, keychain/  │  │ (constrained,   │  │
   │  │                     │   │ Secure Enclave/TPM    │  │ local only)     │  │
   │  └────────────────────┘   └──────────────────────┘  └────────────────┘  │
   └───────────────────────────────────────────────────────────────────────┘
        │ filesystem            │ network                 │ credentials
        ▼ structured FS tools   ▼ forward proxy (MITM CA) ▼ broker injects creds
          + optional sandbox      + header/watermark        at proxy; agent never
          for raw exec            injection                  sees raw secrets

5.1 Interception adapters (how Guardian plugs into a harness)

In priority order from most to least agnostic:

• (a) MCP gateway / proxy — primary, most agnostic. Guardian runs as an MCP

server that aggregates and re-exposes the user's real MCP servers and tools. The harness points at Guardian; every tools/call passes through the policy engine before being forwarded. Works with any MCP-speaking client.

• (b) Native hook adapter — for harnesses with a hook system (e.g. Claude

Code's PreToolUse/PostToolUse). Guardian registers as the hook handler and returns allow/ask/deny per call. Lowest friction where available; gives a true deterministic deny.

• (c) HTTP(S) forward proxy — a user-space CONNECT proxy with a locally

installed CA. Intercepts all outbound traffic for network policy, the agent-signaling header, and content watermarking. This is the only "system-ish" piece and it is still pure user-space (a proxy + a trusted cert).

• (d) LLM gateway proxy — optional. Proxy the model API itself to capture the

raw request/response, strip injected instructions from tool results, and attach provenance. Useful but not required for MVP.

5.2 Policy engine (the actual boundary)

• Deterministic evaluation of declarative rules → exactly one of allow / ask /

deny per action.

• Conditions over structured field

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Vadale
• Source: Vadale/project-guardian
• License: Apache-2.0

Install and usage instructions live in the source repository linked above.