PentestAgent

KI-gestütztes Penetrationstesting

https://github.com/user-attachments/assets/a67db2b5-672a-43df-b709-149c8eaee975

Anforderungen

• Python 3.10+
• API-Schlüssel für OpenAI, Anthropic oder einen anderen LiteLLM-unterstützten Anbieter

Installation

# Klonen
git clone https://github.com/GH05TCREW/pentestagent.git
cd pentestagent

# Einrichtung (erstellt venv, installiert Abhängigkeiten)
.\scripts\setup.ps1   # Windows
./scripts/setup.sh    # Linux/macOS

# Oder manuell
python -m venv venv
.\venv\Scripts\Activate.ps1  # Windows
source venv/bin/activate     # Linux/macOS
pip install -e ".[all]"
playwright install chromium  # Erforderlich für das Browser-Tool

Konfiguration

Erstelle .env im Projektverzeichnis:

ANTHROPIC_API_KEY=sk-ant-...
PENTESTAGENT_MODEL=claude-sonnet-4-20250514

Oder für OpenAI:

OPENAI_API_KEY=sk-...
PENTESTAGENT_MODEL=gpt-5

Jedes LiteLLM-unterstützte Modell funktioniert.

Verwendung eines Relays / einer benutzerdefinierten API-Basis

Leite PentestAgent über OPENAI_API_BASE auf einen beliebigen OpenAI-kompatiblen Endpunkt:

OPENAI_API_KEY=your-relay-token
OPENAI_API_BASE=https://relay.example/v1
PENTESTAGENT_MODEL=openai/<model-name-on-your-relay>

Für Anthropic-kompatible Endpunkte verwende stattdessen ANTHROPIC_API_BASE. Siehe .env.example für vollständige Hinweise zu Anbietern und Embedding-Optionen.

Ausführung

pentestagent                      # TUI starten
pentestagent -t 192.168.1.1       # Mit Ziel starten
pentestagent tui --docker         # Tools im Docker-Container ausführen

Docker

Führe Tools innerhalb eines Docker-Containers aus – für Isolation und vorinstallierte Pentesting-Tools.

Option 1: Vorgebautes Image ziehen (am schnellsten)

# Basis-Image mit nmap, netcat, curl
docker run -it --rm \
  -e ANTHROPIC_API_KEY=your-key \
  -e PENTESTAGENT_MODEL=claude-sonnet-4-20250514 \
  ghcr.io/gh05tcrew/pentestagent:latest

# Kali-Image mit metasploit, sqlmap, hydra, etc.
docker run -it --rm \
  -e ANTHROPIC_API_KEY=your-key \
  ghcr.io/gh05tcrew/pentestagent:kali

Option 2: Lokal bauen

# Bauen
docker compose build

# Ausführen
docker compose run --rm pentestagent

# Oder mit Kali
docker compose --profile kali build
docker compose --profile kali run --rm pentestagent-kali

Der Container führt PentestAgent mit Zugriff auf Linux-Pentesting-Tools aus. Der Agent kann nmap, msfconsole, sqlmap usw. direkt über das Terminal-Tool verwenden.

Erfordert eine installierte und laufende Docker-Installation.

Modi

PentestAgent hat drei Modi, die über Befehle in der TUI erreichbar sind:

TUI-Befehle

/assist <Aufgabe>    Eine einmalige Anweisung.
/agent <Aufgabe>     Autonomen Agenten für Aufgabe ausführen
/crew <Aufgabe>      Multi-Agent-Crew für Aufgabe ausführen
/interact <Aufgabe>  Im geführten Modus mit dem Agenten chatten
/target <Host>       Ziel setzen
/tools               Verfügbare Tools auflisten
/notes               Gespeicherte Notizen anzeigen
/report              Bericht aus der Sitzung generieren
/memory              Token-/Speichernutzung anzeigen
/prompt              System-Prompt anzeigen
/conversations       Gespeicherte Unterhaltungen durchsuchen und wiederherstellen
/mcp <list/add>      MCP-Server visualisieren oder hinzufügen.
/spawn [target] [--scope CIDR] [--model M] [--no-rag] [--no-mcp]
                     Manuell einen untergeordneten MCP-Agenten aus der TUI erzeugen.
/despawn <server_name>
                     Einen zuvor erzeugten untergeordneten Agenten beenden und entfernen.
/clear               Chat und Verlauf löschen
/quit                Beenden (auch /exit, /q)
/help                Hilfe anzeigen (auch /h, /?)

Drücke Esc, um einen laufenden Agenten zu stoppen. Strg+Q zum Beenden.

Playbooks

PentestAgent enthält vorgefertigte Angriffs-Playbooks für Black-Box-Sicherheitstests. Playbooks definieren einen strukturierten Ansatz für bestimmte Sicherheitsbewertungen.

Ein Playbook ausführen:

pentestagent run -t example.com --playbook thp3_web

Tools

PentestAgent enthält integrierte Tools und unterstützt MCP (Model Context Protocol) zur Erweiterbarkeit.

Integrierte Tools: terminal, browser, notes, web_search (erfordert TAVILY_API_KEY), spawn_mcp_agent

Agent Self-Spawning (spawn_mcp_agent)

spawn_mcp_agent ist ein eingebautes Tool, das es einem laufenden Agenten ermöglicht, eine untergeordnete Kopie seiner selbst als untergeordneten MCP-Server zu erzeugen, der über stdio verbunden ist. Der untergeordnete Prozess ist vollständig isoliert – eigene Laufzeit, LLM-Client, Unterhaltungsverlauf und Notizenspeicher – und sein vollständiger Tool-Satz wird nach dem Spawning zurück in die verfügbaren Tools des übergeordneten Agenten injiziert.

Dies ermöglicht hierarchische Multi-Agent-Workflows ohne externe Orchestrierung: Der Agent organisiert sich selbst, indem er begrenzte Unteraufgaben an Kinder delegiert, die er bei Bedarf erzeugt.

Nachdem spawn_mcp_agent zurückgekehrt ist, sind die Tools des Kindes (run_task, run_task_async, await_tasks usw.) beim nächsten Tool-Aufruf verfügbar. Der Server-Name des Kindes wird automatisch zugewiesen (z.B. child_agent_1) und im Ergebnis zurückgegeben.

Beispiel – Orchestrator delegiert parallele Reconnaissance an zwei Kinder:

# Runde 1: zwei isolierte Kind-Agenten erzeugen
spawn_mcp_agent  target="10.0.1.0/24"  scope=["10.0.1.0/24"]
spawn_mcp_agent  target="10.0.2.0/24"  scope=["10.0.2.0/24"]

# Runde 2: Tools der Kinder sind jetzt verfügbar – delegiere Arbeit asynchron
child_agent_1__run_task_async  task="Full port scan and service enumeration"
child_agent_2__run_task_async  task="Full port scan and service enumeration"

# Runde 3: warten und sammeln
child_agent_1__await_tasks  task_ids=["<id1>"]  timeout_seconds=600
child_agent_2__await_tasks  task_ids=["<id2>"]  timeout_seconds=600
child_agent_1__get_task_result  task_id="<id1>"
child_agent_2__get_task_result  task_id="<id2>"

Manuelle Kind-Agent-Steuerung (/spawn und /despawn)

Neben dem automatischen spawn_mcp_agent-Tool bietet die TUI zwei Befehle, mit denen du Kind-Agenten manuell erzeugen und beenden kannst, unabhängig von einer laufenden Agentenschleife.

/spawn

/spawn [target] [--scope CIDR ...] [--model MODEL] [--no-rag] [--no-mcp]

Erzeugt einen neuen untergeordneten MCP-Agenten über stdio und hängt ihn an die aktuelle Sitzung an. Der Kind-Agent erscheint als einklappbares Terminal-Panel in der TUI-Seitenleiste und seine Tools werden dem übergeordneten Agenten beim nächsten Tool-Aufruf zur Verfügung gestellt.

Beispiele:

/spawn 10.0.1.1
/spawn 10.0.1.1 --scope 10.0.1.0/24 --model claude-sonnet-4-20250514
/spawn --target 10.0.1.1 --scope 10.0.1.0/24 --no-rag

/despawn

/despawn <server_name>

Beendet den Kind-Agenten, der durch server_name identifiziert wird (z.B. child_agent_1), entfernt sein Terminal-Panel aus der TUI und trennt seine Tools von der übergeordneten Sitzung. Verwende /mcp list, um die Namen aller aktuell aktiven Kind-Agenten zu sehen.

Beispiel:

/despawn child_agent_1

MCP RAG Tool Optimizer

Wenn ein MCP-Server mehr als 128 Tools bereitstellt, ersetzt PentestAgent automatisch den gesamten Katalog durch ein einzelnes mcp_<server>_rag_optimizer-Tool. Dieses Meta-Tool verwendet Embedding-Ähnlichkeit (via LiteLLM, standardmäßig text-embedding-3-small), um die relevantesten Tools für die anstehende Aufgabe abzurufen und injiziert sie in die nächste Runde des Agenten – so bleibt der Kontextfenster überschaubar, ohne den Zugriff auf den vollständigen Tool-Satz zu verlieren.

Der Optimierer ist für den Agenten transparent: Er ruft das RAG-Tool mit gezielten Anfragen in natürlicher Sprache auf, die beschreiben, was er benötigt, und die passenden Tools werden beim nächsten Aufruf direkt verfügbar.

Nutzungshinweise für den Agenten:

Embeddings werden einmalig beim Start berechnet und zwischengespeichert, sodass wiederholte Abfragen schnell sind. Der Optimierer wird pro Server erstellt, sodass jeder MCP-Server mit einem großen Katalog seinen eigenen unabhängigen Index erhält.

Tipp: Gib eine Anfrage pro eindeutiger Fähigkeit an, anstatt alles in eine Anfrage zu packen. ["alle offenen Ports auf einem Host auflisten", "Prozessspeichernutzung abrufen"] liefert bessere Ergebnisse als ["Ports und Speicher und CPU auflisten"].

MCP-Integration

PentestAgent unterstützt MCP (Model Context Protocol) in zwei Richtungen: Konsumieren externer MCP-Server als Tool-Quellen und Bereitstellen seiner selbst als MCP-Server, sodass externe Clients (Claude Desktop, Cursor usw.) PentestAgent programmgesteuert steuern können.

Konsumieren externer MCP-Server (Client-Modus)

Konfiguriere mcp_servers.json, um PentestAgent mit beliebigen externen MCP-Servern zu verbinden. Beispielkonfiguration:

{
  "mcpServers": {
    "nmap": {
      "command": "npx",
      "args": ["-y", "gc-nmap-mcp"],
      "env": {
        "NMAP_PATH": "/usr/bin/nmap"
      }
    }
  }
}

Bereitstellen von PentestAgent als MCP-Server (Server-Modus)

PentestAgent kann als MCP-Server ausgeführt werden, sodass jeder MCP-kompatible Client Aufgaben einreichen, Ergebnisse einsehen und den Agenten fernsteuern kann. Zwei Transporte werden unterstützt:

STDIO – für lokale Clients (z. B. Claude Desktop, Cursor):

pentestagent mcp_server --type stdio
pentestagent mcp_server --type stdio --target 192.168.1.1 --scope 192.168.1.0/24
pentestagent mcp_server --type stdio --model claude-sonnet-4-20250514 --docker

SSE (HTTP) – für entfernte oder vernetzte Clients:

pentestagent mcp_server --type sse
pentestagent mcp_server --type sse --host 0.0.0.0 --port 8080
pentestagent mcp_server --type sse --target 10.0.0.1 --scope 10.0.0.0/24 --docker

Der SSE-Transport stellt einen einzelnen /mcp-Endpunkt bereit, der POST (Anfragen), GET (persistenter SSE-Stream für serverseitiges Pushen) und DELETE (Sitzungsabbau) unterstützt. Sitzungen werden über den Mcp-Session-Id-Header verfolgt.

Alle mcp_server-Flags:

Beispiel: Claude Desktop-Konfiguration (claude_desktop_config.json)

{
  "mcpServers": {
    "pentestagent": {
      "command": "pentestagent",
      "args": ["mcp_server", "--type", "stdio"]
    }
  }
}

MCP-Server-Tool-Referenz

Wenn PentestAgent als MCP-Server fungiert, stellt es die folgenden Tools bereit:

Server-Status & Konfiguration

Aufgabenausführung

Aufgabeninspektion

Aufgabensteuerung

Tool-Management

Unterhaltungsverlauf

Speicher

Beobachtbarkeit

Beispiel für asynchronen Aufgaben-Workflow

Für langlaufende Recon-Aufgaben verwende das asynchrone Muster:

# 1. Aufgaben ohne Blockieren einreichen
run_task_async  task="Subdomains von example.com ermitteln"  target="example.com"
run_task_async  task="Nmap-SYN-Scan auf example.com ausführen"     target="example.com"

# 2. Blockieren, bis beide fertig sind (max. 5 Minuten)
await_tasks  task_ids=["<id1>", "<id2>"]  timeout_seconds=300

# 3. Vollständige Ergebnisse abrufen
get_task_result  task_id="<id1>"
get_task_result  task_id="<id2>"

CLI-Tool-Management

pentestagent tools list         # Alle Tools auflisten
pentestagent tools info <name>  # Tool-Details anzeigen
pentestagent mcp list           # MCP-Server auflisten
pentestagent mcp add <name> <command> [args...]  # MCP-Server hinzufügen
pentestagent mcp test <name>    # MCP-Verbindung testen

Steuerung des Unterhaltungsverlaufs

Jede Benutzernachricht in der TUI zeigt zwei Inline-Aktionsschaltflächen: Rewind und Fork.

Rewind

Klicke auf Rewind bei einer beliebigen Benutzernachricht, um die Unterhaltung auf den Punkt kurz vor dieser Nachricht zu kürzen – sowohl in der Benutzeroberfläche als auch im In-Memory-Verlauf des Agenten. Verwende dies, um eine Abfrage von Grund auf neu zu versuchen, ohne den verworfenen Pfad zu speichern.

Fork

Klicke auf >> fork bei einer beliebigen Benutzernachricht, um die Unterhaltung von diesem Punkt abzuzweigen:

1. Die aktuelle vollständige Unterhaltung wird im Konversationsspeicher gespeichert und eine kurze Schnappschuss-ID wird angezeigt.
2. Die Unterhaltung wird dann auf den Punkt kurz vor der ausgewählten Nachricht gekürzt (wie bei Rewind).

So kannst du von jedem Punkt aus einen alternativen Ansatz ausprobieren, während der ursprüngliche Thread über /conversations abrufbar bleibt.

Unterhaltungsverlauf

PentestAgent speichert automatisch jede Unterhaltung, damit du vergangene Sitzungen überprüfen, vergleichen und wiederherstellen kannst.

Automatisches Speichern erfolgt nach jeder /assist-, /agent-, /crew- und /interact-Aufgabe sowie vor /clear. Es werden maximal 20 Unterhaltungen aufbewahrt; ältere werden automatisch gelöscht.

Speicherort: workspaces/<active>/memory/conversations/ wenn ein Arbeitsbereich aktiv ist, andernfalls conversations/ im Projektverzeichnis. Jede Unterhaltung ist eine JSON-Datei.

Durchsuchen und Wiederherstellen mit /conversations:

Der Befehl /conversations öffnet ein geteiltes Fenster-Modal innerhalb der TUI:

• Linkes Panel – Liste der gespeicherten Unterhaltungen mit Titel und Datum.
• Rechtes Panel – Metadaten-Vorschau plus die ersten 5 Nachrichten (Benutzernachrichten in Blau, Agentenantworten in Grün, Tool-Aufrufe in Gelb, Tool-Ergebnisse in Grau). Eine Zahl zeigt an, wie viele zusätzliche Nachrichten vorhanden sind.

Wähle eine Unterhaltung aus und drücke Restore, um sie in die aktuelle Sitzung zu laden, oder Close, um das Modal zu schließen.

Wissen

• RAG: Lege Methodiken, CVEs oder Wortlisten in pentestagent/knowledge/sources/ ab, um eine automatische Kontextinjektion zu ermöglichen.
• Notizen: Agenten speichern Erkenntnisse in loot/notes.json mit Kategorien (credential, vulnerability, finding, artifact). Notizen bleiben über Sitzungen hinweg erhalten und werden in den Agentenkontext injiziert.
• Shadow Graph: Im Crew-Modus erstellt der Orchestrator einen Wissensgraphen aus Notizen, um strategische Erkenntnisse abzuleiten (z. B. "Wir haben Anmeldeinformationen für Host X").

Projektstruktur

pentestagent/
  agents/         # Agent-Implementierungen
  config/         # Einstellungen und Konstanten
  interface/      # TUI und CLI
  knowledge/      # RAG-System und Shadow Graph
  llm/            # LiteLLM-Wrapper
  mcp/            # MCP-Client- und Server-Konfigurationen
  playbooks/      # Angriffs-Playbooks
  runtime/        # Ausführungsumgebung
  tools/          # Integrierte Tools

Entwicklung

pip install -e ".[dev]"
pytest                       # Tests ausführen
pytest --cov=pentestagent    # Mit Abdeckung
black pentestagent           # Formatieren
ruff check pentestagent      # Linten

Rechtliche Hinweise

Verwende das Tool nur gegen Systeme, für die du eine ausdrückliche Genehmigung zum Testen hast. Unbefugter Zugriff ist illegal.

Lizenz

MIT