mcp-safeguard - 🛡️ Security scanner for MCP (Model Context Protoco

项目说明

<!-- mcp-name: com.cogni/mcp-safeguard -->
<di="center">

🛡️ mcp-safeguard

The security scanner for MCP servers.

Detect prompt injection · credential leaks · exposed endpoints · tool poisoning

> 🔎 Found C — a ser request forgery in Google's official MCP Toolbox. Google shipped the fix and credited the report.

![PyPI ]()
![Found C in Google's MCP Toolbox]()
![DOI]()
![Python 3.11+]()
![License: MIT]()
![Listed on mcpservers.org]()
![GitLab]()

</div>

---

30-Second Demo

> Scan your own Claude Desktop config: mcp-safeguard scan ~/Library/Application\ Support/Claude/claude_desktop_config.json

---

What is this?

MCP (Model Context Protocol) connects AI agents — Claude, Cursor, Windsurf, GPT — to real-world tools: your filesystem, databases, shell, APIs. It's growing fast. The security tooling hasn't kept up.

mcp-safeguard is an open-source automated security scanner purpose-built for MCP. It audits tool definitions and ser for the attack surfaces OWASP classified in 2026.

---

Why it matters

MCP tool descriptions are text the LLM reads to decide what to do. An attacker who controls a tool description can embed instructions:

The AI reads this as part of its context. Without scanning, you'd never know.

Four attack surfaces mcp-safeguard covers:

| Risk | Rules | What it detects |
|------|-------|----------------|
| Prompt Injection | PI-001–PI-015 (15) | Instruction o, jailbreak phrases, exfiltration commands, identity hijacking, zero-width steganography |
| Credential Leaks | CRED-001–028 (31) | AWS keys, Anthropic/OpenAI tokens, GitHub PATs, Stripe keys, JWTs, database URLs, hardcoded passwords, plus name-based detection for Twilio/SendGrid/Slack/HuggingFace/Replicate/Cohere env vars |
| Endpoint Exposure | EP-001–013, EP-PORT-001–012, EP-RESP-001–005, EP-SSRF-001 (31) | /admin, /.env, /debug, /actuator, dangerous open ports, response-body credential leaks, AWS/GCP metadata endpoints |
| Tool Poisoning | TP-001–TP-011 (11) | Side-effect exfiltration, external URL calls, safety o instructions, hidden instruction tags, conceal-from-user directives, read-then-exfiltrate patterns |
| SSRF Detection | SS-001–SS-003 (3) | URL parameters without allowlist/blocklist protection, blind URL fetch descriptors, redirect-following without re |

v0.3.0: SSRF rules detect URL parameter patterns across MCP fetch/scrape tools:

---

Installation

Docker:

---

Quick Start

Scan tool definitions directly

Scan a server's source tree

The scanners above read a config/tool-definition JSON. scan-source instead
walks an MCP server's actual implementation for code-le a config
scan cannot see: credential handling across redirects, SQL read-only
enforcement, a ser credential attached to a caller-influenced
destination host, unenforced auth flags, unowned resource IDs keying shared
state, syntax-only destructi classifiers trusted as security gates,
client-trusted ownership fields on mutations, unescaped shell interpolation,
unhardened credential file writes, SSRF DNS-rebinding TOCTOU windows, and
silently-dropped manifest entries.

| Rule | Detects |
|------|---------|
| SRC-001 | Go http.RoundTripper re-applies Authorization on every hop with no CheckRedirect to strip it on a host change |
| SRC-002 | Python httpx client with follow_redirects=True plus a bearer/Authorization header (the same failure as SRC-001) |
| SRC-003 | SQL read-only mode enforced by a string/prefix check only, with no database-le transaction in the same file |
| SRC-004 | A ser credential (token/secret/API key) attached to a connection whose destination host is an interpolated, potentially caller-influenced |
| SRC-005 | An --auth-token/AUTH_TOKEN flag is parsed and referenced but ne gates the network listener before it starts serving |
| SRC-006 | A client-supplied resource ID (chat_id/session_id/...) keys shared ser state with no ownership check on that ID |
| SRC-007 | A "detect destructive"/is_readonly-style classifier used to gate execution recognizes only statement-type syntax, missing side-effecting calls wrapped in a safe-looking statement |
| SRC-008 | A create/update mutation trusts a client-supplied ownership field (user_id/owner_id/account_id/tenant_id) instead of deriving it ser |
| SRC-009 | Unescaped interpolation into a shell string passed to exec/system, where the same repo already has a safer arg pattern elsewhere |
| SRC-010 | A credential/key file is written with no permission hardening, while the same repo hardens permissions on other file writes |
| SRC-011 | An SSRF guard a resolved IP once, but the actual outbound call re-resolves the original URL string (DNS-rebinding TOCTOU) |
| SRC-012 | A manifest/lockfile parser silently drops sentinel- entries with only debug-le before the list reaches a security consumer |
| SRC-013 | TLS certificate explicitly disabled (=False, ssl.CERT_NONE, rejectUnauthorized: false, InsecureSkip, ...) |
| SRC-014 | An OAuth redirect_uri is read from the request and used in a redirect response with no allowlist/registration comparison in between (authorization-code interception) |
| SRC-015 | The inbound Authorization header is captured and re-forwarded as an outbound request's own header (token passthrough) |
| SRC-016 | A write/destructi flag gates only the tool-list response, with no matching gate anywhere near the tool-call dispatcher — hides discovery, not execution |
| SRC-017 | An HTTP header value is used directly as an authorization/tenant-scoping identity, with no authentication-check call anywhere in the file |
| SRC-018 | A path is built by joining a base directory with a request/argument-deri and used in a file operation, with no realpath+containment check in between |
| SRC-019 | Unescaped shell interpolation, same shape as SRC-009 but without requiring repo-wide corroboration — broader recall |
| SRC-020 | A value is interpolated into a URL query string with no proper encoder (the statically-detectable root cause behind HTTP Parameter Pollution) |
| SRC-021 | A network listener (HTTP/SSE) starts with no inbound authentication check anywhere in the file — excludes stdio transport, which isn't network-exposed |
| SRC-022 | A SQL/SoQL/query-API fragment is built by hand-quoting an interpolated value directly into the query text instead of binding it as a parameter |
| SRC-023 | A caller-derived URL/target flows into an outbound fetch (HTTP or git clone) with no SSRF-guard call anywhere in the file |
| SRC-024 | A tool/resource-handler reads or approves a resource by an ID-shaped parameter with no ownership/tenant-check anywhere in the file (BOLA) — the lowest-confidence rule in this file |
| SRC-025 | A request query/form parameter is interpolated, unescaped, into HTML response output (reflected XSS) |
| SRC-026 | A loopback-bound (or WebSocket-constructed) server has no Origin-header check anywhere in the file (DNS rebinding / cross-site WebSocket hijacking); also flags an unanchored Origin- regex (substring-match bypass) |
| SRC-027 | An OAuth scope parameter is taken directly from the request and embedded in an issued token, with no check against the caller's role anywhere in the file |
| SRC-028 | A caught exception/error response is logged in full at error level with no redaction |
| SRC-029 | A runtime-obtained access token/secret (OAuth/API response, not a static env var) is written to disk in plaintext with no encryption applied |
| SRC-030 | CORS configured with no origin restriction, or a de host- guard explicitly disabled |

This mode is heuristic (regex/text-proximity o, not a type-aware or
dataflow analysis): findings are leads to confirm by reading the cited file and
line, not proofs. SRC-009 and SRC-010 deliberately fire only when the same repo
shows it already knows the safer pattern elsewhere, trading recall for a lower
false-positive rate. SRC-007 requires e the classifier's result actually
gates execution somewhere, not just that a safety-named function exists — a
direct guard against conflating "a classifier exists" with "the classifier is
enforced," which is the most common way this class of tool o. SRC-006
and SRC-008's ownership/deri checks are file-scoped, so a check enforced
in shared middleware elsewhere in the repo won't be seen and can read as a
finding here — treat those two as the least reliable of the eight.
It was against the published source of 14 official MCP
servers (Microsoft, Amazon, Google, GitHub, and others), correctly
identifying the target pattern in 9 of 10 known instances.

SRC-013 through SRC-017 were added after this project's own coordinated-
disclosure work against li MCP servers turned up the same
handful of bug shapes repeatedly across unrelated codebases — SRC-014's
redirect_uri pattern in particular is the single most common real
that campaign found, including in confirmed go MCP
infrastructure. SRC-016 uses the same non-o discipline as SRC-007,
in reverse: it only fires when the write-gating flag is found inside the
tool-list function and confirmed absent e else in the file.

Connect to Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

Then ask Claude: *"Scan the MCP server at localhost:8000 for security issues"*

Connect to Cursor IDE

Add to .cursor/mcp.json:

Run as a server

---

CI/CD Integration

Drop mcp-safeguard into your pipeline so MCP configs are scanned on every change. It exits non-zero when it finds issues at or above your chosen se, so a config fails the build.

pre-commit (.pre-commit-config.yaml):

GitHub Actions (.github/workflows/mcp-security.yml):

GitLab CI (.gitlab-ci.yml):

Point the scan at your own MCP config path (e.g. claude_desktop_config.json). Use --fail-on CRITICAL for a softer gate, or --format json --output report.json to archi.

---

Tools Reference

| Tool | Description |
|------|-------------|
| scan_mcp_server | Full scan of an MCP server: injection + credentials + endpoints + tools |
| scan_tool_definitions | Analyze tool JSON for injection and poisoning |
| check_auth_config | Audit ser for credential exposure and OAuth scope risks |
| check_endpoint_exposure | Probe for exposed admin/debug endpoints and dangerous ports |
| generate_security_report | Get report in HTML, JSON, or text |
| get_scan_history | List all past scans with se scores |
| compare_scans | Diff two scans to detect regressions |

Example: scan_tool_definitions

Example: check_auth_config

---

Resources & Prompts

Resources:

Prompts:

---

Detection Co

Detection rules across se: prompt injection, credentials, tool poisoning, SSRF, source-audit, endpoint exposure, and OAuth scope risks. The exact count changes across releases — query the security://rules MCP resource at runtime for the li number rather than trusting any figure quoted here or elsewhere.

| Category | Rules | Patterns |
|----------|-------|---------|
| Prompt Injection | 15 rules (PI-001–015) + 4 schema-risk (PI-SCH-001–004) | Instruction o, jailbreak, exfiltration, identity hijack, steganography |
| Credential Leaks | 31 rules (CRED-001–028) | AWS, Anthropic, OpenAI, GitHub, Stripe, JWT, DB URLs, generic passwords, plus name-based detection for Twilio/SendGrid/Slack/HuggingFace/Replicate/Cohere |
| Endpoint Exposure | 29 paths + 12 ports + 5 response-leak escalations | Admin panels, debug routes, metadata services, de, credential leaks in response bodies |
| Tool Poisoning | 11 patterns (TP-001–011) | Side-effect exfil, external calls, safety o, hidden instruction tags, conceal-from-user directives, read-then-exfiltrate patterns |
| SSRF Detection | 3 rules (SS-001–003) | URL params without allowlist/blocklist protection, blind URL fetch descriptors, redirect-following without re |
| OAuth Scope Risk | 7 rules (OAUTH-001–007) | O/write/delete/sudo/offline_access/PII-exposing OAuth scopes |
| Source Audit | 36 rules (SRC-001–036) | Credential re-applied across a cross-host redirect, read-only enforced by string check alone, credential attached to a caller-influenced host, unenforced auth flags, unowned resource IDs keying shared state, syntax-only destructi classifiers, client-trusted ownership fields, unescaped shell interpolation, unhardened credential file writes, SSRF TOCTOU, silently-dropped manifest entries, disabled TLS , unchecked OAuth redirect_uri before a redirect, inbound-token passthrough to an outbound request, a write-capability flag that gates tool listing but not tool execution, a header value used as an authorization identity with no authentication check, real path tra via a joined-path containment check (including a runtime-selected/argparse-style transport value and Node's Sync-suffixed file APIs), broader (no-repo-signal-required) shell injection, unencoded URL query-string building, a network listener with no inbound authentication check anywhere in the file ( against a real, still-li deployment co 115 servers in one repo — the single most common real bug shape this campaign found), SQL/SoQL injection, unguarded outbound SSRF, missing resource-scope checks (BOLA), reflected XSS, loopback/Origin DNS-rebinding, OAuth scope without a role check, unredacted error/PII logging, plaintext credential persistence, CORS wildcard/disabled de host checks, a credential passed as a URL query parameter on a GET request instead of a POST body, a session id from a client header reused with no ownership check (session hijacking), a caller-controlled simulate/dry-run flag as the sole gate before a signing/broadcast call, a state-changing FastAPI/Flask route with no authentication dependency anywhere in the file, a secret-shaped constant that falls back to a hardcoded non-empty string when its env var is unset, and the MCP SDK's own DNS-rebinding protection explicitly disabled. Scans the server's source tree, not a config file — see scan-source above |

Benchmarked against real, confirmed — not just unit tests

tests/test_benchmark_confirmed_.py scans fixtures reproduced
(with attribution, under their original MIT license) from actual MCP servers
this project independently found and disclosed , and asserts the
right rule fires at the right file:line and se. This matters because
several rules looked correct against a hand-written synthetic test but
missed (or, in one case, falsely flagged) the real code on first
contact — real code has indirection through helper functions, multi-line
calls, and surrounding logic a clean unit-test fixture doesn't. Every rule
in this suite is fixed against what actually broke, not just re-tested
against its own synthetic case. This benchmark is small today (one committed
fixture, license-permitting; a few more during de but not
committed due to unclear source licensing) and is meant to grow — see
CONTRIBUTING.md before adding a rule derived from a real finding.

---

Security Features

SSRF Protection

Authentication

Rate Limiting

Obser

---

Architecture

---

Why This Matters

External research confirms the threat is real: MCPTox (2025) found a 72% attack success rate across 45 production MCP servers, demonstrating that tool poisoning and prompt injection attacks are actively exploitable in today's MCP ecosystem.

OWASP officially added MCP Tool Poisoning to their 2026 threat guidance — the same category mcp-safeguard's TP-* rules detect.

The gap: The MCP ecosystem grew from zero to 10,000+ servers in 18 months while security tooling lagged behind. mcp-safeguard is an open-source scanner built specifically for MCP's attack surface — tool definitions, ser, and SSRF exposure injection.

The patterns mcp-safeguard detects are documented with illustrati in SECURITY-HALL-OF-SHAME.md. Run mcp-safeguard on your own servers and contribute real scan results Issues or Discussions.

Share your results — open a Discussion or submit a PR to SECURITY-HALL-OF-SHAME.md.

---

Project Resources & Standards Work

📰 Community & Standards

🔒 Real-World Fixes Credited

Using mcp-safeguard in your pipeline, or found a real issue with it? We welcome scan results and contributions — open a Discussion or PR.

---

Roadmap

---

Contributing

Issues and PRs welcome — especially:

---

License

MIT — see LICENSE.

---

<di="center">

If this helped you, please ⭐ the repo — it helps others find it.

GitHub · PyPI · Issues

</div>

项目信息

开发语言：Python

Star 数：9

技术要点

该项目属于安全软件方向的开源资源，代码结构清晰，适合安全研究人员学习参考。项目围绕🛡️ Security scanner for MCP (Model Context Protocol) servers — prompt injection, credential exposure, SSRF, tool poisoning & source-level credential-handling flaws. pip install mcp-safeguard展开，提供了可运行的实现，对理解相关安全机制、工具原理与攻防技术具有较高的研究价值。

从技术实现角度看，此类项目的核心在于对底层原理的深入理解与工程化落地。开发者在研究过程中可以结合官方文档与社区讨论，梳理项目的初始化流程、核心模块职责与数据流转，逐步掌握其中的技术细节与设计思路。

使用与学习建议

1. 下载源码压缩包，解压到本地环境。

2. 根据项目类型准备对应的运行环境与依赖。

3. 按照 README 中的步骤完成配置与部署。

4. 在隔离的测试环境中运行验证，避免影响生产系统。

免责声明

本资源来源于开源社区，仅供安全研究、技术学习与合法授权范围内的攻防演练使用，请勿用于任何非法或侵害他人权益的用途。使用本项目产生的一切后果由使用者自行承担。