MCP Pentest

# 🚀 Quick Start Guide Get up and running with MCP Pentest Framework in less than 10 minutes! ## ⚡ Installation ### 1. Prerequisites ```bash # Install Node.js (v18+) curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash - sudo apt-get install -y nodejs # Install Git sudo apt-get install git ``` ### 2. Clone and Setup ```bash # Clone repository git clone https://github.com/your-repo/mcp-pentest.git cd mcp-pentest # One-command setup (installs everything) npm run setup ``` ### 3. Alternative: Manual Setup ```bash # Install Node dependencies npm install # Build the project npm run build # Install pentesting tools npm run install-tools ``` ## 🎯 First Scan ### CLI Usage (Easiest) ```bash # Quick port scan npm run cli recon nmap scanme.nmap.org --type quick # Web technology detection npm run cli recon tech https://httpbin.org # Subdomain enumeration npm run cli recon subdomains example.com ``` ### MCP Integration ```bash # Start MCP server npm start # In another terminal, test with MCP client # (Configure your MCP client to connect to this server) ``` ## 🔧 Configuration ### 1. Basic MCP Client Setup Add to your MCP client config: ```json { "mcpServers": { "pentest": { "command": "node", "args": ["/path/to/mcp-pentest/dist/index.js"] } } } ``` ### 2. Security Configuration ```bash # Copy example config cp examples/mcp-client-config.json ~/.config/mcp-pentest/ # Edit for your environment nano ~/.config/mcp-pentest/config.json ``` ## 🌟 Quick Examples ### Example 1: Basic Web Assessment ```bash # Full automated web assessment npm run cli auto pentest https://httpbin.org --scope web --intensity passive ``` ### Example 2: Network Discovery ```bash # Network reconnaissance npm run cli recon nmap 192.168.1.1 --type quick npm run cli vuln nuclei http://192.168.1.1 ``` ### Example 3: Vulnerability Scanning ```bash # Web vulnerability scan npm run cli vuln nuclei https://example.com --severity medium npm run cli vuln nikto https://example.com ``` ## 📊 Understanding Results ### Port Scan Results ``` 🔓 Open Ports (3): 80/tcp - http Apache 2.4.41 443/tcp - https Apache 2.4.41 22/tcp - ssh OpenSSH 8.0 ``` ### Vulnerability Results ``` 🚨 Vulnerabilities Found (2): [HIGH] Outdated Apache Version Apache 2.4.41 has known security vulnerabilities [MEDIUM] Missing Security Headers Server lacks important security headers ``` ### Technology Detection ``` 🛠️ Detected Technologies (4): Apache HTTP Server 2.4.41 (100% confidence) PHP 7.4 (95% confidence) WordPress 5.8 (90% confidence) jQuery 3.6.0 (85% confidence) ``` ## 🚨 Safety First! ### ⚠️ Before You Start 1. **Only test systems you own** or have explicit permission for 2. **Read the SECURITY.md** file thoroughly 3. **Start with passive scans** (--intensity passive) 4. **Respect rate limits** and don't overwhelm targets ### ✅ Good Practices ```bash # Safe reconnaissance (passive only) npm run cli auto pentest example.com --scope web --intensity passive # Validate targets before scanning npm run cli config validate example.com # Generate reports for documentation npm run cli report generate example.com --format html ``` ### ❌ What NOT to Do - Don't scan without permission - Don't use aggressive intensity on production systems - Don't ignore rate limiting warnings - Don't skip authorization checks ## 🔍 Common Use Cases ### Bug Bounty Research ```bash # Subdomain discovery npm run cli recon subdomains target.com # Technology fingerprinting npm run cli recon tech https://target.com # Vulnerability assessment npm run cli vuln nuclei https://target.com --severity high ``` ### Internal Assessment ```bash # Network discovery npm run cli recon nmap 10.0.1.0/24 --type quick # Service enumeration npm run cli vuln nuclei 10.0.1.100 --templates network # Full automated assessment npm run cli auto pentest 10.0.1.100 --scope full --intensity active ``` ### Compliance Testing ```bash # Web security assessment npm run cli auto pentest https://internal-app.com --scope web --intensity active # Generate compliance report npm run cli report generate internal-app.com --format html ``` ## 🛠️ Troubleshooting ### Common Issues #### "Command not found: nmap" ```bash # Install missing tools sudo apt install nmap nikto sqlmap npm run install-tools ``` #### "Permission denied" ```bash # Some tools need sudo sudo npm run install-tools # Or install manually sudo apt install nmap nikto sqlmap ``` #### "Rate limit exceeded" ```bash # Wait a moment and try again with lower intensity npm run cli recon nmap target.com --type quick # Instead of aggressive scans ``` #### "Target validation failed" ```bash # Check if target is allowed npm run cli config validate your-target.com # Some networks are blocked for safety # Edit config to allow if you have permission ``` ### Getting Help ```bash # Show available commands npm run cli --help # Show command-specific help npm run cli recon --help npm run cli vuln nuclei --help # Check configuration npm run cli config show ``` ## 🎓 Next Steps ### Learn More 1. Read the full [README.md](README.md) 2. Check [usage examples](examples/usage-examples.md) 3. Review [security policy](SECURITY.md) ### Advanced Usage 1. **Custom Workflows**: Build automated testing pipelines 2. **Integration**: Connect with SIEM, CI/CD, and other tools 3. **Extension**: Add custom tools and techniques ### Get Involved 1. **Report Issues**: Help improve the framework 2. **Contribute**: Add new features and tools 3. **Share**: Help others learn ethical hacking ## 📞 Support - 📖 **Documentation**: Check README.md and examples/ - 🐛 **Issues**: Report bugs on GitHub - 💬 **Discussions**: Join community discussions - 🔐 **Security**: Contact security@example.com for security issues --- **Happy Ethical Hacking! 🎯** Remember: *With great power comes great responsibility.*