# Penetration Testing MCP Server - Implementation Guidelines
## Overview
This MCP server provides educational penetration testing capabilities through a secure Docker container running Kali Linux tools. All tools are wrapped with proper input sanitization and safety measures.
## Security Implementation
### Input Sanitization
- All user inputs pass through `sanitize_input()` function
- Dangerous shell metacharacters are filtered: `;`, `&`, `|`, `` ` ``, `$`, `(`, `)`, `<`, `>`, `\`, `"`, `'`
- IP addresses and domains validated with regex patterns
- Port numbers validated to be within 1-65535 range
### Command Execution Safety
- Uses `subprocess.run()` with `shell=False` to prevent shell injection
- All commands use explicit argument arrays, not shell strings
- Timeout protection on all command executions
- Non-root user execution with minimal required capabilities
### Container Security
- Based on official Kali Linux image
- Runs as non-root user `pentester` (UID 1000)
- Network capabilities set only for tools that require raw sockets
- No persistent storage of scan results
- Regular security tool database updates
## Tool Architecture
### Core Security Tools Included
1. **nmap** - Network discovery and port scanning
2. **nikto** - Web vulnerability scanner
3. **dirb** - Directory/file enumeration
4. **whatweb** - Web technology fingerprinting
5. **searchsploit** - Exploit database search
6. **gobuster** - Fast directory/DNS/vhost enumeration
7. **nslookup** - DNS record queries
### Tool Wrapper Pattern
Each tool follows this pattern:
```python
@mcp.tool()
async def tool_name(param: str = "") -> str:
"""Single-line description."""
# 1. Input validation
# 2. Sanitization
# 3. Command construction
# 4. Execution with timeout
# 5. Result formatting
# 6. Error handling
```
## Ethical Use Guidelines
### Authorized Testing Only
- This server is designed exclusively for educational purposes
- Only use on systems you own or have explicit written authorization to test
- Respect all applicable laws and regulations
- Follow responsible disclosure practices
### Prohibited Uses
- Unauthorized scanning of third-party systems
- Malicious exploitation of discovered vulnerabilities
- Violation of computer fraud and abuse laws
- Testing without proper authorization
## Development Guidelines
### Adding New Tools
1. **Install in Dockerfile**
```dockerfile
RUN apt-get install -y new-tool
```
2. **Create wrapper function**
```python
@mcp.tool()
async def new_tool_scan(target: str = "") -> str:
"""Single-line description of tool functionality."""
# Implement following security pattern
```
3. **Follow security checklist**
- Input sanitization with `sanitize_input()`
- Target validation with `validate_ip_or_domain()`
- Command construction with argument arrays
- Timeout protection
- Error handling
- Result formatting
4. **Update documentation**
- Add tool to readme.txt features list
- Include usage examples
- Update catalog.yaml with new tool
### Security Checklist for New Tools
- [ ] Input sanitization implemented
- [ ] Target validation for IP/domain inputs
- [ ] Command injection prevention (no shell=True)
- [ ] Timeout protection
- [ ] Error handling with user-friendly messages
- [ ] No sensitive data in logs
- [ ] Proper capability requirements documented
## Error Handling Strategy
### User-Friendly Error Messages
- Clear indication of what went wrong
- Suggestions for fixing common issues
- No exposure of internal system details
- Consistent error message formatting
### Common Error Patterns
```python
# Invalid input
return "❌ Error: Target is required"
# Validation failure
return "❌ Error: Invalid target format"
# Tool execution failure
return "❌ Tool scan failed:\n{stderr}"
# Timeout
return "❌ Error: Command timed out"
```
## Performance Considerations
### Timeout Management
- Network scans: 60 seconds
- Web scans: 120 seconds
- Directory enumeration: 300 seconds
- DNS queries: 15 seconds
- General commands: 30 seconds
### Resource Limits
- Container runs with limited privileges
- Tools configured for reasonable scan scope
- No persistent result storage
- Memory-efficient tool configurations
## Logging and Monitoring
### Log Levels
- INFO: Normal operations and tool execution
- WARNING: Missing tools or configuration issues
- ERROR: Execution failures and exceptions
### Log Contents
- Tool execution events
- Input validation results
- Error conditions
- Startup/shutdown events
### Privacy Protection
- No logging of target details
- No storage of scan results
- Sanitized error messages only
## Future Enhancements
### Potential Tool Additions
- **wpscan** - WordPress vulnerability scanner
- **sqlmap** - SQL injection testing
- **hydra** - Network login cracker (with additional restrictions)
- **masscan** - High-speed port scanner
- **fierce** - DNS reconnaissance
### Configuration Options
- Scan intensity levels
- Custom wordlists
- Timeout adjustments
- Output format options
## Compliance Notes
### Educational Use
- Designed for cybersecurity education
- Supports authorized penetration testing
- Promotes responsible security research
- Includes extensive ethical use documentation
### Legal Compliance
- Users responsible for ensuring authorized use
- No assistance with unauthorized activities
- Clear disclaimers and warnings
- Responsible disclosure guidelines included
## Support and Troubleshooting
### Common Issues
1. **Tools not found**: Verify Dockerfile installation steps
2. **Permission denied**: Check container capabilities and user permissions
3. **Network unreachable**: Verify target accessibility and firewall rules
4. **Timeout errors**: Consider network latency and target responsiveness
### Debug Mode
For development, add debug logging:
```python
logging.getLogger().setLevel(logging.DEBUG)
```
### Container Debugging
```bash
# Interactive shell for debugging
docker run -it --rm pentest-mcp-server /bin/bash
# Check tool installations
which nmap nikto dirb whatweb searchsploit gobuster
```
## Version History
### v1.0.0
- Initial implementation with core security tools
- Input sanitization and safety measures
- Kali Linux container base
- Educational use documentation
- Ethical guidelines and legal disclaimers
