📌Overview

Purpose: The Model Context Provider (MCP) aims to enhance penetration testing engagements by integrating AI technologies with existing pentesting tools for a more streamlined and effective testing process.

Overview: MCP is an open-source framework designed to act as a middleware that connects AI capabilities with a variety of penetration testing tools. It assists human pentesters throughout the entire testing lifecycle by parsing, enriching, and optimizing tool outputs while ensuring adherence to established testing methodologies.

Key Features:

Methodology Enforcement: Guarantees that each penetration testing engagement follows a structured approach, progressing through designated phases systematically.
Real-time Context Aggregation: Collects and normalizes outputs from various tools into a cohesive context for improved analysis and decision-making.
LLM-Powered Insights: Utilizes a large language model to generate insights and provide contextual guidance based on the findings during the engagement.
Seamless Tool Integration: Functions as a middleware that easily connects with major pentesting tools, enabling conversion of their outputs to a unified format.
Secure Data Handling: Prioritizes security by ensuring proper data sanitization and protection during processing interactions with the AI model.
Reporting and Knowledge Retention: Maintains a detailed log of findings and activities, facilitating efficient report generation for subsequent analysis or documentation.

Model Context Provider (MCP) for Penetration Testing

An AI-driven assistant and middleware for penetration testing engagements

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

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

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

Contributions are welcome!

🤝 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

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