Model Context Provider (MCP) for Penetration Testing

<div align="center"> <img src="docs/images/mcp-logo.png" alt="MCP Logo" width="300" /> <br> <em>An AI-driven assistant and middleware for penetration testing engagements</em> <br><br>

</div>

⚠️ 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

• Metasploit Framework: Exploitation framework

Password Attacks

• Hydra: Network login brute-force tool
• John the Ripper: Offline password cracker

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

1. Clone this repository:

git clone https://github.com/allsmog/mcp-pentest.git
cd mcp-pentest

2. Build the Docker containers:

docker-compose build

3. Start the MCP services:

docker-compose up -d

Basic Usage

1. 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"]}}'

2. 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"}}'

3. 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:

• [ ] 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 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 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

• API Reference
• Architecture Guide
• Tool Integration Guide
• Deployment Guide

🙏 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