pentester-mcp-security-tools

Savant verdict: Review advised

Security analysis or source-hub review identified patterns requiring attention.

Live evaluation

Not evaluated yet. Workspaces can request a live evaluation.

Security assessment

Scan pending.

Structure

• No license declaredConfirm you may reuse this skill before importing it into your repository.
• The source hub's security checks flagged this skillGen Agent Trust Hub: fail (The skill integrates over 200 penetration testing tools into an AI agent environment. It requires downloading code from an untrusted external repository and includes instructions for granting the agent root privileges or passwordless sudo access. It also performs dynamic module loading and executes shell commands with user-supplied arguments.); Socket: warn (1 alert: gptSecurity); Snyk: warn (Risk: MEDIUM · 2 issues)

SKILL.md

---
name: pentester-mcp-security-tools
description: MCP server integrating 200+ penetration testing tools (nmap, sqlmap, ffuf, etc.) via Docker sandbox for AI-driven security testing
triggers:
  - run a penetration test with AI
  - scan a target with nmap through MCP
  - use pentester MCP tools for security testing
  - execute sqlmap or ffuf via Model Context Protocol
  - set up AI-powered penetration testing environment
  - configure pentester-mcp in Claude or Cursor
  - integrate cybersecurity tools with AI assistant
  - automate security scans using MCP server
---

# Pentester-MCP Security Tools

> Skill by [ara.so](https://ara.so) — Security Skills collection.

Pentester-MCP provides Model Context Protocol (MCP) integration for 200+ open-source penetration testing and cybersecurity tools. It enables AI assistants (Claude Desktop, Cursor, etc.) to autonomously execute security tools like `nmap`, `sqlmap`, `ffuf`, `gobuster`, `nuclei`, `impacket`, and hundreds more within a secure Docker sandbox.

Each tool is wrapped as an MCP server with AI-optimized documentation, safe argument handling, timeout enforcement, and output truncation to prevent shell injection and system pollution.

## Installation

### Docker Sandbox (Recommended)

The Docker approach isolates all 200+ tools in a container, avoiding host system pollution:

```bash
# Clone repository
git clone https://github.com/halilkirazkaya/pentester-mcp.git
cd pentester-mcp

# Configure desired tools in configs/example-config.yaml
# Set tools to true/false based on your needs

# Build and start container
docker compose up -d --build

# Verify container is running
docker ps | grep pentester-mcp
```

### Local Execution (Advanced)

For Kali Linux, Parrot OS, or systems with tools pre-installed:

```bash
# Clone and setup
git clone https://github.com/halilkirazkaya/pentester-mcp.git
cd pentester-mcp

# Create virtual environment
python3 -m venv .venv
source .venv/bin/activate

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

## Configuration

### Tool Selection

Edit `configs/example-config.yaml` to enable/disable tools:

```yaml
# Reconnaissance Tools
nmap: true
masscan: true
amass: true
subfinder: true
nuclei: true

# Web Exploitation
sqlmap: true
ffuf: true
gobuster: true
nikto: true
dirsearch: true

# Network & AD
impacket: true
responder: true
evil_winrm: true
bloodhound: false

# Password Tools
hydra: true
john: true
hashcat: false
```

### MCP Client Configuration

#### Claude Desktop

Add to `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "pentester_mcp": {
      "command": "docker",
      "args": [
        "exec",
        "-i",
        "pentester-mcp",
        "/app/.venv/bin/python",
        "/app/server.py"
      ]
    }
  }
}
```

#### Cursor

Add to Cursor's MCP settings:

```json
{
  "mcpServers": {
    "pentester_mcp": {
      "command": "docker",
      "args": [
        "exec",
        "-i",
        "pentester-mcp",
        "/app/.venv/bin/python",
        "/app/server.py"
      ]
    }
  }
}
```

#### Local Execution Configuration

For host-based execution, modify the configuration:

```json
{
  "mcpServers": {
    "pentester_mcp": {
      "command": "/path/to/pentester-mcp/.venv/bin/python",
      "args": ["/path/to/pentester-mcp/server.py"]
    }
  }
}
```

## Tool Categories & Examples

### Reconnaissance

**Nmap** - Network scanning and port enumeration:

```python
# tools/nmap_mcp.py structure (auto-generated)
import subprocess
from typing import Optional

def run_nmap(
    target: str,
    flags: str = "-sV -sC",
    timeout: int = 300
) -> dict:
    """
    Execute nmap scan against target.
    
    Args:
        target: IP or hostname to scan
        flags: Nmap flags (e.g., -sV -sC -p-)
        timeout: Maximum execution time in seconds
    """
    cmd = ["nmap"] + flags.split() + [target]
    result = subprocess.run(
        cmd,
        capture_output=True,
        text=True,
        timeout=timeout
    )
    return {
        "stdout": result.stdout[:8000],  # Truncated
        "stderr": result.stderr[:8000],
        "returncode": result.returncode
    }
```

**Usage via AI:**
- "Scan 192.168.1.1 with nmap using default scripts"
- "Run aggressive nmap scan on target.com"

### Web Exploitation

**SQLMap** - Automated SQL injection testing:

```python
# tools/sqlmap_mcp.py
def run_sqlmap(
    url: str,
    flags: str = "--batch --random-agent",
    timeout: int = 600
) -> dict:
    """
    Execute SQLMap against URL.
    
    Args:
        url: Target URL with parameter
        flags: SQLMap options
        timeout: Max execution time
    """
    cmd = ["sqlmap", "-u", url] + flags.split()
    # Safe execution without shell=True
    result = subprocess.run(cmd, capture_output=True, text=True, timeout=timeout)
    return {"output": result.stdout[:8000]}
```

**FFUF** - Web fuzzing:

```python
# tools/ffuf_mcp.py
def run_ffuf(
    url: str,
    wordlist: str,
    flags: str = "-c -v",
    timeout: int = 300
) -> dict:
    """
    Execute ffuf directory/file fuzzer.
    
    Args:
        url: Target URL with FUZZ keyword
        wordlist: Path to wordlist file
        flags: Additional ffuf options
    """
    cmd = ["ffuf", "-u", url, "-w", wordlist] + flags.split()
    result = subprocess.run(cmd, capture_output=True, text=True, timeout=timeout)
    return {"output": result.stdout[:8000]}
```

### Active Directory & Network

**Impacket Suite** - AD exploitation tools:

```python
# tools/impacket_secretsdump_mcp.py
def run_secretsdump(
    target: str,
    username: str,
    password: Optional[str] = None,
    hashes: Optional[str] = None,
    timeout: int = 300
) -> dict:
    """
    Extract credentials from domain controller.
    
    Args:
        target: DC IP or hostname
        username: Domain username
        password: Password (or use hashes)
        hashes: LM:NTLM hash format
    """
    cmd = ["secretsdump.py"]
    if hashes:
        cmd.extend(["-hashes", hashes])
    cmd.append(f"{username}@{target}")
    # Execute with proper error handling
    result = subprocess.run(cmd, capture_output=True, text=True, timeout=timeout)
    return {"credentials": result.stdout[:8000]}
```

### Password Cracking

**Hydra** - Brute force authentication:

```python
# tools/hydra_mcp.py
def run_hydra(
    target: str,
    service: str,
    username: str,
    wordlist: str,
    flags: str = "-t 4",
    timeout: int = 600
) -> dict:
    """
    Brute force login credentials.
    
    Args:
        target: Target IP/hostname
        service: Service (ssh, ftp, http-post-form, etc.)
        username: Username to test
        wordlist: Password list path
        flags: Additional options
    """
    cmd = ["hydra", "-l", username, "-P", wordlist] + flags.split() + [target, service]
    result = subprocess.run(cmd, capture_output=True, text=True, timeout=timeout)
    return {"results": result.stdout[:8000]}
```

## Common Patterns

### AI-Driven Recon Workflow

When an AI assistant has Pentester-MCP configured, it can autonomously chain tools:

1. **Initial Scan**: "Scan example.com for open ports"
   - AI executes: `nmap -sV -sC example.com`
   
2. **Web Discovery**: AI detects port 80/443 open
   - Auto-executes: `ffuf -u https://example.com/FUZZ -w /wordlists/common.txt`
   
3. **Vulnerability Testing**: AI finds `/admin` directory
   - Auto-executes: `sqlmap -u https://example.com/admin?id=1 --batch`

### Environment Variables for Credentials

Never hardcode secrets. Use environment variables:

```bash
# Set credentials in container
docker exec pentester-mcp sh -c 'export TARGET_USER=$TARGET_USER'

# Reference in AI queries
# "Use credentials from $TARGET_USER and $TARGET_PASS environment variables"
```

### Custom Tool Configurations

Create custom config files for specific engagements:

```yaml
# configs/web-pentest.yaml
nmap: true
ffuf: true
gobuster: true
sqlmap: true
nikto: true
nuclei: true
# Disable AD tools
impacket: false
bloodhound: false
responder: false
```

Update `docker-compose.yml` to use custom config:

```yaml
services:
  pentester-mcp:
    volumes:
      - ./configs/web-pentest.yaml:/app/config.yaml
```

## Unified Server Architecture

Instead of registering 235 individual MCP servers, Pentester-MCP uses a single unified server (`server.py`) that dynamically loads enabled tools:

```python
# server.py (simplified structure)
from fastmcp import FastMCP
import importlib
import yaml

mcp = FastMCP("Pentester MCP")

# Load configuration
with open("config.yaml") as f:
    config = yaml.safe_load(f)

# Dynamically register enabled tools
for tool_name, enabled in config.items():
    if enabled:
        module = importlib.import_module(f"tools.{tool_name}_mcp")
        mcp.tool(module.run_tool)

# Start server
if __name__ == "__main__":
    mcp.run()
```

## Troubleshooting

### Container Not Running

```bash
# Check container status
docker ps -a | grep pentester-mcp

# View logs
docker logs pentester-mcp

# Restart container
docker compose down
docker compose up -d --build
```

### Tool Not Found Errors

If AI reports tool not found:

1. Verify tool is enabled in `configs/example-config.yaml`
2. Rebuild container: `docker compose up -d --build`
3. Check tool binary exists in container: `docker exec pentester-mcp which nmap`

### Timeout Issues

For long-running scans, increase timeout in tool invocation:

```python
# Most tools accept timeout parameter
run_nmap(target="10.0.0.0/24", flags="-p-", timeout=1800)  # 30 minutes
```

### Output Truncation

All tools truncate output to 8000 characters to prevent context overflow. For full output:

```bash
# Execute directly in container for full output
docker exec -it pentester-mcp nmap -p- target.com > full_output.txt
```

### Permission Denied (Local Execution)

When running locally, some tools require root:

```bash
# Run with sudo
sudo /path/to/.venv/bin/python server.py

# Or add user to sudoers for specific tools
echo "$USER ALL=(ALL) NOPASSWD: /usr/bin/nmap" | sudo tee /etc/sudoers.d/pentester
```

## Legal & Ethical Use

**CRITICAL**: Only use these tools on systems you own or have explicit written authorization to test. Unauthorized penetration testing is illegal. This project is for:

- Authorized security assessments
- Bug bounty programs with scope
- Educational lab environments
- Your own infrastructure testing

Always obtain proper authorization before running any security tools.