# 🛡️ Pentest-MCP

**A Production-Ready Penetration Testing Toolkit for AI Agents**

Pentest-MCP is a powerful, enterprise-grade framework that exposes penetration testing tools to Large Language Models (LLMs) through both REST API and Model Context Protocol (MCP). Built with Docker containerization, intelligent caching, and comprehensive security policies, it enables AI agents to perform automated security assessments safely and efficiently.

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
[![Docker](https://img.shields.io/badge/docker-%230db7ed.svg?logo=docker&logoColor=white)](https://www.docker.com/)
[![FastAPI](https://img.shields.io/badge/FastAPI-005571?logo=fastapi)](https://fastapi.tiangolo.com/)

---
## ▶️ Demo
[![PentestMCP](https://img.youtube.com/vi/6X1dZ02Oum4/0.jpg)](https://youtu.be/6X1dZ02Oum4)


## 🌟 Features

### 🎯 Dual Protocol Support
- **REST API**: Traditional HTTP endpoints for maximum compatibility
- **MCP Native**: First-class support for Claude Desktop, Cline, and other MCP clients
- **Unified Core**: Single codebase powers both interfaces

### 🔒 Enterprise Security
- **Policy Engine**: Network restrictions, rate limiting, and authorization controls
- **API Key Authentication**: Secure access control for all endpoints
- **Network Isolation**: Only private RFC 1918 networks allowed by default
- **Audit Logging**: Complete execution history with JSON logging

### 🐳 Docker Architecture
- **Isolated Execution**: Each tool runs in dedicated Kali Linux containers
- **Automatic Building**: Smart image caching and dependency management
- **Shared Resources**: Common wordlists and results volumes
- **Network Access**: Controlled host network mode for scanning

### 🧠 AI-Optimized Design
- **Rich Descriptions**: Every tool includes context, examples, and usage hints
- **Structured Output**: Automatic parsing of tool output (nmap, gobuster, etc.)
- **Input Validation**: Pydantic models ensure type safety
- **Intelligent Caching**: Results cached for 1 hour to reduce redundant scans

### 🛠️ Included Tools
- **nmap**: Network discovery and vulnerability scanning
- **gobuster**: Web content and vhost enumeration
- **enum4linux**: SMB/Active Directory enumeration
- **crackmapexec**: Post-exploitation and lateral movement testing

---

## 📋 Table of Contents

- [Quick Start](#-quick-start)
- [Architecture](#-architecture)
- [Installation](#-installation)
- [Configuration](#-configuration)
- [Usage](#-usage)
  - [REST API](#rest-api)
  - [MCP Integration](#mcp-integration)
- [Tool Development](#-tool-development)
- [Security](#-security)
- [API Reference](#-api-reference)
- [Contributing](#-contributing)
- [License](#-license)

---

## 🚀 Quick Start

### Prerequisites
- Docker & Docker Compose
- Python 3.11+
- Make (usually pre-installed on Linux/macOS)
- 4GB+ RAM recommended

### Installation (Using Makefile - Recommended)

```bash
# Clone the repository
git clone https://github.com/sasaga/PentestMCP.git
cd pentest-mcp

# See all available commands
make help

# Complete setup in one command
make setup              # Create directories
cp .env.example .env    # Copy environment template
nano .env               # Configure your API_KEY

# Build all Docker images
make build-all          # Builds base image + all tool images

# Start services
make up                 # Starts REST API + MCP Server

# Verify installation
make test               # Run system tests
```

### Alternative: Manual Installation

```bash
# Set up environment
cp .env.example .env
nano .env

# Build images
./build_images.sh

# Start services
docker-compose up -d

# Verify
curl http://localhost:8085/health
```

### First Scan

```bash
# List available tools
curl http://localhost:8085/tools | jq

# Run an nmap scan
curl -X POST http://localhost:8085/invoke \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "name": "nmap",
    "mode": "nmap_host_discovery",
    "args": {"target": "192.168.1.0/24"}
  }' | jq
```

### 🎯 Makefile Commands Reference

The Makefile is the **central management tool** for this project. Key commands:

| Command | Description |
|----------|-------------|
| `make help` | Show this help message |
| `make setup` | Create required directories (e.g., `wordlists` and `results`) |
| `make build-base` | Build the base Kali Linux image |
| `make build-app` | Build the main application image (FastAPI / MCP) |
| `make build-<tool>` | Build specific tool (e.g., `make build-nmap`) |
| `make build-tools` | Build all tool images defined in YAML files |
| `make build-all` | Build all images (base + app + tools) |
| `make check-images` | Verify which Docker images are built |
| `make list-images` | List all Pentest-MCP Docker images |
| `make clean-images` | Remove all Pentest-MCP Docker images |
| `make clean-containers` | Remove all Pentest-MCP containers |
| `make clean` | Perform a full cleanup (containers + images) |
| `make up` | Start all services using Docker Compose |
| `make down` | Stop all running services |
| `make logs` | View logs from all running services |
| `make restart` | Restart services (rebuild app if changes detected) |
| `make test` | Run full system tests (uses `.env` configuration) |
| `make test-api` | Perform a quick REST API health test |
| `make validate-yaml` | Validate syntax of all YAML configuration files |
| `make fix-yaml-paths` | Fix or normalize Docker paths in YAML files |
| `make show-docker-config` | Display Docker configuration detected in YAMLs |
| `make dev` | Start the system in development mode |
| `make dev-mcp` | Run the MCP server in standalone mode |
| `make info` | Display detailed system and environment information |

**See full Makefile documentation below.**

---

## 🏗️ Architecture

```
┌─────────────────────────────────────────────────────────────┐
│                        Client Layer                          │
│  Claude Desktop │ Cline │ HTTP Clients │ Custom Integrations│
└────────────┬────────────────────────────────────────────────┘
             │
    ┌────────┴─────────┐
    │                  │
┌───▼────┐      ┌─────▼──────┐
│ MCP    │      │  REST API  │
│ Server │      │  (FastAPI) │
│ :8090  │      │   :8085    │
└───┬────┘      └─────┬──────┘
    │                 │
    └────────┬────────┘
             │
    ┌────────▼─────────┐
    │   Core Engine    │
    │  ┌────────────┐  │
    │  │  Loader    │  │  YAML → Pydantic Models
    │  ├────────────┤  │
    │  │  Policy    │  │  Security Validation
    │  ├────────────┤  │
    │  │  Executor  │  │  Docker Management
    │  ├────────────┤  │
    │  │  Parser    │  │  Output Structuring
    │  └────────────┘  │
    └──────────────────┘
             │
    ┌────────▼─────────┐
    │ Docker Manager   │
    │  - Image Build   │
    │  - Container Run │
    │  - Volume Mount  │
    └────────┬─────────┘
             │
    ┌────────▼─────────┐
    │  Tool Containers │
    │  ┌──────────┐    │
    │  │  nmap    │    │
    │  ├──────────┤    │
    │  │ gobuster │    │
    │  ├──────────┤    │
    │  │enum4linux│    │
    │  ├──────────┤    │
    │  │   cme    │    │
    │  └──────────┘    │
    └──────────────────┘
```

### Key Components

1. **Server Layer** (`server.py`, `mcp_server.py`)
   - Dual protocol support (REST + MCP)
   - Request validation and routing
   - Authentication and rate limiting

2. **Core Engine** (`core/`)
   - **Loader**: Converts YAML tool definitions to Pydantic models
   - **Policy**: Enforces network restrictions and security rules
   - **Executor**: Manages Docker containers and command execution
   - **Parser**: Extracts structured data from tool output

3. **Docker Manager** (`docker_manager.py`)
   - Automatic image building with caching
   - Ephemeral container lifecycle
   - Volume management for wordlists and results

4. **Tool Definitions** (`tools/*.yaml`)
   - Declarative tool configuration
   - Schema generation for AI agents
   - Examples and usage hints

---

## 📦 Installation

### Option 1: Quick Install with Makefile (Recommended)

```bash
# Clone and enter directory
git clone https://github.com/sasaga/PentestMCP.git
cd pentest-mcp

# View all available commands
make help

# Setup directories
make setup

# Configure environment
cp .env.example .env
nano .env  # Set your API_KEY

# Build everything
make build-all

# Start services
make up

# Verify installation
make test
```

### Option 2: Docker Compose (Manual)

```bash
# Clone and configure
git clone https://github.com/sasaga/PentestMCP.git
cd pentest-mcp
cp .env.example .env

# Edit configuration
nano .env

# Build and start
docker-compose up -d

# Check logs
docker-compose logs -f
```

### Option 3: Manual Setup (Development)

```bash
# Install Python dependencies
pip install -r requirements.txt

# Build Docker images
./build_images.sh

# Download wordlists (optional)
mkdir -p wordlists
cd wordlists
wget https://github.com/danielmiessler/SecLists/raw/master/Discovery/Web-Content/common.txt

# Start services
uvicorn server:app --host 0.0.0.0 --port 8085 &
python mcp_server.py &
```

**💡 Pro Tip:** Use `make help` to see all available commands at any time.

---

## ⚙️ Configuration

### Environment Variables

Create a `.env` file:

```bash
# Security
API_KEY=your-secret-api-key-here

# Server Ports
REST_PORT=8085
MCP_PORT=8090
MCP_PROXY_PORT=8091

# Paths
TOOLS_DIR=/app/tools
WORDLISTS_DIR=/app/wordlists
RESULTS_DIR=/app/results

# Docker
KALI_IMAGE=pentest-kali-base

# Caching
ENABLE_CACHE=true
CACHE_TTL_HOURS=1

# Logging
LOG_LEVEL=INFO
```

### Network Policies

Edit `tools/*.yaml` to configure allowed networks:

```yaml
policy:
  allowed_networks:
    - "10.0.0.0/8"
    - "172.16.0.0/12"
    - "192.168.0.0/16"
  max_hosts: 4096
  blocked_ports: []
```

---

## 🎮 Usage

### REST API

#### List Available Tools

```bash
curl http://localhost:8085/tools | jq
```

#### Execute a Tool

```bash
curl -X POST http://localhost:8085/invoke \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "name": "nmap",
    "mode": "nmap_tcp_ports_syn_scan",
    "args": {
      "target": "192.168.1.100"
    }
  }' | jq
```

#### List Wordlists

```bash
curl http://localhost:8085/wordlists | jq
```

#### Check Health

```bash
curl http://localhost:8085/health | jq
```

### MCP Integration

#### Claude Desktop

Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "PentestMCP": {
      "command": "python3",
      "args": ["/path/to/pentest-mcp/mcp_wrapper.py"],
      "env": {
        "MCP_SERVER_URL": "http://127.0.0.1:8091/mcp",
        "API_KEY": "your-api-key-here"
      }
    }
  }
}
```

#### Cline (VSCode Extension)

Add to `.vscode/settings.json`:

```json
{
  "cline.mcpServers": {
    "PentestMCP": {
      "type": "http",
      "url": "http://127.0.0.1:8091/mcp",
      "headers": {
        "x-api-key": "your-api-key-here"
      }
    }
  }
}
```

#### 5ire client MCP

```json
{
  "name": "PentestMCP",
  "key": "PentestMCP",
  "url": "http://127.0.0.1:8091/mcp",
  "headers": {
    "x-api-key": "your-api-key-here"
  },
  "approvalPolicy": "always"
}
```

#### Warp MCP Config

```json
{
  "PentestMCP": {
    "command": "python3",
    "args": [
      "/path/mcp_wrapper.py"
    ],
    "env": {
      "API_KEY": "your-api-key-here",
      "MCP_SERVER_URL": "http://127.0.0.1:8091/mcp"
    },
    "working_directory": null
  }
}
```

#### Cursor MCP Config

```json
{
  "mcpServers": {
    "PentestMCP": {
      "type": "http",
      "url": "http://127.0.0.1:8091/mcp",
      "headers": {
        "x-api-key": "your-api-key-here"
      }
    }
  }
}
```

#### Direct MCP Client

```bash
# HTTP transport
TRANSPORT=http python mcp_server.py

# stdio transport (for direct integration)
TRANSPORT=stdio python mcp_server.py
```

---

## 🛠️ Makefile - Complete Reference

The Makefile is the **central management interface** for Pentest-MCP. It provides a unified, user-friendly way to build, test, deploy, and manage the entire system.

### Design Philosophy

The Makefile is **dynamic** and **self-discovering**:
- Automatically detects tools from YAML definitions
- No hardcoded tool names
- Generates targets on-the-fly
- Color-coded output for better UX

### Core Commands

#### Setup & Installation

```bash
# Create required directories (wordlists, results)
make setup

# Show system information
make info
```

#### Docker Image Management

```bash
# Build everything (recommended for first setup)
make build-all          # Builds base + all tool images

# Build only base image
make build-base         # Kali Linux base

# Build specific tool
make build-nmap         # Just nmap
make build-gobuster     # Just gobuster
make build-enum4linux   # Just enum4linux
make build-crackmapexec # Just crackmapexec

# Verify what's built
make check-images       # Shows ✅/❌ for each image

# List all pentest images
make list-images
```

#### Service Management

```bash
# Start all services (REST API + MCP Server)
make up

# Stop services
make down

# Restart services (useful after code changes)
make restart

# View live logs
make logs
```

#### Testing & Validation

```bash
# Run complete system test suite
make test

# Quick API health check
make test-api

# Validate YAML syntax
make validate-yaml

# Show Docker configuration from YAMLs
make show-docker-config
```

#### Development

```bash
# Start REST API in development mode (with auto-reload)
make dev

# Start MCP server in stdio mode
make dev-mcp

# Fix YAML Docker paths (if needed)
make fix-yaml-paths
```

#### Cleanup

```bash
# Remove containers
make clean-containers

# Remove all pentest images
make clean-images

# Full cleanup (containers + images)
make clean
```

### Advanced Usage

#### Building Specific Tool After YAML Changes

```bash
# After modifying tools/nmap.yaml
make build-nmap

# After modifying tools/gobuster.yaml
make build-gobuster
```

#### Incremental Builds

The Makefile is smart about dependencies:

```bash
# This will check if base exists, build it if not, then build nmap
make build-nmap

# This rebuilds base, then all tools
make build-all
```

#### Parallel Testing

```bash
# Run tests in background, continue working
make test &

# Monitor logs in another terminal
make logs
```

### Makefile Architecture

```
Makefile
├── Variables
│   ├── PYTHON := python3
│   ├── COMPOSE := docker-compose
│   ├── DOCKER := docker
│   ├── TOOLS_DIR := .
│   └── DOCKERFILES_DIR := ./dockerfiles
│
├── Auto-Discovery
│   └── TOOLS_WITH_DOCKER (scans YAMLs for docker: config)
│
├── Static Targets
│   ├── help, setup, info
│   ├── build-base, build-all
│   ├── up, down, restart, logs
│   ├── test, test-api
│   └── clean, clean-images
│
└── Dynamic Targets
    └── build-% (e.g., build-nmap)
        ├── Validates tool exists in YAML
        ├── Builds base if needed
        └── Builds specific tool image
```

### Color Coding

The Makefile uses colors for better readability:
- 🟢 **GREEN**: Success messages
- 🟡 **YELLOW**: Info and warnings
- 🔴 **RED**: Errors
- 🔵 **BLUE**: Headers and titles

### Environment Integration

The Makefile respects `.env` variables:

```bash
# Example: Change log level for development
echo "LOG_LEVEL=DEBUG" >> .env
make dev
```

### Tips & Tricks

#### 1. Quick Status Check

```bash
make info check-images
```

#### 2. Rebuild After Tool Addition

```bash
# After creating tools/mytool.yaml and dockerfiles/Dockerfile.mytool
make build-mytool
make restart
make test-api
```

#### 3. Development Workflow

```bash
# Terminal 1: Development server
make dev

# Terminal 2: Logs
make logs

# Terminal 3: Testing
make test-api
```

#### 4. Production Deployment

```bash
make setup
make build-all
make up
make test
```

### Troubleshooting with Makefile

```bash
# Check what images exist
make check-images

# Verify services are running
make up
docker-compose ps

# View detailed logs
make logs

# Full rebuild (if things are broken)
make clean
make build-all
make up
```

### Customization

The Makefile is designed to be extended. Add your own targets:

```makefile
# Example: Add to Makefile
.PHONY: backup
backup: ## Backup results and wordlists
	@echo "Creating backup..."
	tar -czf pentest-backup-$(shell date +%Y%m%d).tar.gz results/ wordlists/
	@echo "✅ Backup created"
```

### CI/CD Integration

The Makefile works great in CI/CD pipelines:

```yaml
# Example: GitHub Actions
- name: Build and Test
  run: |
    make setup
    make build-all
    make test
```

### Why Makefile?

**Benefits:**
- ✅ **Single source of truth** for all operations
- ✅ **Self-documenting** with `make help`
- ✅ **Cross-platform** (Linux, macOS, WSL)
- ✅ **Dependency management** (base image before tools)
- ✅ **Developer friendly** (simple, memorable commands)
- ✅ **CI/CD ready** (easy to automate)

**vs Docker Compose alone:**
- Makefile provides higher-level abstractions
- Better error handling and feedback
- Testing and validation built-in
- Dynamic target generation

**vs Shell Scripts:**
- Better dependency tracking
- Parallel execution support
- Standard, well-known tool

---

## 🔧 Tool Development

### Adding a New Tool

1. **Create YAML Definition** (`tools/your_category/tool_name.yaml`)

```yaml
name: mytool
category: reconnaissance
description: |
  Brief description of what the tool does.
  
  **Use cases:**
  - Use case 1
  - Use case 2

docker:
  image: pentest-mytool:latest
  build:
    context: ./dockerfiles
    dockerfile: Dockerfile.mytool

functions:
  scan:
    description: |
      Detailed description of this function.
    
    command: "mytool {target} {options}"
    
    parameters:
      target:
        type: string
        format: ipv4
        description: Target to scan
        examples:
          - "192.168.1.10"
          - "10.0.0.0/24"
      
      options:
        type: string
        description: Additional options
        default: "-v"
    
    timeout: 300
    
    examples:
      - description: "Basic scan"
        input:
          function: scan
          args:
            target: "192.168.1.10"
            options: "-v"

policy:
  allowed_networks:
    - "10.0.0.0/8"
    - "172.16.0.0/12"
    - "192.168.0.0/16"
  max_hosts: 1024

hints:
  - "Start with basic options"
  - "Use verbose mode for debugging"
```

2. **Create Dockerfile** (`dockerfiles/Dockerfile.mytool`)

```dockerfile
FROM pentest-kali-base:latest

RUN apt-get update && apt-get install -y \
    mytool \
    && apt-get clean \
    && rm -rf /var/lib/apt/lists/*

WORKDIR /workspace

LABEL tool="mytool"
LABEL category="reconnaissance"
```

3. **Build and Test**

```bash
# Build image
./build_images.sh

# Test via REST API
curl -X POST http://localhost:8085/invoke \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "name": "mytool",
    "mode": "scan",
    "args": {"target": "192.168.1.10"}
  }' | jq
```

---

## 🔐 Security

### Best Practices

1. **Always use API keys** in production
2. **Restrict networks** via policy configuration
3. **Monitor audit logs** (`results/executions.log`)
4. **Review Docker privileges** (NET_ADMIN/NET_RAW required for scanning)
5. **Use HTTPS** in production with reverse proxy

### Network Isolation

By default, tools can only target private networks (RFC 1918):
- `10.0.0.0/8`
- `172.16.0.0/12`
- `192.168.0.0/16`
- `127.0.0.0/8`

### Rate Limiting

Configure in your reverse proxy (nginx, traefik) or use FastAPI middleware.

### Audit Trail

Every execution is logged:

```bash
tail -f results/executions.log
```

---

## 📚 API Reference

### REST Endpoints

| Method | Endpoint | Description |
|--------|----------|-------------|
| GET | `/` | API information |
| GET | `/health` | System health check |
| GET | `/tools` | List all available tools |
| POST | `/invoke` | Execute a tool |
| GET | `/wordlists` | List available wordlists |
| POST | `/reload` | Reload tool definitions |
| GET | `/cache/stats` | Cache statistics |
| DELETE | `/cache/clear` | Clear result cache |

### MCP Resources

- `pentest://tools` - Tool catalog
- `pentest://wordlists` - Wordlist inventory

### MCP Tools

All tools are automatically exposed as MCP functions with the format:
`{tool_name}_{function_name}`

Example: `nmap_tcp_ports_syn_scan`, `gobuster_directory_bruteforce`

---

## 🤝 Contributing

Contributions are welcome! Here's how:

1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-tool`)
3. Commit your changes (`git commit -m 'Add amazing tool'`)
4. Push to the branch (`git push origin feature/amazing-tool`)
5. Open a Pull Request

### Adding New Tools

Please ensure:
- Complete YAML definition with examples
- Dockerfile with minimal dependencies
- Security policy configuration
- Documentation in README

---

## 🐛 Troubleshooting

### Docker Issues

```bash
# Rebuild all images
./build_images.sh

# Check Docker connectivity
docker ps

# View container logs
docker logs pentest-mcp-app
```

### Port Conflicts

```bash
# Change ports in .env
REST_PORT=8086
MCP_PORT=8091

# Restart services
docker-compose restart
```

### Permission Errors

```bash
# Fix volume permissions
sudo chown -R $(id -u):$(id -g) wordlists results
```

---

## 📄 License

MIT License - see [LICENSE](LICENSE) file for details.

```
Copyright (c) 2025 Samir Sanchez Garnica

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, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
```

---

## 👤 Author

**Samir Sanchez Garnica**
- Email: samir.sanchez@hawktesters.com
- GitHub: [@sasaga](https://github.com/sasaga)

---

## 🙏 Acknowledgments

- [FastMCP](https://github.com/jlowin/fastmcp) - Modern MCP server framework
- [FastAPI](https://fastapi.tiangolo.com/) - High-performance web framework
- [Nmap](https://nmap.org/) - Network discovery tool
- [Gobuster](https://github.com/OJ/gobuster) - Directory/DNS busting
- [CrackMapExec](https://github.com/byt3bl33d3r/CrackMapExec) - Post-exploitation tool
- [enum4linux-ng](https://github.com/cddmp/enum4linux-ng) - SMB enumeration

---

## 📊 Project Stats

![GitHub stars](https://img.shields.io/github/stars/sasaga/pentest-mcp?style=social)
![GitHub forks](https://img.shields.io/github/forks/sasaga/pentest-mcp?style=social)
![GitHub watchers](https://img.shields.io/github/watchers/sasaga/pentest-mcp?style=social)

---

**⚠️ Disclaimer**: This tool is intended for authorized security testing only. Users are responsible for complying with all applicable laws and regulations. The authors assume no liability for misuse.