pentestMCP: KI-gestützte Penetrationstests über MCP

pentestMCP stellt eine leistungsstarke Brücke zwischen Large Language Models (LLMs) und praktischen Penetrationstest-Werkzeugen über das Model Context Protocol (MCP) bereit. Dieses Projekt fungiert als MCP-Server und stellt eine kuratierte Suite von über 20 Standard-Sicherheitsbewertungsprogrammen (Nmap, Nuclei, ZAP, SQLMap usw.) als aufrufbare „Tools" bereit. Dadurch können KI-Agenten in MCP-kompatiblen Clients (wie Claude Desktop oder bestimmten VS Code-Setups) diese Programme für automatisierte und interaktive Sicherheitsanalyseaufgaben nutzen.

Das Ziel ist es, die Steuerung komplexer Sicherheitsworkflows über natürliche Sprache zu ermöglichen, wodurch Pentesting-Fähigkeiten zugänglicher und in KI-gesteuerte Umgebungen integriert werden. Diese Arbeit ist inspiriert von Laurie Kirk's GhidraMCP.

Inhaltsverzeichnis

• Kernkonzepte & Architektur

• Hauptfunktionen

• Voraussetzungen

• Installation & Einrichtung

  • Verwendung des vorgefertigten Docker-Images (empfohlen)

  • Lokales Erstellen des Docker-Images

• Integration des Client-Hosts

  • Claude Desktop-Integration

  • VS Code Copilot Chat-Integration

• Tool-Referenz

• Sicherheitshinweise

• Mitwirken

• Lizenz

• Haftungsausschluss

• Danksagungen

Related MCP server: redteam-mcp

Video-Demo

https://github.com/user-attachments/assets/930c879a-5cb4-478a-b033-f30df0e770a6

Kernkonzepte & Architektur

pentestMCP hält sich strikt an die MCP-Spezifikation und fungiert ausschließlich als MCP-Server. Es bettet kein bestimmtes LLM ein und kommuniziert auch nicht direkt mit einem solchen. Der Interaktionsablauf wird über eine MCP-Client-Host-Anwendung vermittelt:

1. Client-Host-Anwendung (z. B. Claude Desktop, benutzerdefinierter Agent): Stellt eine Verbindung zu pentestMCP her (typischerweise über stdio, vermittelt durch Docker), verwaltet die Benutzerinteraktion und kommuniziert mit einem ausgewählten LLM.

2. LLM: Empfängt Benutzeraufforderungen und Tool-Definitionen (von pentestMCP über den Client-Host). Es entscheidet anhand des Kontexts, welche Tools aufgerufen werden sollen.

3. pentestMCP-Server (Dieses Projekt): Läuft in einem Docker-Container. Er lauscht auf tools/call-Anfragen vom Client-Host, führt das entsprechende zugrunde liegende Tool (z. B. nmap) aus und gibt die Ergebnisse zurück.

4. Externe Tools: Die eigentlichen Befehlszeilenprogramme, die im Docker-Image gekapselt sind.

Der Server wird mit dem Python-MCP-SDK (mcp.server.fastmcp.FastMCP) erstellt und bietet:

• Tool-Erkennung: Verwendet Python-Typannotationen und Docstrings für die automatische Generierung von MCP-Tool-Schemas.

• Parallelitätssteuerung: Ein threading.Semaphore begrenzt die gleichzeitige Ausführung ressourcenintensiver Scans.

• Asynchrones Scan-Muster: Implementiert Start-/Abrufmethoden für langlaufende Aufgaben (Nmap, Nuclei, SQLMap, Gobuster), um die MCP-Verbindung nicht zu blockieren.

sequenceDiagram
    participant User
    participant ClientHost as Client Host (Claude, VS Code)
    participant LLM
    participant PentestMCP as pentestMCP Server (Docker via stdio)
    participant ExtTool as External Tool (e.g., Nmap)

    User->>ClientHost: "Perform Nmap service scan on scanme.nmap.org"
    ClientHost->>PentestMCP: tools/list Request
    PentestMCP-->>ClientHost: List of Tools (including 'run_nmap_scan')
    ClientHost->>LLM: User Prompt + Available Tools Description
    LLM-->>ClientHost: Decision: Use 'run_nmap_scan', target='scanme.nmap.org', args='-sV'
    ClientHost->>PentestMCP: tools/call (name='run_nmap_scan', args={...})
    Note over PentestMCP, ExtTool: pentestMCP executes 'nmap -sV scanme.nmap.org' internally
    PentestMCP-->>ClientHost: tools/call Result (pid, output_path for async or direct output)
    ClientHost->>LLM: Tool Execution Result
    LLM-->>ClientHost: Formulate Final Response
    ClientHost-->>User: "Nmap scan launched/completed. Results..."

Hauptfunktionen

• Umfassendes Toolset: Integriert über 20 wichtige Penetrationstest-Werkzeuge über MCP.

• Standardisierter Zugriff: Ermöglicht jedem MCP-Client, der das Starten von stdio-Servern unterstützt, die Nutzung komplexer Pentesting-Workflows.

• Nicht blockierende Scans: Verarbeitet langlaufende Scans effizient, ohne den Interaktionsfluss zu blockieren.

• Ressourcenverwaltung: Implementiert eine grundlegende Parallelitätsbegrenzung für Scans.

• Portabel & reproduzierbar: Die Docker-Umgebung stellt sicher, dass alle Abhängigkeiten und Tools plattformübergreifend (Windows, macOS, Linux) konsistent verfügbar sind.

• Web-Scanner-Integration: Bietet direkte Steuerung der OWASP ZAP Active Scan- und AJAX Spider-Funktionen.

Voraussetzungen

• Docker: Erfordert Docker Desktop (Windows/macOS) oder Docker Engine (Linux), das installiert und ausgeführt wird. Stellen Sie sicher, dass der Docker-Daemon aktiv ist.

• Git: Wird nur benötigt, wenn das Image lokal erstellt wird (git clone-Schritt).

• (Optional, aber empfohlen) OWASP ZAP-Instanz: Für die Verwendung von ZAP-bezogenen Tools (run_zap_*, run_active_scan_*, run_ajax_*). Diese ZAP-Instanz muss ausgeführt werden und vom Inneren des pentestMCP-Docker-Containers aus über das Netzwerk erreichbar sein (siehe Abschnitt Client Host Integration für die Konfiguration).

Installation & Einrichtung

Wir empfehlen die Verwendung des vorgefertigten Docker-Images für die schnellste und zuverlässigste Einrichtung.

🐳 Verwendung des vorgefertigten Docker-Images (empfohlen)

Die Verwendung des vorgefertigten Images vermeidet lokale Build-Zeiten und stellt sicher, dass alle Tools (wie gofang, nmap und nuclei) ohne Abhängigkeitsprobleme korrekt installiert sind.

1. Image von Docker Hub abrufen:

   docker pull ramgameer/pentest-mcp:latest

   ℹ️ Hinweis: Abhängig von Ihrer Umgebung müssen Sie sich möglicherweise authentifizieren oder sicherstellen, dass der Docker-Daemon ausgeführt wird.

🛠️ Lokales Erstellen des Docker-Images

⚠️ WICHTIG: Das lokale Erstellen ist derzeit am effizientesten und wird auf Linux-Umgebungen unterstützt.

Wenn Sie den Code des Servers ändern möchten, die absolut neueste Version verwenden möchten oder das vorgefertigte Image nicht verfügbar ist, können Sie das Docker-Image lokal erstellen.

1. Repository klonen:

   git clone https://github.com/ramkansal/pentestMCP.git
   cd pentestMCP

2. Docker-Image erstellen:

   docker build -t pentest-mcp-server:custom .

3. SecLists installieren (optional, aber dringend empfohlen):

   💡 Tipp: Mehrere Tools (wie Gobuster und Fuzzing-Programme) sind auf umfangreiche Wortlisten angewiesen. Sie müssen das SecLists-Repository klonen, damit diese spezifischen Scans effektiv funktionieren. GXP5

Integration des Client-Hosts

pentestMCP läuft in Docker und kommuniziert über stdio mit dem Client-Host. Sie konfigurieren Ihren Host (z. B. Claude Desktop, VS Code) so, dass er den Server mit docker run -i ... startet.

Claude Desktop-Integration

1. Konfigurationsdatei suchen/erstellen:

   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

   • Windows: %APPDATA%\Claude\claude_desktop_config.json

2. Konfiguration bearbeiten: Fügen Sie den Abschnitt mcpServers hinzu bzw. aktualisieren Sie ihn. Verwenden Sie den korrekten Imagenamen (ramgameer/pentest-mcp:latest oder Ihr benutzerdefiniertes Tag).

   {
     "mcpServers": {
       "pentestMCP": {
         "command": "docker",
         "args": [
           "run",
           "--rm",
           "-i",
           "ramgameer/pentest-mcp:latest"
         ]
       }
     }
   }

3. Starten Sie Claude Desktop vollständig neu.

4. Überprüfen: Achten Sie auf das -Symbol. Ein Klick darauf sollte die Pentesting-Tools auflisten.

5. Interagieren: Bitten Sie Claude, die Tools zu verwenden (siehe Beispiele im Entwurf).

VS Code Copilot Chat-Integration

Die Integration erfordert die Konfiguration der VS Code-Einstellungen, um den MCP-Server für Copilot Chat-Agenten zu definieren, die MCP unterstützen.

1. Voraussetzung installieren: Stellen Sie sicher, dass die Github Copilot-Erweiterung und relevante GitHub Copilot-Erweiterungen installiert sind.

2. VS Code-Einstellungen konfigurieren: Öffnen Sie Ihre Benutzer- oder Arbeitsbereichsdatei settings.json (Befehlspalette: „Einstellungen öffnen (JSON)"). Fügen Sie die MCP-Serverkonfiguration unter dem entsprechenden Pfad hinzu (dieser Pfad kann sich je nach spezifischer Copilot Chat-Agentenimplementierung ändern; lesen Sie deren Dokumentation):

   "pentest-mcp": {
       "type": "stdio",
       "command": "docker",
       "args": [
           "run",
           "-i",
           "--rm",
           "ramgameer/pentest-mcp:latest"
       ]
   }

3. VS Code / Agenten neu laden: Starten Sie VS Code neu oder verwenden Sie relevante Befehle, um die Konfiguration des Copilot-Agenten neu zu laden, damit die Änderungen wirksam werden. Konsultieren Sie die Dokumentation des jeweiligen Copilot-Agenten für Details.

4. Interagieren: Verwenden Sie die Copilot Chat-Oberfläche, rufen Sie Tools möglicherweise über Erwähnungen auf, falls der Agent dies unterstützt, oder lassen Sie den Agenten sie basierend auf Ihren Aufforderungen aufrufen.

Tool-Referenz

Der Server stellt eine Vielzahl von Tools bereit, die nach Funktion kategorisiert sind:

• Aufklärung & Enumeration:

  • run_subfinder: Entdeckt Subdomains mit ProjectDiscovery's Subfinder.

  • launch_nmap_scan / fetch_nmap_results: Führt Nmap-Netzwerkscans aus und ruft Ergebnisse asynchron ab.

  • run_gobuster_scan / check_gobuster_status: Führt Verzeichnis-/Datei-/DNS-Bruteforcing mit Gobuster asynchron durch.

  • launch_gofang_scan / fetch_gofang_results: Führt gofang aus, einen All-in-One-Webcrawler mit Extraktions-Superkräften.

  • run_harvester / check_harvester_status: Führt theHarvester asynchron für OSINT-Sammlung (E-Mails, Hosts, IPs) aus.

  • run_dig_tool: Führt DNS-dig-Abfragen aus.

  • fetch_whois_data: Ruft WHOIS-Informationen für eine Domain ab.

  • run_curl_tool: Führt cURL-Befehle für HTTP-Interaktion aus.

• Schwachstellenscanning:

  • launch_nuclei_scan / fetch_nuclei_results: Führt templatebasierte Schwachstellenscans mit ProjectDiscovery's Nuclei asynchron durch.

• Webanwendungsanalyse:

  • launch_arjun_scan / fetch_arjun_results: Lokalisiert versteckte HTTP-Parameter mit Arjun.

• Exploitation-Unterstützung:

  • run_searchsploit: Durchsucht die lokale Exploit-DB-Datenbank mit Searchsploit.

  • run_sqlmap_tool / check_sqlmap_status: Führt SQLmap für SQL-Injection-Tests asynchron aus.

• Active Directory-Analyse (ad_*-Tools):

  • Enumeration: ad_user_enum, ad_shares_enum, ad_smb_signing_check, ad_certipy_enum, ad_ldap_dump, ad_bloodhound_collect

  • Angriffe/Coercion: ad_asreproast, ad_kerberoast, ad_password_spray, ad_coerce_petitpotam, ad_coerce_printerbug, ad_responder_poison, ad_relay_setup

  • Anmeldedaten-/Domain-Operationen: ad_check_credentials, ad_secrets_dump, ad_dcsync

Sicherheitshinweise

• Ausführungsberechtigungen: Tools werden als appuser in Docker ausgeführt, aber Docker selbst läuft mit Host-Berechtigungen. Seien Sie vorsichtig mit Tools, die Dateien ändern oder erhöhten Systemzugriff erfordern.

• Zielautorisierung: KRITISCH: Verwenden Sie diese Tools nur gegen Systeme, für die Sie eine ausdrückliche, vorherige, schriftliche Autorisierung haben. Nicht autorisiertes Scannen ist illegal und unethisch.

• Netzwerkexposition: Wenn Sie den ZAP-Port (-p 8888:8888) weiterleiten, stellen Sie sicher, dass Ihre Host-Firewall den Zugriff einschränkt, wenn sich die Maschine in einem nicht vertrauenswürdigen Netzwerk befindet. Der konfigurierte ZAP-API-Schlüssel bietet Kontrolle über die Instanz.

• Eingabevalidierung: Obwohl MCP strukturierte Eingaben bereitstellt, können die zugrunde liegenden Tools dennoch anfällig für manipulierte Argumente sein, wenn sie nicht robust in den Python-Wrapper-Funktionen behandelt werden.

Mitwirken

Beiträge sind ausdrücklich erwünscht! Forken Sie das Repository, erstellen Sie einen Feature-Branch und reichen Sie einen Pull Request ein. Bitte stellen Sie sicher, dass alle Beiträge den ethischen Testrichtlinien entsprechen. Fehlerberichte und Feature-Wünsche sind über GitHub Issues willkommen.

Lizenz

Dieses Projekt wird unter den Bedingungen der MIT-Lizenz vertrieben.

Haftungsausschluss

Diese Software ist AUSSCHLIESSLICH für Bildungszwecke und autorisierte, ethische Sicherheitstests bestimmt. Jegliche Nutzung gegen Systeme ohne ausdrückliche Genehmigung ist strengstens untersagt und illegal. Die Autoren und Mitwirkenden übernehmen KEINE Haftung für Missbrauch oder Schäden, die durch dieses Programm entstehen. Nutzung auf eigene Gefahr und stellen Sie die Einhaltung aller geltenden Gesetze und Vereinbarungen sicher.

Danksagungen

Tiefgreifende Inspiration für dieses Projekt stammt von Laurie Kirks bahnbrechender Arbeit an GhidraMCP.