---

hackingBuddyGPT ist ein Open-Source-Framework zum Erstellen LLM-gesteuerter Agenten für Sicherheitstests. Es liefert dir die langweilige, aber unverzichtbare Grundlage — LLM-Konnektivität, Ziel-Konnektoren (SSH / lokale Shell / WinRM-artiges psexec), Verdrahtung von Fähigkeiten und Tools, Ausführungslimits und strukturiertes Logging —, sodass du ein neues Experiment (einen „Use-Case") in ein paar Dutzend Zeilen Code ausdrücken kannst. Unser Ziel ist es, DAS zentrale Framework für Sicherheitsforscher und Pen-Tester zu sein, die LLMs (oder LLM-basierte autonome Agenten) für Sicherheitstests nutzen möchten.

Um reproduzierbare Forschung zu unterstützen, pflegen wir außerdem einen wiederverwendbaren Linux-Privilegieneskalations-Benchmark und veröffentlichen unsere Ergebnisse als Open-Access-Berichte. Wenn du Hilfe bei der Auswahl eines LLM für eine Aufgabe benötigst, haben wir ein Paper, das mehrere LLMs vergleicht.

⚠️ Diese Software führt echte Befehle auf Live-Systemen aus. Im lokalen Shell-Modus führt sie diese auf deinem Rechner aus; im SSH/psexec-Modus auf dem Ziel, das du angibst. Führe sie ausschließlich gegen Systeme aus, die dir gehören oder die du ausdrücklich testen darfst, und bevorzuge isolierte VMs oder Container. Siehe die Haftungsausschlüsse.

Schnellstart

# 1. clone and install (uv is recommended; a plain venv + pip works too)
git clone https://github.com/ipa-lab/hackingBuddyGPT.git && cd hackingBuddyGPT
uv sync && source .venv/bin/activate

# 2. configure your LLM key + target
cp .env.example .env && $EDITOR .env

# 3. list the available use-cases
wintermute

# 4. run one — e.g. a minimal Linux privilege-escalation against an SSH target
wintermute MinimalPrivEscLinux \
    --conn=ssh --conn.host=192.168.122.151 \
    --conn.username=lowpriv --conn.password=trustno1

Die Installation des Pakets stellt den Befehl wintermute bereit. Wenn er ohne Argumente ausgeführt wird, listet er jeden registrierten Use-Case auf; wintermute <UseCase> --help zeigt die Optionen dieses Use-Cases an.

Sie brauchen ein Ziel zum Üben? Holen Sie sich eine verwundbare Box aus unserem Linux Privilege-Escalation Benchmark oder eine absichtlich verwundbare VM wie Lin.Security von VulnHub.

Use-Cases

Experimente sind in Use-Cases gegliedert. Jeder wird zu einem wintermute-Unterbefehl. Das Framework liefert derzeit die folgenden:

Privilegieneskalation

Befehl	Beschreibung
MinimalPrivEscLinux	Minimale ~20-zeilige Linux-Privilegieneskalation. Fügt die gesamte Historie in jeder Runde in einen Prompt ein und extrahiert einen reinen Befehl aus der Antwort (die klassische hackingBuddyGPT-Schleife). Hervorragender Ausgangspunkt — siehe Build your own use-case.
MinimalToolCallPrivEscLinux	Der Tool-Calling-Zwilling des obigen: führt eine echte Chat-Historie und steuert das Ziel über Function Calling. Sein task_solved-Tool wird gegen Ground Truth verifiziert, sodass ein halluziniertes oder nachgebendes „got root" keinen falschen Erfolg erzielen kann.
PrivEscLinux	Voll ausgestattete strategiebasierte Linux-PrivEsc mit optionaler Retrieval-Augmented Generation (--rag_path), Chain-of-Thought (--enable_cot), Zustandsverfolgung und strukturierter Anleitung.
PrivEscWindows	Strategiebasierte Windows-Privilegieneskalation, die das Ziel über psexec statt SSH steuert.
ExPrivEscLinuxLSE	Führt zuerst lse.sh auf dem Ziel aus, wandelt dessen Ausgabe in Hinweise um und orchestriert dann PrivEscLinux pro Hinweis — ein Beispiel für einen Use-Case, der einen anderen Use-Case aufruft.

Web

Befehl	Beschreibung
WebTestingWithExplanation	Testet autonom eine Webseite über HTTP und lässt das LLM dabei seine Überlegungen „aussprechen"; enthält eine Pentest-Playbook-Fähigkeit im OWASP-Stil.
WebTestingWithShell	Web-Testing mit Shell-Zugriff auf eine Angreifer-Box im Kali-Stil.
AdvancedWebTesting	Ein übergeordneter Agent ohne direkten Zielzugriff, der Arbeit über eine Sub-Agent-Fähigkeit an begrenzte Sub-Agenten delegiert.

Web-API

Befehl	Beschreibung
WebAPITesting	Erkennt die Zieloberfläche — eine OpenAPI-Spezifikation oder eine Website-Sitemap — und führt dann einen Pentest der REST-API durch. Läuft im --mode document (Spezifikation erstellen), test (Pentest einer bekannten Oberfläche) oder auto (beides).

Active Directory

Befehl	Beschreibung
AD	Autonomer LLM-Pentest für Active Directory unter Annahme einer Kompromittierung, portiert aus dem Angriffstool cochise. Verwendet ein Planner/Executor-Design: Ein persistenter strategischer Planner pflegt einen Aufgabenbaum und eine gemeinsame Wissensbasis und delegiert jede Aufgabe an einen frischen, gedächtnislosen taktischen Executor.

Framework-Funktionen

• Zwei Ausführungsstile auf einer gemeinsamen Schleife: native Tool-Calling-Agenten (echte Chat-Historie + Function Calling) und einfache Text-Befehlsstrategien (Mako-Template → einzelner geparster Befehl).
• Einheitliche Ausführungslimits — begrenzen Sie jeden Lauf nach Runden, Tokens, Kosten (in Dollar) und Wanduhr-Dauer (--limits.max_rounds/max_tokens/max_cost/max_duration).
• Ein LLM-Upstream: litellm. Jeder Anbieter ist über den llm.model-String erreichbar — OpenAI, OpenRouter (der Standard-Endpunkt), Anthropic, Azure, ein lokales Ollama und mehr. Leiten Sie den API-Verkehr über einen abfangenden Proxy (Burp/mitmproxy) mit --llm.proxy.
• Strukturiertes, eigenständiges Logging — jeder Lauf wird als append-only OpenTelemetry/GenAI-JSONL-Trace geschrieben, mit CLI-Tools zum Replay und Aggregieren von Läufen.
• Vollständig asynchrones Ausführungsmodell auf Basis von asyncio.
• Ground-Truth-verifizierte Erfolgserkennung für Privilegieneskalation (ein behauptetes „got root" wird gegen echte Befehlsausgabe geprüft).
• Docker-Fleet-Benchmark-Launcher für Regressionstests gegen viele Ziele gleichzeitig.

Installation & Einrichtung

Voraussetzungen: Python 3.13+. Das Projekt verwendet das Build-Backend uv; wir empfehlen uv zur Verwaltung der Umgebung, aber ein einfaches python -m venv + pip funktioniert ebenfalls.

git clone https://github.com/ipa-lab/hackingBuddyGPT.git
cd hackingBuddyGPT

# option A (recommended): uv creates .venv and installs the project
uv sync
source .venv/bin/activate

# option B: a plain virtual environment + pip
python -m venv venv && source ./venv/bin/activate
pip install -e .