Model Context Provider (MCP) for Penetration Testing
⚠️ 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 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: Network discovery and security auditing
- Masscan: High-speed port scanner
Web Enumeration
- Gobuster: Directory and file brute forcing
- Nikto: Web server scanner for vulnerabilities
Exploitation & Post-Exploitation
Password Attacks
Privilege Escalation
- LinPEAS: 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
- Clone this repository:
git clone https://github.com/allsmog/mcp-pentest.git
cd mcp-pentest
- Build the Docker containers:
docker-compose build
- Start the MCP services:
docker-compose up -d
Basic Usage
- Create a new penetration testing engagement:
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"]}}'
- Start a reconnaissance scan:
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"}}'
- Query the AI assistant:
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 for complete API references and examples.
📋 Project Roadmap
Here's what we're currently working on:
We welcome contributions to any of these areas!
🤝 Contributing
Contributions are welcome and appreciated! Please see CONTRIBUTING.md for guidelines.
How You Can Help
We're particularly looking for help with:
- Tool Integrations : Adding support for more security tools
- Testing : Real-world testing and bug reporting
- Documentation : Improving and expanding guides
- UI Development : Building the web interface
- 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 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 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
🙏 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
