# 🔒 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/yourusername/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.**
