# Pentest-mcp

Unified Penetration Testing MCP Server for Claude Desktop

## Overview

A comprehensive penetration testing toolkit using Model Context Protocol (MCP). Works as a **single unified MCP server** that can be used directly from Claude Desktop.

## Features

- **Claude Desktop Integration**: All tools available via single MCP connection
- **34 Security Tools**: Reconnaissance, web scanning, SAST, SCA, taint analysis, 0-day discovery, AI security testing, authenticated testing
- **Pure MCP Architecture**: No LangChain, simple and lightweight
- **Docker Ready**: Easy deployment with Docker

## Quick Start

### Docker Setup (Recommended)

1. Build the image:
   ```bash
   docker build -t pentest-mcp .
   ```

2. Configure Claude Desktop:

   Edit your Claude Desktop config file:
   - Windows: `%APPDATA%\Claude\claude_desktop_config.json`
   - macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
   - Linux: `~/.config/Claude/claude_desktop_config.json`

   ```json
   {
     "mcpServers": {
       "pentest-mcp": {
         "command": "docker",
         "args": ["run", "--rm", "-i", "pentest-mcp"]
       }
     }
   }
   ```

3. Restart Claude Desktop

### Local Setup

```bash
# Install dependencies
pip install -r requirements.txt

# Run server
python pentest_mcp_server_stdio.py
```

## Available Tools (34 total)

### Network Scanning (4)
| Tool | Description |
|------|-------------|
| `scan_network` | Nmap network scan (basic/full/quick) |
| `resolve_dns` | DNS resolution |
| `scan_port` | Single port scan |
| `scan_http_headers` | HTTP header security analysis |

### SSH/Access (5)
| Tool | Description |
|------|-------------|
| `ssh_connect` | SSH connection test |
| `ssh_execute_command` | Execute remote commands via SSH |
| `ssh_explore_system` | System enumeration (users, network, SUID, etc.) |
| `find_flags` | CTF flag file search |
| `ftp_connect` | FTP connection and directory listing |

### Web Vulnerability Scanning (4)
| Tool | Description |
|------|-------------|
| `detect_technology` | CMS/Framework detection |
| `enumerate_directories` | Directory/file brute force |
| `test_sql_injection` | SQL injection testing |
| `test_xss` | XSS vulnerability testing |

### Exploit/Intelligence (3)
| Tool | Description |
|------|-------------|
| `search_cve` | CVE vulnerability search |
| `get_vulnerability_info` | Product vulnerability lookup |
| `generate_exploit_payload` | Reverse shell payload generation |

### Code Security (5)
| Tool | Description |
|------|-------------|
| `check_security_tools` | Check installed security tool availability |
| `semgrep_scan` | SAST - Static code analysis for vulnerabilities |
| `trivy_scan` | SCA - Dependency/container vulnerability scan |
| `trufflehog_scan` | Secret detection in Git repos/filesystems |
| `ffuf_fuzz` | High-speed web application fuzzing |

### Code Analysis / 0-day Discovery (5)
| Tool | Description |
|------|-------------|
| `repo_map` | Map repository structure - entry points, key files |
| `extract_definitions` | Extract function/class definitions |
| `analyze_call_graph` | Analyze function calls, identify dangerous sinks |
| `find_attack_surface` | Find input sources → dangerous sinks |
| `code_summary` | Generate security-focused code summary |

### Taint Analysis (1)
| Tool | Description |
|------|-------------|
| `taint_analysis` | Track data flow from sources to sinks, determine exploitability |

### AI Security Testing (3)
| Tool | Description |
|------|-------------|
| `test_prompt_injection` | Test AI APIs for prompt injection vulnerabilities |
| `test_system_prompt_extraction` | Attempt to extract system prompts from AI services |
| `test_content_filter_bypass` | Test content filter bypass techniques (leetspeak, homoglyphs, etc.) |

### Authenticated Testing (4)
| Tool | Description |
|------|-------------|
| `authenticated_request` | Make authenticated HTTP requests with OAuth/API key |
| `test_idor` | Test for Insecure Direct Object Reference vulnerabilities |
| `test_auth_bypass` | Test authentication/authorization bypass (token manipulation, header injection) |
| `test_rate_limiting` | Test rate limiting implementation |

## 0-day Discovery Workflow

```
1. repo_map          → Understand project structure
2. find_attack_surface → Identify inputs and dangerous operations
3. taint_analysis    → Track actual data flow (source → sink)
4. semgrep_scan      → Pattern-based vulnerability detection
5. [AI analysis]     → Verify exploitability
```

## Usage Examples

Use natural language in Claude Desktop:

```
Scan 192.168.1.1 for open ports
```

```
Check security headers for https://example.com
```

```
Search for CVE-2021-44228 details
```

```
Analyze /path/to/repo for 0-day vulnerabilities
```

```
Run taint analysis on /path/to/python/project
```

## Penetration Testing Phases

| Phase | Status | Tools |
|-------|--------|-------|
| **Reconnaissance** | ✅ | nmap, DNS, port scanning |
| **Web Application Testing** | ✅ | Headers, SQLi, XSS, directory enumeration |
| **Vulnerability Assessment** | ✅ | CVE search, product vulnerabilities |
| **Code Analysis (SAST/SCA)** | ✅ | Semgrep, Trivy, TruffleHog |
| **0-day Discovery** | ✅ | Taint analysis, attack surface mapping |
| **Exploitation** | ✅ | Payload generation |
| **Gaining Access** | ✅ | SSH, FTP connection |
| **Post-Exploitation** | ✅ | System exploration, flag search |
| **AI Security Testing** | ✅ | Prompt injection, system prompt extraction, filter bypass |
| **Authenticated Testing** | ✅ | IDOR, auth bypass, rate limiting |

## Security Warning

This tool is for **authorized security testing only**.

### Permitted Use
- Systems you own or manage
- Systems with explicit written permission
- CTF competition environments
- Research/educational lab environments

### Prohibited Use
- Scanning systems without permission
- Malicious purposes
- Unauthorized access attempts

**Use responsibly. We are not liable for illegal activities.**

## Project Structure

```
.
├── pentest_mcp_server_stdio.py  # Main MCP server
├── tools/                        # Tool implementations
│   ├── __init__.py              # Package exports
│   ├── network.py               # Network scanning (4 tools)
│   ├── ssh_access.py            # SSH/access (4 tools)
│   ├── ftp_access.py            # FTP (1 tool)
│   ├── web_scanner.py           # Web vulnerability (4 tools)
│   ├── exploit.py               # Exploit/intelligence (3 tools)
│   ├── code_security.py         # SAST/SCA/Secret/Fuzzing (5 tools)
│   ├── code_analysis.py         # 0-day discovery (5 tools)
│   ├── taint_analysis.py        # Taint analysis (1 tool)
│   ├── ai_security.py           # AI security testing (3 tools)
│   └── auth_testing.py          # Authenticated testing (4 tools)
├── wordlists/                    # Bundled wordlists (Docker)
├── requirements.txt              # Python dependencies
├── Dockerfile                    # Docker build
└── README.md                     # This file
```

## Technical Stack

- **Protocol**: Model Context Protocol (MCP)
- **Language**: Python 3.10+
- **Libraries**: mcp, nmap, asyncssh, httpx, ast (taint analysis)
- **External Tools**: Semgrep, Trivy, TruffleHog, ffuf (optional)

## Troubleshooting

### MCP Server Not Recognized
1. Fully quit Claude Desktop (check task manager)
2. Restart Claude Desktop
3. Verify MCP server appears in settings

### Dependency Errors
Use a virtual environment:
```bash
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate
pip install -r requirements.txt
```

### Nmap Not Found
```bash
# Ubuntu/Debian
sudo apt-get install nmap

# macOS
brew install nmap

# Windows: Download from https://nmap.org/download.html
```

## License

MIT License

## Contributing

Pull requests welcome. For major changes, please open an issue first to discuss.

## Support

Report issues on GitHub Issues section.

---

**Author**: d01ki
**Repository**: https://github.com/d01ki/Pentest-mcp
**License**: MIT