MCPGuard-Lab

A security experiment project for MCP tool invocation based on the real mcp==2.0.0 SDK. It does not rely on external large models or API keys, and implements tool whitelisting, parameter validation, file boundary enforcement, SSRF protection, sensitive operation confirmation, output sanitization, tool description poisoning detection, and JSONL auditing through deterministic policies. Regression test cases verify that protections are not broken by subsequent changes.

Usage boundary: This project is intended only for local experimentation, authorized testing, and defense research. It does not include attack functionality against unauthorized targets.

Implemented Capabilities

• MCP 2.0 stdio server and real client round-trip testing.

• Six demonstration tools: safe calculation, file reading within root directory, note query, public URL request, tool metadata inspection, and write note after confirmation.

• Tool whitelist and strict JSON Schema validation, rejecting extra parameters.

• File path normalization, rejecting absolute paths, directory traversal, and root directory escape.

• URL protocol, user info, port, and DNS resolution result checks, rejecting loopback, private network, link-local, and other non-public addresses.

• Write operation confirmed=true gate.

• Explicit labeling of untrusted tool outputs; recursive sanitization of passwords, tokens, API keys, and Bearer credentials.

• High-risk prompt injection signal detection in tool names/descriptions.

• Each decision written to JSONL: request ID, time, tool, parameters, allow/deny, reason, and result.

• pytest unit/integration tests and reproducible attack regression reports.

Related MCP server: meok-mcp-injection-scan-mcp

Architecture

MCP Client
   │ stdio / MCP 2.0
   ▼
MCP Server ──► GuardedGateway ──► PolicyEngine
                      │                 ├─ allowlist + schema
                      │                 ├─ path boundary
                      │                 ├─ URL / SSRF
                      │                 └─ confirmation
                      ├─ Tool handler
                      ├─ untrusted labeling + redaction
                      └─ JSONL audit

The core principle is "decide first, execute second, sanitize output, and leave traces throughout." Prompt text does not directly gain additional permissions; permissions are determined by the whitelist and policies in the code.

Quick Start (Windows)

py -3.10 -m venv .venv
.\.venv\Scripts\python.exe -m pip install -e ".[dev]"
.\.venv\Scripts\python.exe -m pytest
.\.venv\Scripts\python.exe -m mcpguard.regression

Or run directly:

powershell -ExecutionPolicy Bypass -File .\scripts\verify.ps1

Reports will be generated in:

• reports/regression-report.md

• reports/regression-report.json

• reports/regression-audit.jsonl

MCP Client Configuration Example

First run pip install -e ., then replace the following structure with the absolute path of the current repository:

{
  "mcpServers": {
    "mcpguard-lab": {
      "command": "D:/path/to/mcpguard-lab/.venv/Scripts/python.exe",
      "args": ["-m", "mcpguard.server"],
      "env": {
        "MCPGUARD_WORKSPACE": "D:/path/to/mcpguard-lab/fixtures/workspace",
        "MCPGUARD_NOTES": "D:/path/to/mcpguard-lab/fixtures/workspace/notes",
        "MCPGUARD_AUDIT": "D:/path/to/mcpguard-lab/reports/audit.jsonl"
      }
    }
  }
}

Real-World Boundaries

• Tool description poisoning detection is a high-signal rule layer and cannot replace manual review and a fixed whitelist.

• confirmed=true is an explicit confirmation gate in local experiments; production environments should use confirmation credentials issued by the host UI/identity system that cannot be forged by the model itself.

• The URL tool currently disables redirects to avoid passing the check on the first hop and then redirecting to an internal network; a production version should also limit response size, content type, and egress network.

• Labeling untrusted content reduces the risk of "data being treated as instructions," but the final host agent must still follow trust boundaries.

• Regression data only represents fixed test cases within the repository and does not guarantee blocking all prompt injections or all MCP risks.

Table of Contents

src/mcpguard/       核心实现
tests/              单元测试与真实 MCP stdio 集成测试
fixtures/           可公开的本地测试数据
reports/            自动生成的测试和审计证据
scripts/verify.ps1  一键验证入口

References

• Model Context Protocol Python SDK

• AgentDojo