# 🔒 Professional Penetration Testing MCP Server

A **Model Context Protocol (MCP)** server providing enterprise-grade penetration testing capabilities through a secure Docker container running comprehensive Kali Linux tools. Designed for professional security assessments and authorized penetration testing engagements.

## 🎯 Overview

This professional MCP server integrates 40+ industry-standard penetration testing tools into Claude Desktop, enabling AI-assisted security assessments for authorized environments. All tools run in an isolated Docker container with proper input sanitization, security measures, and automated result management.

## ⚡ Professional Features

### 🛠️ Comprehensive Tool Arsenal

#### **Network Reconnaissance & Scanning**
| Tool | Purpose | Professional Features |
|------|---------|----------------------|
| **nmap** | Network Discovery & Port Scanning | 6+ scan types (stealth, version, aggressive, full, UDP, vuln scripts) |
| **masscan** | High-Speed Port Scanner | Large-scale network discovery with configurable scan rates |
| **dnsenum** | DNS Enumeration | Comprehensive subdomain, nameserver, and zone transfer testing |
| **amass** | OWASP Subdomain Enumeration | Passive and active reconnaissance modes |
| **traceroute** | Network Path Analysis | Routing and topology identification |
| **whois** | Domain Registration Lookup | WHOIS information gathering |

#### **Web Application Testing**
| Tool | Purpose | Professional Features |
|------|---------|----------------------|
| **nikto** | Web Vulnerability Scanner | OWASP Top 10, SSL/TLS support, comprehensive misconfiguration detection |
| **sqlmap** | SQL Injection Testing | Multi-DBMS support, authentication, customizable risk/level |
| **wpscan** | WordPress Security Scanner | Plugin, theme, user enumeration with vulnerability database |
| **ffuf** | Fast Web Fuzzer | Directory, file, parameter, vhost discovery with filtering |
| **nuclei** | CVE & Misconfiguration Scanner | Template-based vulnerability detection |
| **wafw00f** | WAF Detection | Web Application Firewall fingerprinting |
| **whatweb** | Technology Fingerprinting | CMS, framework, server detection with aggression levels |
| **gobuster** | Fast Enumeration | Directory, DNS, VHost discovery with custom wordlists |
| **dirb** | Web Content Brute-forcing | Multiple wordlist support |

#### **Exploitation & Vulnerability Research**
| Tool | Purpose | Professional Features |
|------|---------|----------------------|
| **searchsploit** | Exploit Database Search | Local ExploitDB search with exact matching |
| **metasploit** | Exploitation Framework | Module search and exploit identification |

#### **Password Cracking & Authentication Testing**
| Tool | Purpose | Professional Features |
|------|---------|----------------------|
| **hydra** | Network Login Brute-forcing | SSH, FTP, HTTP, RDP, SMB support with rate limiting |
| **john** | Password Hash Cracking | Multi-format hash support with custom wordlists |
| **hashcat** | GPU-Accelerated Cracking | Advanced attack modes (dictionary, combinator, mask, hybrid) |
| **hashid** | Hash Type Identification | Automatic hash format detection |

#### **Post-Exploitation & Enumeration**
| Tool | Purpose | Professional Features |
|------|---------|----------------------|
| **enum4linux** | SMB/Samba Enumeration | User, share, group, policy enumeration |
| **smbmap** | SMB Share Auditing | Permission auditing with authentication |

#### **SSL/TLS Security Testing**
| Tool | Purpose | Professional Features |
|------|---------|----------------------|
| **sslscan** | SSL/TLS Testing | Cipher suite and protocol analysis |
| **testssl.sh** | Advanced SSL Vulnerability Scanner | Heartbleed, POODLE, BEAST, CRIME detection |

#### **Wireless Security Testing**
| Tool | Purpose | Professional Features |
|------|---------|----------------------|
| **aircrack-ng** | Wireless Security Suite | WPA/WPA2 password cracking from capture files |

### 🔐 Enterprise Security Features

- **🐳 Isolated Container Environment** - Complete isolation using Kali Linux
- **🛡️ Advanced Input Sanitization** - Multi-layer command injection prevention
- **👤 Non-root Execution** - Minimal privilege principle with capability-based security
- **🔍 Input Validation** - IP/domain/port format verification with regex patterns
- **⏱️ Timeout Protection** - Configurable timeouts for all operations
- **📝 Comprehensive Logging** - Full audit trail with structured logging
- **💾 Automatic Result Storage** - Timestamped results with organized file management
- **📊 Result Management** - List, read, and organize scan outputs

## 🚀 Quick Start

### Prerequisites

- **Docker Desktop** installed and running
- **Claude Desktop** application (latest version)
- **Git** for repository cloning
- **Administrative privileges** for Docker operations

### Installation

1. **Clone the repository**
   ```bash
   git clone https://github.com/AnGrY-Althaf/pentest-mcp-server.git
   cd pentest-mcp-server
   ```

2. **Build the professional Docker image**
   ```bash
   docker build -t pentest-mcp-pro .
   ```

   *Note: Initial build may take 15-30 minutes due to comprehensive tool installation*

3. **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`

   Add this configuration:
   ```json
   {
     "mcpServers": {
       "pentest_professional": {
         "command": "docker",
         "args": [
           "run",
           "--rm",
           "-i",
           "--cap-add=NET_RAW",
           "--cap-add=NET_ADMIN",
           "--cap-add=NET_BIND_SERVICE",
           "pentest-mcp-pro",
           "python3",
           "pentest_server.py"
         ]
       }
     }
   }
   ```

4. **Restart Claude Desktop**

   Completely quit and restart Claude Desktop to load the new professional server.

5. **Verify Installation**

   In Claude Desktop, you should see the professional pentest server connected with 40+ tools available.

## 📖 Professional Usage Examples

### Network Reconnaissance

```
"Perform a comprehensive nmap scan on 192.168.1.0/24 with version detection"
"Run a stealth SYN scan on 10.0.0.1 ports 1-1000"
"Execute aggressive nmap scan with OS detection on target.local"
"Use masscan to quickly scan 192.168.1.0/24 for common ports at rate 5000"
"Enumerate subdomains for example.com using amass in passive mode"
"Perform comprehensive DNS enumeration on target-domain.com"
```

### Web Application Testing

```
"Scan https://webapp.local with nikto including SSL checks"
"Test https://target.com/login.php for SQL injection with sqlmap at level 3 risk 2"
"Enumerate WordPress plugins and themes on https://blog.example.com"
"Run nuclei CVE scans against https://application.local"
"Use ffuf to discover hidden directories on https://target.com with big wordlist"
"Detect WAF on https://protected-site.com using wafw00f"
"Identify web technologies on https://target.com with aggressive whatweb scan"
```

### Exploitation & Vulnerability Research

```
"Search for Apache 2.4.49 vulnerabilities in searchsploit"
"Find Metasploit modules for MS17-010 EternalBlue"
"Search exploits for ProFTPD 1.3.5 with exact matching"
```

### Password & Authentication Testing

```
"Use hydra to brute-force SSH on 192.168.1.10 with username admin"
"Crack NTLM hashes from hashes.txt using john with rockyou wordlist"
"Identify hash type for 5f4dcc3b5aa765d61d8327deb882cf99"
"Run hashcat on MD5 hashes in hash-file.txt with dictionary attack"
```

### Post-Exploitation

```
"Enumerate SMB shares on 192.168.1.20 using enum4linux"
"Test SMB share access on 192.168.1.20 with username guest"
"Map SMB permissions on 10.0.0.5 with credentials user:password"
```

### SSL/TLS Security

```
"Test SSL/TLS configuration on https://secure.example.com:443"
"Check for SSL vulnerabilities on mail.example.com using testssl.sh"
"Analyze cipher suites on https://api.example.com with sslscan"
```

### Results Management

```
"List the last 20 scan results"
"Show me the contents of the most recent nmap scan"
"Read the nikto scan results from [filename]"
```

## 🔧 Professional Tool Reference

### Network Reconnaissance

#### `nmap_scan(target, scan_type, ports)`
- **target**: IP address, domain, or CIDR range
- **scan_type**:
  - `basic` - TCP connect scan (default)
  - `stealth` - SYN stealth scan with OS detection
  - `version` - Service version detection with default scripts
  - `aggressive` - OS detection, version detection, script scanning, traceroute
  - `full` - All ports with comprehensive detection
  - `udp` - UDP port scan
  - `vuln` - Vulnerability detection scripts
- **ports**: Port specification (e.g., "80,443,8080" or "1-1000")

#### `masscan_scan(target, ports, rate)`
- **target**: IP address or CIDR range
- **ports**: Port range (default: "1-65535")
- **rate**: Packets per second (default: "1000", recommend 10000 for fast scans)

#### `dnsenum_scan(domain)`
- **domain**: Target domain for comprehensive DNS enumeration

#### `amass_enum(domain, mode)`
- **domain**: Target domain
- **mode**: `passive` (OSINT only) or `active` (includes DNS queries)

### Web Application Testing

#### `sqlmap_scan(url, data, cookie, level, risk)`
- **url**: Target URL with parameters
- **data**: POST data for testing
- **cookie**: Session cookies
- **level**: Detection level 1-5 (default: 1)
- **risk**: Test risk level 1-3 (default: 1)

#### `wpscan_scan(url, enumerate)`
- **url**: WordPress site URL
- **enumerate**: Options - `vp` (vulnerable plugins), `vt` (vulnerable themes), `u` (users)

#### `nuclei_scan(target, templates)`
- **target**: Target URL or domain
- **templates**: Template category (cves, misconfigurations, vulnerabilities, etc.)

#### `ffuf_scan(url, wordlist, mode)`
- **url**: Target URL (include /FUZZ for directory mode)
- **wordlist**: `common`, `big`, or custom path
- **mode**: `dir` (directory) or `vhost` (virtual host)

### Password Cracking

#### `hydra_bruteforce(target, service, username, password_list)`
- **target**: Target IP or hostname
- **service**: ssh, ftp, http-post-form, rdp, smb, etc.
- **username**: Username to test
- **password_list**: `rockyou` or custom wordlist

#### `hashcat_crack(hash_file, hash_type, attack_mode)`
- **hash_file**: Path to file containing hashes
- **hash_type**: Hash mode (0=MD5, 100=SHA1, 1000=NTLM, 3200=bcrypt, etc.)
- **attack_mode**: 0=Dictionary, 1=Combinator, 3=Mask, 6=Hybrid

### Results Management

#### `list_results(limit)`
- **limit**: Number of recent results to display (default: 10)

#### `read_result(filename)`
- **filename**: Name of result file to read

## 🏗️ Professional Architecture

```
Claude Desktop → MCP Protocol → Docker Container → Kali Linux Tools
                                       ↓
                         Input Sanitization & Validation
                                       ↓
                         Secure Tool Execution (pentester user)
                                       ↓
                         Result Storage & Management
                                       ↓
                         Formatted Output & Error Handling
```

### Security Layers

1. **Input Layer**: Multi-character sanitization, regex validation
2. **Execution Layer**: Non-shell subprocess execution, timeout protection
3. **Permission Layer**: Capability-based security, non-root user
4. **Storage Layer**: Isolated workspace with proper permissions
5. **Network Layer**: Controlled network capabilities

## 🛡️ Security & Legal Considerations

### ✅ Authorized Use Only

**CRITICAL**: This tool is designed exclusively for:
- **Authorized penetration testing engagements** with written permission
- **Professional security assessments** in controlled environments
- **Bug bounty programs** within defined scope
- **Cybersecurity education and training** on owned systems
- **Red team exercises** with proper authorization
- **Security research** on authorized targets

### ❌ Strictly Prohibited Uses

- ❌ Unauthorized scanning of third-party systems
- ❌ Attacking systems without explicit written permission
- ❌ Using discovered vulnerabilities maliciously
- ❌ Violating computer fraud and abuse laws (CFAA, Computer Misuse Act, etc.)
- ❌ Scanning internet-facing systems without authorization
- ❌ Denial-of-service attacks
- ❌ Data exfiltration or system compromise

### 📋 Professional Best Practices

1. **Pre-Engagement**
   - Obtain written authorization before testing
   - Define scope and boundaries clearly
   - Establish rules of engagement
   - Document chain of custody

2. **During Engagement**
   - Stay within defined scope
   - Document all activities
   - Maintain communication with stakeholders
   - Report critical findings immediately

3. **Post-Engagement**
   - Provide comprehensive reports
   - Follow responsible disclosure practices
   - Securely delete sensitive data
   - Archive results per contractual obligations

## 🔒 Technical Security Implementation

### Input Sanitization
```python
# Multi-layer protection
- Shell metacharacter filtering: ; & | ` $ ( ) < > \ " '
- IP/domain regex validation
- Port range validation (1-65535)
- CIDR notation support
- URL format verification
```

### Container Security
```dockerfile
- Based on official Kali Linux
- Non-root user (pentester UID 1000)
- Capability-based permissions (CAP_NET_RAW, CAP_NET_ADMIN)
- No persistent storage mounting
- Regular security updates
- Minimal attack surface
```

### Command Execution
```python
- subprocess.run() with shell=False
- Explicit argument arrays
- Configurable timeout protection
- Comprehensive error handling
- Result capture and sanitization
```

## 🧪 Development & Testing

### Local Testing

```bash
# Test MCP server directly
docker run --rm -i pentest-mcp-pro python3 pentest_server.py

# Interactive container for debugging
docker run --rm -it pentest-mcp-pro /bin/bash

# Test individual tools
docker run --rm pentest-mcp-pro nmap --version
docker run --rm pentest-mcp-pro masscan --version
docker run --rm pentest-mcp-pro sqlmap --version

# Check tool availability
docker run --rm pentest-mcp-pro python3 -c "import subprocess; [print(f'{t}: {subprocess.run([\"which\", t], capture_output=True).returncode == 0}') for t in ['nmap', 'masscan', 'sqlmap']]"
```

### Performance Optimization

```bash
# Multi-stage builds for smaller image size
# Cached wordlists for faster scanning
# Parallel tool installation in Dockerfile
# Pre-decompressed rockyou.txt wordlist
# Optimized Python dependencies
```

### Adding Custom Tools

1. **Install in Dockerfile**
   ```dockerfile
   RUN apt-get update && apt-get install -y --no-install-recommends \
       new-security-tool \
       && rm -rf /var/lib/apt/lists/*
   ```

2. **Add capability if needed**
   ```dockerfile
   RUN setcap cap_net_raw+eip /usr/bin/new-tool || true
   ```

3. **Create wrapper function**
   ```python
   @mcp.tool()
   async def new_tool_scan(target: str = "") -> str:
       """Single-line professional description."""
       # Implement security pattern
       target = sanitize_input(target)
       if not validate_ip_or_domain(target):
           return "❌ Error: Invalid target format"
       # Execute and handle results
   ```

4. **Update documentation and tool checklist**

## 📁 Project Structure

```
pentest-mcp-server/
├── Dockerfile                    # Professional container configuration
├── requirements.txt              # Python dependencies
├── pentest_server.py            # Main MCP server (1000+ lines)
├── README.md                    # Professional documentation (this file)
├── CLAUDE.md                    # Implementation guidelines
├── LICENSE                      # MIT License
└── results/                     # Auto-generated scan results (in container)
    ├── nmap_*.txt
    ├── nikto_*.txt
    ├── sqlmap_*.txt
    └── ...
```

## 📊 Tool Statistics

- **40+ Professional Tools** installed and configured
- **9 Tool Categories** covering full pentest lifecycle
- **Network Reconnaissance**: 6 tools
- **Web Application Testing**: 9 tools
- **Exploitation**: 2 frameworks
- **Password Cracking**: 4 tools
- **Post-Exploitation**: 2 tools
- **SSL/TLS Testing**: 2 tools
- **Wireless**: 1 suite
- **Utilities**: 5+ additional tools
- **Result Management**: Built-in

## 🤝 Contributing

Professional contributions welcome! Please follow:

1. Fork the repository
2. Create feature branch (`git checkout -b feature/advanced-tool`)
3. Follow security guidelines for new tools
4. Add comprehensive tests and documentation
5. Update tool statistics and documentation
6. Submit detailed pull request

### Contribution Guidelines
- Maintain security-first approach
- Add comprehensive error handling
- Include usage examples
- Update professional documentation
- Follow Python best practices (PEP 8)
- Add type hints where applicable

## 📜 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## ⚠️ Disclaimer

**IMPORTANT LEGAL NOTICE**

This software is intended for **authorized security testing and educational purposes only**. Users are solely responsible for ensuring their use complies with:

- All applicable local, state, federal, and international laws
- Computer Fraud and Abuse Act (CFAA) in the United States
- Computer Misuse Act in the United Kingdom
- Similar legislation in other jurisdictions
- Terms of Service and Acceptable Use Policies
- Contractual obligations and authorization agreements

**Unauthorized use of this software to:**
- Scan, probe, or attack systems without explicit written authorization
- Access systems or data without permission
- Disrupt services or operations
- Violate privacy or security measures

**...is strictly prohibited and may result in civil and criminal penalties.**

The authors and contributors:
- Provide this software "as-is" without warranty
- Are not responsible for misuse or damage
- Do not endorse or encourage unauthorized activities
- Recommend consultation with legal counsel before use

**By using this software, you acknowledge and agree to these terms.**

## 🆘 Support & Community

- **Issues**: [GitHub Issues](https://github.com/yourusername/pentest-mcp-server/issues)
- **Documentation**: Check CLAUDE.md for implementation details
- **Security Issues**: Use responsible disclosure practices
- **Professional Support**: Contact for enterprise consulting

## 🏆 Acknowledgments

Built with:
- **Kali Linux** - Offensive Security
- **Model Context Protocol** - Anthropic
- **Docker** - Containerization platform
- **FastMCP** - Python MCP framework
- All the amazing open-source security tool developers

## 🏷️ Keywords

`penetration-testing` `cybersecurity` `mcp-server` `kali-linux` `docker` `nmap` `metasploit` `sqlmap` `professional-security` `ethical-hacking` `security-tools` `claude-desktop` `vulnerability-scanning` `network-security` `web-security` `password-cracking` `post-exploitation`

---

**⭐ Star this repository if you find it useful for professional security assessments!**

**🔒 Always get authorization before testing systems you don't own.**