themalwarenews/damn-vulnerable-MCP
If you are the rightful owner of damn-vulnerable-MCP and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.
DV-MCP Server is a security training platform with intentional vulnerabilities for educational purposes.
DV-MCP Server - Security Training Platform
A comprehensive security training platform implementing the Model Context Protocol (MCP) with intentional vulnerabilities for educational purposes.
๐ฏ Overview
DV-MCP Server is a deliberately vulnerable MCP implementation designed for:
- Security Training - Learn OAuth vulnerabilities and exploitation techniques
- MCP Integration - Practice with Claude Desktop, Windsurf, and other MCP clients
- Penetration Testing - Hands-on experience with 12+ vulnerability categories
- Educational Research - Safe environment for security research
๐ Quick Start
Prerequisites
- Docker & Docker Compose
- Python 3.11+ (for local development)
- curl (for testing)
1-Minute Setup
# Clone the repository
git clone <your-repo-url>
cd dv-mcp-server-release
# Copy environment configuration
cp .env.example .env
# Start the server
cd docker && docker-compose up -d
# Verify deployment
curl http://localhost:8080/health
๐๏ธ Architecture
dv-mcp-server-release/
โโโ src/ # Core server implementation
โ โโโ dv_mcp_server.py # Main server with 12 vulnerabilities
โโโ docker/ # Docker deployment files
โ โโโ docker-compose.yml # Multi-container setup
โ โโโ Dockerfile # Server container
โ โโโ .env # Configuration
โโโ docs/ # Comprehensive documentation
โ โโโ DEPLOYMENT.md # Deployment guide
โ โโโ OAUTH_VULNERABILITIES.md # OAuth security analysis
โ โโโ Vulnandexploit.md # Vulnerability catalog
โโโ examples/ # Demo clients and guides
โ โโโ oauth_demo_client.py # OAuth exploitation demo
โ โโโ oauthguide.md # OAuth integration guide
โโโ tests/ # Security test suites
๐ง Configuration
Security Profiles
Configure via .env
file:
# INSECURE: All vulnerabilities enabled (training)
SECURITY_PROFILE=insecure
# MIXED: Some protections active (intermediate)
SECURITY_PROFILE=mixed
# SECURE: All vulnerabilities blocked (production-like)
SECURITY_PROFILE=secure
Authentication Modes
# No authentication (open access)
AUTH_MODE=none
# API key authentication
AUTH_MODE=api_key
API_KEY=your-secure-key
# OAuth 2.1 with PKCE
AUTH_MODE=oauth
OAUTH_CLIENT_ID=your-client-id
OAUTH_CLIENT_SECRET=your-client-secret
๐ก๏ธ Security Features
Vulnerability Categories
Category | Tools | INSECURE | MIXED | SECURE |
---|---|---|---|---|
Path Traversal | read_file , write_file | โ | โ | โ |
Command Injection | execute_command | โ | โ | โ |
SSRF | fetch_url | โ | โ | โ |
Information Disclosure | get_system_info | โ | โ | โ |
OAuth Vulnerabilities | Authorization flow | โ | โ ๏ธ | โ |
Security Profile Comparison
# Test in INSECURE mode
curl -X POST http://localhost:8080/mcp \
-H "Content-Type: application/json" \
-d '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "read_file", "arguments": {"path": "/etc/passwd"}}}'
# Result: File contents exposed
# Test in SECURE mode
# Result: {"error": "Path traversal detected"}
๐ MCP Client Integration
Claude Desktop
Add to your Claude Desktop configuration:
{
"mcpServers": {
"dv-mcp-security": {
"command": "python",
"args": ["/path/to/src/dv_mcp_server.py"],
"env": {
"SECURITY_PROFILE": "mixed",
"AUTH_MODE": "oauth"
}
}
}
}
Windsurf
Configure in Windsurf settings:
{
"mcp.servers": [
{
"name": "dv-mcp-security",
"command": ["python", "/path/to/src/dv_mcp_server.py"],
"env": {
"SECURITY_PROFILE": "insecure",
"AUTH_MODE": "none"
}
}
]
}
HTTP/REST Integration
Direct API access:
# List available tools
curl -X POST http://localhost:8080/mcp \
-H "Content-Type: application/json" \
-d '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}'
# Call specific tool
curl -X POST http://localhost:8080/mcp \
-H "Content-Type: application/json" \
-d '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "get_system_info", "arguments": {}}}'
๐ OAuth Security Training
Complete OAuth Flow
# 1. Authorization Request
curl "http://localhost:8080/authorize?client_id=dv-mcp-client&redirect_uri=http://localhost:8080/callback&response_type=code&state=demo123"
# 2. Token Exchange
curl -X POST http://localhost:8080/token \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "grant_type=authorization_code&code=AUTH_CODE&redirect_uri=http://localhost:8080/callback&client_id=dv-mcp-client&client_secret=insecure-secret"
# 3. API Access with Token
curl -X POST http://localhost:8080/mcp \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "get_system_info", "arguments": {}}}'
OAuth Vulnerability Demo
# Run comprehensive OAuth security demonstration
cd examples
python3 -m venv oauth_venv
source oauth_venv/bin/activate
pip install httpx PyJWT
python oauth_demo_client.py
๐งช Security Testing
Automated Vulnerability Testing
#!/bin/bash
# Security Test Suite
echo "๐ DV-MCP Security Testing"
echo "=========================="
# Test 1: Path Traversal
echo "Test 1: Path Traversal"
curl -s -X POST http://localhost:8080/mcp \
-H "Content-Type: application/json" \
-d '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "read_file", "arguments": {"path": "/etc/passwd"}}}' \
| jq '.result.content' > /dev/null && echo "โ VULNERABLE" || echo "โ
PROTECTED"
# Test 2: Command Injection
echo "Test 2: Command Injection"
curl -s -X POST http://localhost:8080/mcp \
-H "Content-Type: application/json" \
-d '{"jsonrpc": "2.0", "id": 2, "method": "tools/call", "params": {"name": "execute_command", "arguments": {"command": "whoami"}}}' \
| jq '.result.stdout' > /dev/null && echo "โ VULNERABLE" || echo "โ
PROTECTED"
# Test 3: SSRF
echo "Test 3: SSRF"
curl -s -X POST http://localhost:8080/mcp \
-H "Content-Type: application/json" \
-d '{"jsonrpc": "2.0", "id": 3, "method": "tools/call", "params": {"name": "fetch_url", "arguments": {"url": "http://internal-api:3000/admin"}}}' \
| jq '.result.body' > /dev/null && echo "โ VULNERABLE" || echo "โ
PROTECTED"
echo "Testing complete!"
Manual Testing Checklist
-
MCP Protocol
- JSON-RPC 2.0 compliance
- Tool discovery (
tools/list
) - Tool execution (
tools/call
) - Error handling
-
Authentication
- OAuth 2.1 flow
- Token validation
- Scope enforcement
- Session management
-
Vulnerabilities
- Path traversal (
read_file
,write_file
) - Command injection (
execute_command
) - SSRF (
fetch_url
) - Information disclosure (
get_system_info
)
- Path traversal (
๐ Deployment Options
Docker Compose (Recommended)
cd docker
docker-compose up -d
# Scale services
docker-compose up -d --scale dv-mcp=3
# View logs
docker-compose logs -f dv-mcp
Standalone Docker
# Build image
docker build -t dv-mcp-server .
# Run container
docker run -d \
-p 8080:8080 \
-e SECURITY_PROFILE=insecure \
-e AUTH_MODE=oauth \
--name dv-mcp-server \
dv-mcp-server
Local Development
# Install dependencies
pip install fastapi uvicorn pydantic aiofiles httpx sse-starlette PyJWT
# Run server
cd src
python dv_mcp_server.py
# Server available at http://localhost:8080
Cloud Deployment
AWS ECS
# Build and push to ECR
aws ecr get-login-password --region us-west-2 | docker login --username AWS --password-stdin 123456789012.dkr.ecr.us-west-2.amazonaws.com
docker build -t dv-mcp-server .
docker tag dv-mcp-server:latest 123456789012.dkr.ecr.us-west-2.amazonaws.com/dv-mcp-server:latest
docker push 123456789012.dkr.ecr.us-west-2.amazonaws.com/dv-mcp-server:latest
Docker Swarm
# Initialize swarm
docker swarm init
# Deploy stack
docker stack deploy -c docker-compose.yml dv-mcp-stack
๐ Documentation
- - Complete deployment guide
- - OAuth security analysis
- - Vulnerability catalog
- - OAuth integration guide
๐ ๏ธ Development
Adding New Vulnerabilities
# src/dv_mcp_server.py
@app.post("/mcp")
async def mcp_endpoint(request: MCPRequest):
if request.method == "tools/call":
if request.params.name == "your_new_vulnerability":
# Implement vulnerability logic
if config.SECURITY_PROFILE == SecurityProfile.INSECURE:
# Vulnerable implementation
return {"result": "vulnerable_response"}
else:
# Secure implementation
return {"error": {"message": "Access denied"}}
Security Profile Configuration
class SecurityProfile(str, Enum):
INSECURE = "insecure"
MIXED = "mixed"
SECURE = "secure"
def get_security_features(profile: SecurityProfile) -> dict:
if profile == SecurityProfile.INSECURE:
return {
"allow_path_traversal": True,
"allow_command_injection": True,
# ... all vulnerabilities enabled
}
elif profile == SecurityProfile.MIXED:
return {
"allow_path_traversal": False,
"allow_command_injection": True,
# ... mixed protections
}
else: # SECURE
return {
"allow_path_traversal": False,
"allow_command_injection": False,
# ... all protections enabled
}
๐ Monitoring & Logging
Health Monitoring
# Health check endpoint
curl http://localhost:8080/health
# Response:
{
"status": "healthy",
"security_profile": "insecure",
"features": {
"allow_path_traversal": true,
"allow_command_injection": true,
// ... feature flags
},
"timestamp": "2025-08-16T07:04:33.719294"
}
Security Event Logging
# View security events
docker-compose logs dv-mcp | grep "SECURITY"
# Example logs:
# SECURITY: Path traversal attempt blocked: /etc/passwd
# SECURITY: Command injection detected: rm -rf /
# SECURITY: SSRF attempt to internal service: http://169.254.169.254/
๐ค Contributing
- Fork the repository
- Create feature branch (
git checkout -b feature/new-vulnerability
) - Add vulnerability with tests
- Update documentation
- Submit pull request
Contribution Guidelines
- New Vulnerabilities: Must include secure/insecure implementations
- Documentation: Update relevant .md files
- Tests: Add to security test suite
- Security Profiles: Ensure proper profile handling
๐ License
This project is licensed under the MIT License - see the file for details.
โ ๏ธ Security Disclaimer
FOR EDUCATIONAL USE ONLY
This software contains intentional security vulnerabilities for training purposes:
- โ DO NOT deploy in production environments
- โ DO NOT use with real sensitive data
- โ DO NOT expose to untrusted networks
- โ DO use in isolated training environments
- โ DO use for security education and research
- โ DO follow responsible disclosure practices
๐ Support
- Issues: GitHub Issues
- Discussions: GitHub Discussions
- Security: Report security issues responsibly
๐ Acknowledgments
- MCP Protocol: Model Context Protocol Specification
- Security Community: OWASP, SANS, and security researchers
- Contributors: All contributors to this educational platform
Happy Security Learning! ๐๐