Mcpwn - Automated security scanner for Model Context Proto

项目说明

<!-- donation:eth:start -->
<di="center">

Support De

If this project helps your work, support ongoing maintenance and new features.

ETH Donation Wallet
0x11282eE5726B3370c8B480e321b3B2aA13686582

<a href="
<img src="publiceth.svg" alt="Ethereum donation QR code" width="220" />
</a>

_Scan the QR code or copy the wallet address above._

</div>
<!-- donation:eth:end -->

Mcpwn - MCP Security Testing Framework

![Python]()
![MCP]()
![Security]()

Automated security scanner for Model Context Protocol servers that detects RCE, path tra, prompt injection, and protocol .

Why Mcpwn?

MCP servers expose powerful capabilities to AI agents. One tool = full system compromise.

What Mcpwn Does:

✅ Detects RCE injection in tool arguments

✅ Finds path tra in file operations

✅ Identifies prompt injection risks in LLM-facing tools

✅ Tests protocol fuzzing and state desync attacks

✅ Generates structured reports (JSON/SARIF) for AI analysis & CI/CD

✅ Stages findings for AI - automated baseline → AI deep analysis

✅ Zero dependencies - pure Python stdlib

Quick Start:

Real Impact: Mcpwn found RCE in production MCP servers by testing tool argument injection patterns that manual code review missed.

Installation

Prerequisites

Python 3.8+

Core framework uses stdlib only (no dependencies)

Features

Semantic Detection: Pattern-based exploit detection (RCE, file read, timing attacks)

Side-Channel Detection: Timing, size, and beha anomaly detection

Paranoid Profile: Production security profile with enhanced thresholds

Thread-Safe: Concurrent operations with proper locking

Configurable Timeouts: Per-request timeout control with deadline tracking

Payload Deduplication: Efficient testing without redundant payloads

Structured Logging: Comprehensi with se levels

Safe Mode: Skip destructi (protocol fuzzing, subscription flood)

Se Aggregation: Automatic categorization by CRITICAL/HIGH/MEDIUM/LOW

CI/CD Integration: SARIF output for GitHub Security, GitLab, and other platforms

Usage

Example Output

Attack Surface

Currently Implemented:

State desync (skip/double initialize)

Capability fuzzing (malformed initialization)

Tool argument injection (command injection, path tra)

Resource path tra

Subscription flooding (parallel, skipped in safe mode)

Prompt injection (indirect LLM jailbreak)

Protocol fuzzing (malformed JSON-RPC, skipped in safe mode)

OOB detection (DNS exfiltration)

Race condition testing

Resource exhaustion

Side-channel detection (timing, size, beha patterns)

Planned (test files exist, not yet integrated):

SSRF injection

Deserialization attacks

Schema pollution

Auth bypass

Detection

Semantic indicators, not crashes:

uid=, root:x: → RCE

-----BEGIN, PRIVATE KEY → File read

Statistical timing de → Blind injection

Prompt echo → Indirect prompt injection

DNS query capture → OOB exfiltration

Architecture

Report Format

JSON reports include:

Configuration Options

| Flag | Description | Default |
|------|-------------|----------|
| --safe-mode | Skip destructi | False |
| --quick | Fast scan (5s timeout, stops on first tool injection finding) | False |
| --rce-only | Skip non-RCE tests | False |
| --profile | Security profile (e.g., profiles/paranoid.json) | None |
| --timeout | Request timeout in seconds (quick mode uses 5s) | 10 |
| --parallel | Enable parallel flooding | False |
| --output-json | Export JSON report | None |
| --output-html | Export HTML report | None |
| --output-sarif | Export SARIF report (CI/CD) | None |

Thread Safety

Request ID generation protected by lock

Health checks use dedicated lock

Send operations protected by transport lock

Connection pooling with cleanup

Safe concurrent test execution

Troubleshooting

Port conflicts (SSRF/OOB tests)

Timeout errors

Ser during tests

False positives

Resource tra now requires 2+ markers for detection

Adjust LEAK_MARKERS in tests/resource_tra.py if needed

Testing

Running Unit Tests

Integration Testing

Test against the included server:

Expected findings:

RCE via execute_command tool

Path tra via read_file tool

Co Analysis

Test Suite O

54 tests co:

Core Components (21 tests)

- Semantic detector (9 tests)
- Reporter (7 tests)
- Payloads (5 tests)

Side-Channel Detection (9 tests)

- Timing
- Size anomaly detection
- Beha pattern matching
- False positi

Edge Cases (10 tests)

- Malformed input handling
- Unicode and special characters
- Large data processing
- Concurrent access scenarios

Integration (14 tests)

- CLI argument
- End-to-end scanning
- Report generation

Co Requirements:

Core modules: >80% co

Critical paths: 100% co

Edge cases: Comprehensi handling

De Testing

bash

Install de dependencies

pip install -r requirements-dev.txt

Run linting

flake8 . --exclude=.git,.mypy_cache,__pycache__

Run security checks

bandit -r . -ll --exclude=.git,.mypy_cache,tests_unit
bash

1. Run automated scan

python mcpwn.py --output-json findings.json npx -y /ser /tmp

2. AI analyzes structured output

- Parses JSON findings

- Identifies patterns

- Prioritizes by se

3. AI performs deep analysis

- findings in context

- Finds logic flaws Mcpwn missed

- Generates remediation guidance

``

Benefits:

Structured Data: JSON/SARIF output for AI parsing

E: Concrete exploits

Time Savings: AI focuses on interpretation, not pattern matching

: Confirm AI-suggested with automated testing

Training: Mcpwn findings teach AI about MCP

Best Practice: Use Mcpwn for automated baseline → AI for deep contextual analysis → Comprehensi co

Limitations

What Mcpwn Detects:

Runtime exploits (RCE, path tra, injection)

Protocol-le

Resource exhaustion and DoS

Pattern-based security issues

What Mcpwn Misses:

Configuration (exposed credentials, insecure settings)

Business logic flaws

Authorization bypass requiring context

Complex multi-step attack chains

No without known patterns

Recommendation: Use Mcpwn for automated baseline scanning and CI/CD integration, but complement with manual security review for comprehensi. Automated tools find known patterns; human analysis finds logic flaws.

FAQ

Q: How long does a typical scan take?
A: Quick mode (--quick --rce-only) takes ~5 seconds. Full scan takes 30-60 seconds depending on ser.

Q: Will this crash my MCP server?
A: Use --safe-mode to skip destructi (protocol fuzzing, subscription flood). Tool injection and path tra tests are non-destructive.

Q: Does this work with any MCP server?
A: Yes, any ser the Model Context Protocol (2024-11-05 spec). Works with Python, TypeScript, Go implementations.

Q: How do I integrate this into CI/CD?
A: Use --output-sarif report.sarif to generate SARIF format compatible with GitHub Security, GitLab, and other platforms.

Q: What's the difference between --quick and --rce-only?
A: --quick reduces timeout to 5s and stops on first finding. --rce-only skips non-RCE tests (path tra, prompt injection, etc). Combine both for fastest scan.

Q: Can I test my own MCP server?
A: Yes! Point Mcpwn at your ser: python mcpwn.py python3 my_server.py or python mcpwn.py node server.js

Q: What if I get false positives?
A: Check the detection patterns in the JSON report. Path tra requires 2+ markers. Adjust LEAK_MARKERS in tests/resource_tra.py if needed.

Q: Does this require root/admin pri?
A: No, runs with normal user pri. Only needs permission to execute the MCP ser.

Q: How does semantic detection work?
A: Instead of looking for crashes, Mcpwn analyzes response content for patterns like uid=1000, root:x:0:0, -----BEGIN PRIVATE KEY, timing de, etc.

Q: Can I use this with AI assistants?
A: Yes! Generate JSON output (--output-json findings.json`) and feed it to AI for deeper analysis. The structured format helps AI understand in context.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT License - see LICENSE file for details

Disclaimer

This tool is for security testing purposes only. Only test systems you ha to test.

Author

Teycir Ben Soltane

Website: teycirbensoltane.tn

Email:

GitHub:

项目信息

开发语言：Python

Star 数：30

技术要点

该项目属于安全软件方向的开源资源，代码结构清晰，适合安全研究人员学习参考。项目围绕Automated security scanner for Model Context Protocol servers that detects RCE, path traversal, prompt injection, and protocol vulnerabilities.展开，提供了可运行的实现，对理解相关安全机制、工具原理与攻防技术具有较高的研究价值。

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

使用与学习建议

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

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

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

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

免责声明

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