# Penetration Testing MCP Server
A Model Context Protocol (MCP) server that provides educational security testing tools in a controlled Docker environment.
## Purpose
This MCP server provides a secure interface for AI assistants to perform penetration testing and security assessments on systems within your own controlled environment for educational purposes.
## Features
### Current Implementation
- **`nmap_scan`** - Network mapping and port scanning with multiple scan types
- **`nikto_scan`** - Web vulnerability scanner for identifying common security issues
- **`dirb_scan`** - Directory and file brute force discovery
- **`whatweb_scan`** - Web technology identification and fingerprinting
- **`searchsploit_lookup`** - Search for known exploits in the Exploit Database
- **`gobuster_scan`** - Fast directory/DNS/vhost enumeration tool
- **`nslookup_query`** - DNS lookup and record enumeration
## Prerequisites
- Docker Desktop with MCP Toolkit enabled
- Docker MCP CLI plugin (`docker mcp` command)
- Target systems must be within your own controlled environment
- Proper authorization for all testing activities
## Installation
See the step-by-step instructions provided with the files.
## Usage Examples
In Claude Desktop, you can ask:
- "Run a basic nmap scan on 192.168.1.1"
- "Perform a nikto web vulnerability scan on example.com"
- "Use dirb to discover directories on http://testsite.local"
- "Check what web technologies are running on mysite.com"
- "Search for exploits related to Apache 2.4"
- "Run gobuster directory enumeration on http://target.local"
- "Perform DNS lookup for domain.com with MX records"
## Security Considerations
### Input Sanitization
- All user inputs are sanitized to prevent command injection
- IP addresses and domains are validated before use
- Dangerous shell metacharacters are filtered
- Port numbers are validated within acceptable ranges
### Container Security
- Runs as non-root user (pentester)
- Uses Kali Linux base with minimal required tools
- Network capabilities set only where necessary
- No persistent data storage of scan results
### Ethical Use
- **ONLY** use on systems you own or have explicit permission to test
- Intended for educational and authorized security testing
- Not for unauthorized scanning or malicious activities
- Users are responsible for compliance with local laws
## Architecture
```
Claude Desktop → MCP Gateway → Pentest MCP Server → Security Tools
↓
Kali Linux Container
(nmap, nikto, dirb, etc.)
```
## Development
### Local Testing
```bash
# Run directly for testing
python3 pentest_server.py
# Test MCP protocol
echo '{"jsonrpc":"2.0","method":"tools/list","id":1}' | python3 pentest_server.py
```
### Adding New Tools
1. Install the tool in Dockerfile
2. Add wrapper function to `pentest_server.py`
3. Decorate with `@mcp.tool()`
4. Include input sanitization and validation
5. Update the catalog entry with the new tool name
6. Rebuild the Docker image
## Tool Details
### Nmap Scanner
- **Basic**: TCP connect scan (-sT)
- **Stealth**: SYN stealth scan (-sS) with OS detection
- **Version**: Service version detection (-sV)
- **Aggressive**: Aggressive scan with OS detection, version detection, script scanning, and traceroute (-A)
### Nikto Scanner
- Web vulnerability scanner
- Checks for outdated software, dangerous files, and misconfigurations
- Output in text format for easy parsing
### Dirb Scanner
- Directory and file brute forcing
- Multiple wordlist options: common, big, small
- Recursive directory discovery
### WhatWeb Scanner
- Web technology fingerprinting
- Identifies CMS, frameworks, server software
- Plugin-based detection system
### SearchSploit
- Searches the Exploit Database
- Local copy of exploits from exploit-db.com
- Updated database included in container
### Gobuster
- Fast directory/file discovery
- DNS subdomain enumeration
- Virtual host discovery
- Multi-threaded scanning
### NSLookup
- DNS record queries
- Supports A, AAAA, MX, NS, TXT, CNAME, SOA records
- Basic DNS reconnaissance
## Troubleshooting
### Tools Not Appearing
- Verify Docker image built successfully with `docker images`
- Check catalog and registry files for syntax errors
- Ensure Claude Desktop config includes custom catalog
- Restart Claude Desktop completely
### Permission Errors
- Ensure Docker has necessary permissions
- Verify container runs as pentester user
- Check that network capabilities are set correctly
### Scan Failures
- Verify target is reachable from container
- Check firewall settings on target systems
- Ensure target systems are in your authorized test environment
- Review container logs for detailed error messages
### Timeout Issues
- Large networks may require longer scan times
- Consider breaking large scans into smaller segments
- Adjust timeout values in tool functions if needed
## Legal and Ethical Considerations
⚠️ **IMPORTANT**: This tool is designed for educational purposes and authorized security testing only.
### Authorized Use Only
- Only scan systems you own or have explicit written permission to test
- Ensure compliance with local, state, and federal laws
- Respect terms of service for cloud platforms and hosting providers
- Document authorization before conducting any scans
### Prohibited Activities
- Unauthorized scanning of third-party systems
- Accessing systems without permission
- Using discovered vulnerabilities maliciously
- Violating computer fraud and abuse laws
### Best Practices
- Maintain detailed logs of authorized testing activities
- Use test environments whenever possible
- Coordinate with system administrators
- Follow responsible disclosure for any vulnerabilities found
## License
MIT License
## Disclaimer
The authors and contributors of this software are not responsible for any misuse or damage caused by this program. Users are solely responsible for ensuring their use complies with applicable laws and regulations.
