pentester-mcp-security-tools

# 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.