https://github.com/allsmog/mcp-pentest
MCP server for pentesting operations (WIP)
https://github.com/allsmog/mcp-pentest
Last synced: about 1 month ago
JSON representation
MCP server for pentesting operations (WIP)
- Host: GitHub
- URL: https://github.com/allsmog/mcp-pentest
- Owner: allsmog
- License: mit
- Created: 2025-03-03T15:59:40.000Z (2 months ago)
- Default Branch: main
- Last Pushed: 2025-03-03T16:19:18.000Z (2 months ago)
- Last Synced: 2025-03-03T17:26:26.801Z (2 months ago)
- Language: Python
- Size: 41 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
- awesome-hacking-lists - allsmog/mcp-pentest - An MCP server for pentesting. Contributors wanted! (Python)
README
# Model Context Provider (MCP) for Penetration Testing
An AI-driven assistant and middleware for penetration testing engagements
[](https://opensource.org/licenses/MIT)
[](https://www.python.org/downloads/)
[](https://www.docker.com/)
[](https://github.com/yourusername/mcp-pentest)
## ⚠️ Work In Progress - Contributors Wanted!
**MCP is currently under active development and in alpha stage.** We're looking for contributors to help build out this exciting project! Whether you're interested in:
- Implementing new tool integrations
- Improving the AI assistant's capabilities
- Enhancing the UI/UX
- Writing documentation
- Testing the system
Your contributions are welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for how to get started.
## 🔍 Overview
The Model Context Provider (MCP) is an open-source framework that bridges AI with penetration testing tools. MCP interfaces with a wide array of pentesting tools, parses and enriches their output in real-time, and strictly follows the standard penetration testing process. It guides human pentesters through each phase – from reconnaissance and scanning to exploitation, post-exploitation, and reporting – aligning with established methodologies.
> ⚠️ **Disclaimer**: This tool is intended for legal security testing with proper authorization. Misuse of this software for unauthorized access to systems is illegal and unethical.
## ✨ Key Features
- **Methodology Enforcement**: Ensures each engagement progresses through proper phases (reconnaissance → scanning → exploitation → post-exploitation → reporting) in order.
- **Real-time Context Aggregation**: Captures tool outputs, normalizes the data into a unified engagement context, and stores it for analysis.
- **LLM-Powered Insights**: Leverages a large language model to interpret findings and provide guidance during the engagement.
- **Seamless Tool Integration**: Acts as a middleware layer that hooks into major pentest tools, converting their results into a common event format.
- **Secure Data Handling**: Enforces strict security on processed data, including sanitization when interacting with the LLM.
- **Reporting and Knowledge Retention**: Logs all findings and actions in a structured format for report generation.
## 🏗️ Architecture
MCP is built on a microservices-based, event-driven system deployed in a containerized environment:
- **Core Context Processing Engine**: Central brain that aggregates and normalizes data from all tools
- **AI-Powered Attack Path Analyzer**: Identifies potential attack paths and prioritizes targets
- **Plugin-Based Integration Framework**: Extensible system for interfacing with external tools
- **Secure Logging & Reporting Module**: Maintains engagement logs and produces reports
- **Real-Time LLM Query Interface**: Provides natural language interface for querying findings
- **Role-Based Access Control**: Enforces security across all operations
## 🧰 Integrated Tools
MCP currently integrates with the following tools:
### Network Scanning & Enumeration
- [Nmap](https://nmap.org/): Network discovery and security auditing
- [Masscan](https://github.com/robertdavidgraham/masscan): High-speed port scanner
### Web Enumeration
- [Gobuster](https://github.com/OJ/gobuster): Directory and file brute forcing
- [Nikto](https://github.com/sullo/nikto): Web server scanner for vulnerabilities
### Exploitation & Post-Exploitation
- [Metasploit Framework](https://www.metasploit.com/): Exploitation framework
### Password Attacks
- [Hydra](https://github.com/vanhauser-thc/thc-hydra): Network login brute-force tool
- [John the Ripper](https://www.openwall.com/john/): Offline password cracker
### Privilege Escalation
- [LinPEAS](https://github.com/carlospolop/PEASS-ng): Linux Privilege Escalation enumeration script
## 🚀 Getting Started
### Prerequisites
- Docker and Docker Compose
- Python 3.8+
- Network connectivity to target environments
- Proper authorizations and scope definitions for penetration testing
### Installation
1. Clone this repository:
```bash
git clone https://github.com/allsmog/mcp-pentest.git
cd mcp-pentest
```
2. Build the Docker containers:
```bash
docker-compose build
```
3. Start the MCP services:
```bash
docker-compose up -d
```
### Basic Usage
1. Create a new penetration testing engagement:
```bash
curl -X POST http://localhost:8000/api/engagements -H "Content-Type: application/json" -d '{"name": "Example Corp Assessment", "scope": {"ip_ranges": ["192.168.1.0/24"], "domains": ["example.com"]}}'
```
2. Start a reconnaissance scan:
```bash
curl -X POST http://localhost:8000/api/tasks -H "Content-Type: application/json" -d '{"engagement_id": "YOUR_ENGAGEMENT_ID", "tool": "theHarvester", "parameters": {"target": "example.com"}}'
```
3. Query the AI assistant:
```bash
curl -X POST http://localhost:8000/api/query -H "Content-Type: application/json" -d '{"engagement_id": "YOUR_ENGAGEMENT_ID", "query": "What are the most promising attack vectors based on our current findings?"}'
```
See our [documentation](docs/API_SPECIFICATION.md) for complete API references and examples.
## 📋 Project Roadmap
Here's what we're currently working on:
- [ ] Completing core Context Engine implementation
- [ ] Finishing initial tool integrations
- [ ] Building the AI-powered attack path analyzer
- [ ] Developing the web UI
- [ ] Creating comprehensive test suite
- [ ] Adding additional tool integrations
- [ ] Implementing report generation
We welcome contributions to any of these areas!
## 🤝 Contributing
Contributions are welcome and appreciated! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
### How You Can Help
We're particularly looking for help with:
1. **Tool Integrations**: Adding support for more security tools
2. **Testing**: Real-world testing and bug reporting
3. **Documentation**: Improving and expanding guides
4. **UI Development**: Building the web interface
5. **AI Components**: Enhancing LLM integration and attack path analysis
### Adding New Tool Integrations
We especially welcome contributions for new tool integrations. See our [Tool Integration Guide](docs/TOOL_INTEGRATION.md) for how to add support for additional tools.
## 💬 Community
- **Issues**: Use GitHub issues for bug reports and feature requests
- **Discussions**: GitHub discussions for general questions and ideas
## 📜 License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## 🔐 Security Considerations
Given the nature of this tool, please be especially mindful of security:
- Never commit credentials, API keys, or sensitive information
- Always follow responsible disclosure practices
- Ensure proper authorization before testing any systems
## 📚 Documentation
- [API Reference](docs/API_SPECIFICATION.md)
- [Architecture Guide](docs/ARCHITECTURE.md)
- [Tool Integration Guide](docs/TOOL_INTEGRATION.md)
- [Deployment Guide](docs/DEPLOYMENT.md)
## 🙏 Acknowledgments
- Thanks to all the open-source penetration testing tools this project builds upon
- Special recognition to the security researchers and tool developers who inspire this work