# Project Guardian > AI Guardian Firewall — a local, user-space, agent-agnostic firewall that mediates an autonomous AI agent's actions (files, shell, network, services) with a deterministic policy boundary, a tamper-evident audit log, and a human-in-the-loop approval cockpit. No kernel modules. Apache-2.0. - **Type:** MCP server - **Install:** `agentstack add mcp-vadale-project-guardian` - **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior - **Seller:** [Vadale](https://agentstack.voostack.com/s/vadale) - **Installs:** 0 - **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml) - **Latest version:** 0.1.0 - **License:** Apache-2.0 - **Upstream author:** [Vadale](https://github.com/Vadale) - **Source:** https://github.com/Vadale/project-guardian ## Install ```sh agentstack add mcp-vadale-project-guardian ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About # 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) · [CODE_OF_CONDUCT](CODE_OF_CONDUCT.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](https://github.com/Vadale/project-guardian/releases/latest). 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: ```sh 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): ```json { "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](https://rustup.rs): ```sh 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. 2. **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. 3. **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. 4. **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. 2. **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. 3. **Agent-agnostic by construction.** Control is applied at the action boundary, which is identical regardless of which model produced the action. 4. **User-space, not kernel-space.** No kernel modules, no OS hooks that require vendor-granted entitlements. (See §4 — this is the central decision.) 5. **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. 6. **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. 7. **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). 8. **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 (read_file, write_file, http_request, send_email) instead of a raw shell. Structured tools are fully policy-able. 2. **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. 3. **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](https://github.com/Vadale) - **Source:** [Vadale/project-guardian](https://github.com/Vadale/project-guardian) - **License:** Apache-2.0 Install and usage instructions live in the source repository linked above. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** no - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** no - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: passed — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/mcp-vadale-project-guardian - Seller: https://agentstack.voostack.com/s/vadale - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.