Habeeba6120/Pentest-MCP

🔒 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

Web Application Testing

Exploitation & Vulnerability Research

Password Cracking & Authentication Testing

Post-Exploitation & Enumeration

SSL/TLS Security Testing

Wireless Security Testing

🔐 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

   git clone https://github.com/yourusername/pentest-mcp-server.git
   cd pentest-mcp-server
   

2. Build the professional Docker image

   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:

   {
     "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

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

Container Security

- 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

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

🧪 Development & Testing

Local Testing

# 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

# 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

   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

   RUN setcap cap_net_raw+eip /usr/bin/new-tool || true
   

3. Create wrapper function

   @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 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
• 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.