MCP Guard

Runtime security proxy for MCP servers and AI agents. Inspects tool calls before they execute, blocks command injection, path traversal, SSRF, tool poisoning, and rug-pull attacks. Hash-chained audit trail.

cargo install --git https://github.com/InnerWarden/mcp-guard

How it works

MCP Guard sits between AI agents and MCP servers as a transparent proxy. Every tool call is inspected against security rules before reaching the server.

Agent (Claude, Cursor, etc.)
  │
  ▼
┌─────────────┐
│  MCP Guard  │ ← inspect + block + audit
└─────────────┘
  │
  ▼
MCP Server (filesystem, database, API, etc.)

Stdio mode (wrap an MCP server):

mcp-guard --upstream-cmd "npx @modelcontextprotocol/server-filesystem /home/user"

TCP mode (proxy to a remote MCP server):

mcp-guard --listen 127.0.0.1:3100 --upstream tcp://localhost:3200

Built-in rules

ID	Rule	Action	Severity
MG-01	Command injection in tool arguments	Block	Critical
MG-02	Path traversal in tool arguments	Block	Critical
MG-03	SSRF in tool arguments	Block	High
MG-04	Hidden/zero-width characters in tool description	Alert	High
MG-05	Tool description changed (rug-pull detection)	Block	Critical
MG-06	Encoded payload in tool arguments	Alert	Medium
MG-07	Prompt injection markers in tool response	Sanitize	High
MG-08	Tool call rate limit	Block	Medium

What it detects

Command injection — semicolons, backticks, $(), pipes to shells, eval(), exec(), system(), file redirects to sensitive paths.

Path traversal — ../, /etc/passwd, /etc/shadow, ~/.ssh/, /proc/self/, URL-encoded variants.

SSRF — localhost, 0.0.0.0, 169.254.169.254 (cloud metadata), private networks (10.x, 172.16-31.x, 192.168.x), file://, gopher://.

Tool poisoning — zero-width characters (U+200B, U+200C, U+200D, U+FEFF, tag characters U+E0001-E007F), soft hyphens, invisible Unicode used for ASCII smuggling.

Rug-pull — SHA-256 hash of tool descriptions on first use. If a tool's description changes silently, it's blocked and flagged.

Encoded payloads — Base64 strings containing shell commands (bash, /bin/sh, curl, wget, eval, exec).

Prompt injection in responses — [INST], [/INST], <|im_start|>, <<SYS>>, Human:, System: role markers are sanitized from tool outputs.

Configuration

Copy guard.toml and customize:

[allowlist]
tools = ["read_file", "search"]
paths = ["/home/user/projects/"]
networks = ["api.github.com"]

[audit]
dir = "./data/audit"
retention_days = 90
hash_chain = true

[[rules]]
id = "CUSTOM-01"
name = "Block dangerous tool"
target = "tool_name"
action = "block"
severity = "critical"
[rules.condition]
type = "contains"
value = "exec"

Rule conditions

Condition	Description
command_injection	Detects shell injection patterns
path_traversal	Detects directory traversal
ssrf	Detects internal network access
hidden_chars	Detects zero-width/invisible Unicode
description_changed	Detects rug-pull (tool description modified)
encoded_payload	Detects Base64 shell commands
not_in_allowlist	Tool name not in allowed list
rate_limit	Calls exceed max_per_minute
pattern	Custom regex match
contains	Case-insensitive string match

Actions

Action	Behavior
block	Return JSON-RPC error, tool call never reaches the server
alert	Allow but log as security alert
sanitize	Strip matched content and pass through
human_approval	Pause and require human confirmation (planned)

Audit trail

All blocked and alerted actions are logged to data/audit/audit-YYYY-MM-DD.jsonl with a SHA-256 hash chain for tamper detection:

{
  "ts": "2026-03-28T15:30:00.000Z",
  "tool_name": "run_command",
  "direction": "request",
  "allowed": false,
  "rules_triggered": [
    {
      "id": "MG-01",
      "severity": "Critical",
      "detail": "shell command after semicolon: '; cat /etc/passwd'"
    }
  ],
  "prev_hash": "a1b2c3...",
  "hash": "d4e5f6..."
}

Audit-only mode

Start with --audit-only to log without blocking. Useful for evaluating rules before enforcing:

mcp-guard --audit-only

Roadmap

• Stdio subprocess mode (spawn and wrap MCP server process)
• Human approval workflow (pause tool call, ask user)
• Cross-server correlation (detect orchestration attacks)
• Tool inventory baseline (detect new/unknown tools)
• Integration with InnerWarden (kernel-level observation of tool call effects)
• Web dashboard for audit trail visualization

From the InnerWarden project

MCP Guard is part of the InnerWarden ecosystem. While InnerWarden protects servers at the kernel level (eBPF, LSM), MCP Guard protects AI agent interactions at the protocol level.

License

MIT