MCPPentestBOT

# 🛡️ MCPPentestBOT > AI-Powered Security Testing Toolkit Built on Model Context Protocol (MCP) An intelligent penetration testing assistant that seamlessly integrates professional security tools with AI language models through the Model Context Protocol standard. --- ## 📖 What is MCPPentestBOT? MCPPentestBOT brings enterprise-grade security testing capabilities to AI assistants like AZURE , Claude and GPT-4. Built on the **Model Context Protocol (MCP)**, it provides a standardized, universal interface for AI-powered penetration testing and security assessments. Instead of manually running security tools and interpreting results, security professionals can now have natural conversations with AI assistants that directly execute scans, analyze vulnerabilities, and provide actionable insights. --- ## 🎯 Why MCP? The **Model Context Protocol (MCP)** is an open standard that enables secure, structured communication between AI applications and external tools. Here's why it matters for security testing: | Benefit | Description | |---------|-------------| | **🔌 Universal Compatibility** | Works seamlessly with any MCP-enabled AI platform - no custom integrations needed | | **🔒 Secure & Structured** | Type-safe, validated communication between AI and security tools | | **🚀 Zero Setup** | Standardized tool definitions mean instant recognition by AI assistants | | **🔧 Easy Extension** | Add new security tools using MCP's plugin architecture without code changes | | **🌐 Ecosystem Ready** | Part of the growing MCP ecosystem with thousands of compatible tools | --- ## ✨ Key Features ### Security Testing Tools - **🔐 SSL/TLS Certificate Analysis** Complete certificate validation, expiration checks, cipher strength analysis, and protocol security assessment - **📋 HTTP Security Headers Audit** Comprehensive analysis of security headers including HSTS, CSP, X-Frame-Options, and security recommendations - **🔍 Port Scanning & Service Detection** Advanced network reconnaissance using industry-standard Nmap with service version detection - **🕸️ Web Vulnerability Scanning** Deep web application security testing with Nikto for common vulnerabilities and misconfigurations - **📡 Network Discovery** Efficient host discovery across networks using ICMP ping sweeps and network mapping - **⚡ Connectivity Testing** Quick port accessibility checks for service availability and firewall verification ### Technical Advantages - ✅ **AI-Native Design** - Purpose-built for seamless LLM integration - ✅ **Async Architecture** - High-performance concurrent scanning capabilities - ✅ **Direct Integration** - No subprocess overhead or JSON-RPC complexity - ✅ **Structured Output** - Clean JSON responses optimized for AI processing - ✅ **Type Safety** - Full type hints and validated inputs/outputs - ✅ **Extensible** - Easy to add custom security tools and workflows --- ## 🚀 Getting Started ### Prerequisites **System Requirements:** - Python 3.8 or higher - Operating System: Linux, macOS, or Windows (WSL recommended) **Required Security Tools:** ```bash # Ubuntu/Debian sudo apt-get install nmap nikto openssl # macOS brew install nmap nikto openssl ``` ### Installation 1. **Clone the Repository** ```bash git clone https://github.com/kannanprabu/MCPPentestBOT.git cd MCPPentestBOT ``` 2. **Install Python Dependencies** ```bash pip install -r requirements.txt ``` 3. **Verify Installation** ```bash python llm_client.py --version ``` ### Configuration **For Claude Desktop Users:** Add to your configuration file at `~/Library/Application Support/Claude/claude_desktop_config.json`: ```json { "mcpServers": { "pentestbot": { "command": "python", "args": ["/absolute/path/to/MCPPentestBOT/llm_client.py"] } } } ``` **For Direct Python Integration:** Configure your environment variables in `.env`: ``` LOG_LEVEL=INFO NMAP_TIMEOUT=300 NIKTO_TIMEOUT=600 ``` --- ## 💡 Usage Examples ### Using with AI Assistants Once configured, simply ask your AI assistant natural language questions: - *"Check the SSL certificate for github.com"* - *"Scan ports 80 and 443 on example.com"* - *"Analyze HTTP security headers for my website"* - *"Perform a comprehensive security assessment on 192.168.1.1"* The AI will automatically select and execute the appropriate security tools, interpret results, and provide actionable recommendations. ### Direct Python Usage ```python from pentestgpt.tools import ssl_check import asyncio # Run a security check result = asyncio.run(ssl_check(target="example.com")) print(result) ``` --- ## 🔧 Available Security Tools | Tool | Purpose | Use Case | |------|---------|----------| | **ssl_check** | SSL/TLS certificate and security analysis | Certificate validation, expiration monitoring, cipher assessment | | **http_headers** | HTTP security headers evaluation | Security posture assessment, compliance checking | | **nmap_scan** | Network port scanning and service detection | Infrastructure discovery, attack surface mapping | | **nikto_scan** | Web application vulnerability scanning | Web server security testing, configuration auditing | | **ping_sweep** | Network host discovery | Network mapping, live host identification | | **port_check** | Individual port connectivity testing | Service availability verification, firewall testing | --- ## ⚖️ Legal & Ethical Use ### ⚠️ Important Legal Notice **MCPPentestBOT is designed for authorized security testing only.** **You MUST:** - ✅ Obtain explicit written permission before testing any system - ✅ Only test systems and networks you own or have authorization to assess - ✅ Follow responsible disclosure practices for any vulnerabilities found - ✅ Comply with all applicable laws and regulations in your jurisdiction - ✅ Respect privacy and handle discovered data responsibly **You MUST NOT:** - ❌ Test systems without proper authorization - ❌ Use for malicious purposes or unauthorized access - ❌ Violate terms of service or acceptable use policies - ❌ Access, modify, or exfiltrate data without permission ### Best Practices - Follow the [OWASP Testing Guide](https://owasp.org/www-project-web-security-testing-guide/) - Adhere to [PTES (Penetration Testing Execution Standard)](http://www.pentest-standard.org/) - Respect [Bug Bounty Program Rules](https://www.bugcrowd.com/resources/) **Unauthorized use of this tool may violate computer crime laws. Users are solely responsible for ensuring their use complies with all applicable laws.** --- ## 🛠️ Configuration & Settings ### Environment Variables Create a `.env` file in the project root: ```env # Logging Configuration LOG_LEVEL=INFO LOG_FILE=pentestbot.log # Tool Timeouts (seconds) NMAP_TIMEOUT=300 NIKTO_TIMEOUT=600 SSL_TIMEOUT=30 # Performance MAX_CONCURRENT_SCANS=3 ``` ### Custom Tool Configuration Advanced users can customize tool behavior by editing `config.yaml` to adjust timeout values, scan parameters, and output formats. --- ## 🐛 Troubleshooting ### Common Issues **"Command not found: nmap/nikto/openssl"** - Install the required system tools using your package manager - Verify installation: `which nmap nikto openssl` **"Permission denied" errors** - Some network operations require elevated privileges - Run with `sudo` or add capabilities: `sudo setcap cap_net_raw+eip $(which python3)` **Module import errors** - Ensure all dependencies are installed: `pip install -r requirements.txt` - Verify Python version: `python --version` (3.8+ required) **Timeout errors** - Increase timeout values in `.env` configuration - Check network connectivity to target systems --- ## 🤝 Contributing We welcome contributions from the security community! **How to Contribute:** 1. Fork the repository 2. Create a feature branch (`git checkout -b feature/amazing-tool`) 3. Commit your changes (`git commit -m 'Add amazing security tool'`) 4. Push to the branch (`git push origin feature/amazing-tool`) 5. Open a Pull Request **Contribution Ideas:** - Add new security tools and integrations - Improve documentation and examples - Report bugs and suggest enhancements - Share usage patterns and workflows --- ## 📄 License This project is licensed under the **MIT License**. ``` Copyright (c) 2024 MCPPentestBOT Contributors Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software. ``` See [LICENSE](LICENSE) file for full details. --- ## Educational Test Targets For learning and practice, use these intentionally vulnerable applications: * **http://testphp.vulnweb.com** - Vulnerable PHP application * **scanme.nmap.org** - Nmap's official test server * **http://demo.testfire.net** - IBM's intentionally vulnerable banking app * **DVWA, WebGoat, Mutillidae** - Local vulnerable applications --- ## Contributing We welcome contributions from the security community: 1. **Fork** the repository 2. **Create** a feature branch for your enhancement 3. **Test** thoroughly with various target types 4. **Submit** a pull request with detailed descriptions 5. **Follow** responsible disclosure for any security issues ### Development Guidelines - Implement proper error handling and timeouts - Follow security best practices in code development - Include comprehensive documentation - Test across different environments and targets - Maintain focus on authorized testing scenarios --- ## Support and Documentation * **Integration Guide**: Detailed Claude Desktop setup instructions * **Tool Documentation**: Comprehensive usage examples and workflows * **Security Best Practices**: Guidelines for responsible testing * **Troubleshooting**: Common issues and solutions * **Community Forums**: User discussions and support --- ## Contributors Thanks to all the security professionals who contributed: * Kannan Prabu Ramamoorthy --- ## Disclaimer This tool is provided "as is" for educational and authorized testing purposes only. Users are solely responsible for compliance with applicable laws, regulations, and organizational policies. The authors assume no liability for misuse or unauthorized activities conducted with this tool. **Always practice responsible disclosure and ethical security testing.** Built with ❤️ by Security Professionals, for Security Professionals [](https://github.com/kannanprabu/MCPPentestBOT) [](https://opensource.org/licenses/MIT) [](https://www.python.org/downloads/) [⬆ Back to Top](#-mcppentestbot) </div>