mcp-guard

🛡️ MCP Guard

Security Auditor, Static Linter, and Dynamic Fuzzer for Model Context Protocol (MCP) Servers.

---

📌 Overview

MCP Guard is an open-source automated security auditing suite designed specifically for the Model Context Protocol (MCP) ecosystem. It helps developers, researchers, and users verify that MCP servers and tools are safe, hardened against exploitation, and free from prompt injection vulnerabilities before deploying or connecting them to LLMs.

---

✨ Key Features

1. ⚡ Dynamic Black-Box & Grey-Box Fuzzing (fuzzer_dynamic):

   • Path Traversal Attacks: Detects unsandboxed filesystem access (e.g. ../../etc/passwd, Windows win.ini).
   • Command & Shell Injection: Injects canary execution tokens into tool parameters to detect unescaped shell commands (shell=True, child_process.exec).
   • SQL Injection: Checks database query tools for error leakage and SQL injection vectors.
   • Denial of Service & ReDoS: Tests large payload handling and boundary conditions.

2. 🧠 Prompt Injection & Tool Poisoning Scanner (scanner_prompt_injection):

   • Detects hidden directives, role hijacking personas ("ignore previous instructions", "DAN mode").
   • Scans for covert data exfiltration instructions and forced tool chaining.
   • Uncovers steganographic zero-width unicode characters and disguised Markdown/HTML comments in tool descriptions.
   • Flags suspicious base64 blobs hidden in metadata.

3. 🔍 Static Code & AST Scanner (scanner_code):

   • Analyzes Python, JavaScript, and TypeScript source files.
   • Detects dangerous system calls (os.system, subprocess(shell=True), eval(), exec(), new Function()).
   • Identifies hardcoded API keys, tokens, and full environment variable dumps.

4. 📋 Schema & Boundary Quality Audit (scanner_schema):

   • Validates JSON Schema conformance against the MCP specification.
   • Enforces parameter descriptions and flags unconstrained sensitive arguments.
   • Detects overly permissive additionalProperties: true.

5. 📊 Multi-Format Reporting & CI/CD Native:

   • Formatted ANSI terminal reports with safety scores (0-100) and letter grades (A+ to F).
   • Markdown summary export for GitHub Pull Request comments.
   • SARIF 2.1.0 export for GitHub Code Scanning alerts.
   • Structured JSON output for automated pipelines.

---

🚀 Installation

Clone the repository and install locally:

git clone https://github.com/dubzeb/mcp-guard.git
cd mcp-guard
pip install -e .

Note: MCP Guard is built with pure Python 3 standard library modules, requiring zero heavy external dependencies for core scanning!

---

💻 Quick Start & Usage

1. Scan a Live Running MCP Server (Stdio)

Test your server dynamically over stdio:

# Scan a Python MCP server
mcp-guard scan --server-cmd "python my_server.py"

# Scan a Node.js / TypeScript MCP server
mcp-guard scan --server-cmd "node dist/index.js"

# Include source code AST analysis simultaneously
mcp-guard scan --server-cmd "python server.py" --source-dir ./src --format terminal

2. Static Codebase Scan Only

Audit an MCP server repository without running the process:

mcp-guard scan-code --dir ./my-mcp-project

3. Manifest / Schema File Audit

Audit an mcp.json configuration or exported tools list:

mcp-guard scan-manifest --file mcp.json

4. Exporting Reports for CI/CD

# Export Markdown report for PR comment
mcp-guard scan --server-cmd "python server.py" --format markdown --output report.md

# Export SARIF for GitHub Code Scanning
mcp-guard scan --server-cmd "python server.py" --format sarif --output results.sarif

---

🛡️ Rules & Detection Catalog

Rule ID	Category	Severity	Description
FUZZ-PATH-001	Path Traversal	CRITICAL	Tool leaked sensitive system file contents during path traversal fuzzing.
FUZZ-CMD-001	Command Execution	CRITICAL	Tool executed arbitrary shell command through argument injection.
FUZZ-SQL-001	SQL Injection	CRITICAL	Tool confirmed SQL injection vulnerability with canary reflection.
INJECT-001	Prompt Injection	CRITICAL	Description contains instruction override directives or jailbreak triggers.
INJECT-002	Prompt Injection	HIGH	Hidden zero-width unicode characters detected in tool/prompt description.
INJECT-003	Prompt Injection	MEDIUM	Hidden Markdown/HTML comments embedded in description.
CODE-001	Command Execution	CRITICAL	Source code contains subprocess call with shell=True.
CODE-002	Dynamic Execution	CRITICAL	Source code contains unsafe eval() or exec().
CODE-SEC-001	Credentials	CRITICAL	Hardcoded API keys, JWTs, or secrets detected in source files.
SCHEMA-001	Schema Quality	HIGH	Tool is missing a description entirely.
SCHEMA-006	Permissions	MEDIUM	Sensitive parameter (e.g. filepath, command) lacks input constraints.

---

🔄 GitHub Actions CI/CD Integration

Add .github/workflows/mcp-security-audit.yml to your MCP server repository:

name: MCP Security Audit

on: [push, pull_request]

jobs:
  security-audit:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: "3.11"

      - name: Install MCP Guard
        run: pip install git+https://github.com/d-ochandiano/mcp-guard.git

      - name: Run MCP Security Scan
        run: |
          mcp-guard scan \
            --server-cmd "python server.py" \
            --source-dir . \
            --min-score 80 \
            --format terminal

---

🧪 Running the Test Suite

python run_tests.py

---

🤝 Contributing

Contributions are welcome! Please feel free to submit issues, add new fuzzing heuristics, or submit pull requests.

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/NewSecurityRule)
3. Commit your Changes (git commit -m 'Add NewSecurityRule')
4. Push to the Branch (git push origin feature/NewSecurityRule)
5. Open a Pull Request

---

📄 License

Distributed under the MIT License. See LICENSE for more information.