mcp-vanguard 1.5.0

Security proxy and verification layer for the Model Context Protocol (MCP)

🛡️ McpVanguard

A security proxy for AI agents that use MCP

MCP (Model Context Protocol) lets AI agents like Claude or GPT call tools on your computer — reading files, running commands, browsing the web. McpVanguard sits in between, inspecting every tool call before it reaches your system and blocking anything that looks malicious.

No changes to your agent. No changes to your server. Just wrap it.

Part of the Provnai Open Research Initiative — Building the Immune System for AI.

---

⚡ Quickstart

pip install mcp-vanguard

Local stdio wrap (no network):

vanguard start --server "npx @modelcontextprotocol/server-filesystem ."

Cloud Security Gateway (SSE, deploy on Railway):

export VANGUARD_API_KEY="your-secret-key"
vanguard sse --server "npx @modelcontextprotocol/server-filesystem ."

📖 Full Railway Deployment Guide

---

🧠 How it works

Every time an AI agent calls a tool (e.g. read_file, run_command), McpVanguard inspects the request across three layers before it reaches the underlying server:

Layer	What it checks	Latency
L1 — Safe Zones & Rules	Kernel-level isolation (openat2 / Windows canonicalization) and 50+ deterministic signatures	~16ms
L2 — Semantic	LLM-based intent scoring for ambiguous requests	Async
L3 — Behavioral	Shannon Entropy ($H(X)$) scouter and sliding-window anomaly detection	Stateful

On latency: 16ms is the overhead at peak concurrent load. In practice it's well under the 1–2 second LLM response time — imperceptible to the agent.

If a request is blocked, the agent receives a standard JSON-RPC error response. The underlying server never sees it.

---

🛡️ What gets blocked

• Sandbox Escapes: TOCTOU symlink attacks, Windows 8.3 shortnames (PROGRA~1), DOS device namespaces
• Data Exfiltration: High-entropy payloads (H > 7.5 cryptographic keys) and velocity-based secret scraping
• Filesystem attacks: Path traversal (../../etc/passwd), null bytes, restricted paths (~/.ssh), Unicode homograph evasion
• Command injection: Pipe-to-shell, reverse shells, command chaining via ; && \n, expansion bypasses
• Network abuse: SSRF, cloud metadata endpoints (AWS/GCP/Azure), hex/octal encoded IPs
• Prompt injection: Jailbreak patterns, instruction-ignore sequences, hidden unicode characters
• Privilege escalation: SUID binary creation, LD_PRELOAD injection, crontab manipulation

---

📊 VEX Protocol — Immutable Audit Log

When McpVanguard blocks an attack, it creates an OPA/Cerbos-compatible Secure Tool Manifest detailing the Principal, Action, Resource, and environmental snapshot.

This manifest is then sent as a cryptographically-signed report to the VEX Protocol. VEX anchors that report to the Bitcoin blockchain via the CHORA Gate.

This means an auditor can independently verify exactly what was blocked, the entropy score, and why — without relying on your local logs.

export VANGUARD_VEX_URL="https://api.vexprotocol.com"
export VANGUARD_VEX_KEY="your-agent-jwt"
vanguard sse --server "..." --behavioral

---

🏗️ Architecture

                      ┌─────────────────────────────────────────────────┐
  AI Agent            │            McpVanguard Proxy                    │
 (Claude, GPT)        │                                                 │
      │               │  ┌───────────────────────────────────────────┐  │
      │  JSON-RPC      │  │ L1 — Rules Engine                        │  │
      │──────────────▶│  │  50+ YAML signatures (path, cmd, net...)  │  │
      │  (stdio/SSE)   │  │  BLOCK on match → error back to agent    │  │
      │               │  └────────────────┬──────────────────────────┘  │
      │               │                   │ pass                         │
      │               │  ┌────────────────▼──────────────────────────┐  │
      │               │  │ L2 — Semantic Scorer (optional)           │  │
      │               │  │  Ollama / OpenAI intent scoring 0.0→1.0   │  │
      │               │  │  Async — never blocks the proxy loop      │  │
      │               │  └────────────────┬──────────────────────────┘  │
      │               │                   │ pass                         │
      │               │  ┌────────────────▼──────────────────────────┐  │
      │               │  │ L3 — Behavioral Analysis (optional)       │  │
      │               │  │  Sliding window: scraping, enumeration    │  │
      │               │  │  In-memory or Redis (multi-instance)      │  │
      │               │  └────────────────┬──────────────────────────┘  │
      │               │                   │                              │
      │◀── BLOCK ─────│───────────────────┤ (any layer)                 │
      │  (JSON-RPC    │                   │ ALLOW                        │
      │   error)      │                   ▼                              │
      │               │           MCP Server Process                     │
      │               │        (filesystem, shell, APIs...)              │
      │               └──────────────────┬──────────────────────────────┘
      │                                  │
      │◀─────────────── response ────────┘
      │
      │   (on BLOCK)
      └──────────────▶ VEX API ──▶ CHORA Gate ──▶ Bitcoin Anchor
                       (async, fire-and-forget audit receipt)

---

🗺️ Project Status

Phase	Goal	Status
Phase 1	Foundation (Proxy, CLI, Defensive Rules)	✅ Done
Phase 2	Intelligence (L2 Semantic, L3 Behavioral)	✅ Done
Phase 3	Flight Recorder (VEX & CHORA Integration)	✅ Done
Phase 4	Distribution (stable PyPI release)	✅ Done
Phase 5	Production Hardening (v1.1.3 stability)	✅ Done
Phase 6	Security Audit Remediation (v1.1.4 hardening)	✅ Done
Phase 7	Titan-Grade L1 Perimeter (v1.5.0 Forensic Hardening)	✅ Done
Phase 8	Agent Identity & VEX v0.2 Spec	🔄 In Progress

---

📚 Resources

• Deployment Guide
• Architecture
• Contributing
• Ecosystem Report

---

📄 License

Apache License 2.0 — see LICENSE.

Built by the Provnai Open Research Initiative. "Verifying the thoughts and actions of autonomous agents."