McpVanguard

A security proxy for AI agents that use MCP

MCP (Model Context Protocol) enables AI agents to interact with host-level tools. McpVanguard interposes between the agent and the system, provide real-time inspection and enforcement prefixing every tool call.

Transparent integration. Zero-configuration requirements for existing servers.

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 via OpenAI, MiniMax, or Ollama	Async
L3 — Behavioral	Shannon Entropy ($H(X)$) scouter and sliding-window anomaly detection	Stateful

Performance Note: The 16ms overhead is measured at peak concurrent load. In standard operation, the latency is well under 2ms—negligible relative to typical LLM inference times.

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 — Deterministic 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)           │  │
      │               │  │  OpenAI / MiniMax / Ollama 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)

---

L2 Semantic Backend Options

The Layer 2 semantic scorer supports three LLM backends. Set the corresponding API key to activate a backend — the first available key wins (priority: OpenAI > MiniMax > Ollama):

Backend	Env Vars	Notes
OpenAI	VANGUARD_OPENAI_API_KEY, VANGUARD_OPENAI_MODEL	Default model: gpt-4o-mini
MiniMax	VANGUARD_MINIMAX_API_KEY, VANGUARD_MINIMAX_MODEL, VANGUARD_MINIMAX_BASE_URL	Default model: MiniMax-M2.5 (204K context). Also available: MiniMax-M2.5-highspeed. API docs
Ollama (local)	VANGUARD_OLLAMA_URL, VANGUARD_OLLAMA_MODEL	Default model: phi4-mini. No API key required

# Example: use MiniMax as semantic backend
export VANGUARD_SEMANTIC_ENABLED=true
export VANGUARD_MINIMAX_API_KEY="your-minimax-key"
vanguard start --server "npx @modelcontextprotocol/server-filesystem ."

---

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."