---

hackingBuddyGPT is an open-source framework for building LLM-driven security-testing agents. It gives you the boring-but-essential groundwork — LLM connectivity, target connectors (SSH / local shell / WinRM-style psexec), capability/tool wiring, run limits, and structured logging — so you can express a new experiment (a "use-case") in a few dozen lines of code. We aim to be THE go-to framework for security researchers and pen-testers who want to use LLMs (or LLM-based autonomous agents) for security testing.

To support reproducible research we also maintain a re-usable Linux privilege-escalation benchmark and publish our findings as open-access reports. If you need help choosing an LLM for a task, we have a paper comparing multiple LLMs.

⚠️ This software executes real commands on live systems. In local-shell mode it runs them on your machine; in SSH/psexec mode on the target you point it at. Only ever run it against systems you own or are explicitly authorized to test, and prefer isolated VMs or containers. See the disclaimers.

Quickstart

# 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

Installing the package provides the wintermute command. Running it with no arguments lists every registered use-case; wintermute <UseCase> --help shows that use-case's options.

Need a target to practice on? Grab a vulnerable box from our Linux Privilege-Escalation Benchmark or a deliberately-vulnerable VM such as Lin.Security from VulnHub.

Use-cases

Experiments are structured into use-cases. Each becomes a wintermute sub-command. The framework currently ships the following:

Privilege escalation

Command	Description
MinimalPrivEscLinux	Minimal ~20-line Linux privilege-escalation. Templates the whole history into one prompt each round and parses a bare command out of the reply (the classic hackingBuddyGPT loop). Great starting point — see Build your own use-case.
MinimalToolCallPrivEscLinux	The tool-calling twin of the above: keeps a real chat history and drives the target through function calling. Its task_solved tool is verified against ground truth, so a hallucinated or conceding "got root" cannot score a false success.
PrivEscLinux	Full-featured strategy-based Linux privesc with optional retrieval-augmented generation (--rag_path), chain-of-thought (--enable_cot), state tracking and structured guidance.
PrivEscWindows	Strategy-based Windows privilege escalation, driving the target through psexec instead of SSH.
ExPrivEscLinuxLSE	Runs lse.sh on the target first, turns its output into hints, then orchestrates PrivEscLinux per hint — an example of a use-case that calls another use-case.

Web

Command	Description
WebTestingWithExplanation	Autonomously tests a web page over HTTP while letting the LLM "talk" through its reasoning; includes an OWASP-style pentest playbook capability.
WebTestingWithShell	Web testing with shell access to a Kali-style attacker box.
AdvancedWebTesting	A top-level agent with no direct target access that delegates work to bounded sub-agents via a sub-agent capability.

Web API

Command	Description
WebAPITesting	Detects the target surface — an OpenAPI spec or a website sitemap — then pentests the REST API. Runs in --mode document (build a spec), test (pentest a known surface), or auto (both).

Active Directory

Command	Description
AD	Autonomous LLM Active Directory assumed-breach pentest, ported from the cochise attack tool. Uses a planner/executor design: a persistent strategic planner maintains a task tree and shared knowledge base, delegating each task to a fresh, memoryless tactical executor.

Framework features

• Two execution styles on one shared loop: native tool-calling agents (real chat history + function calling) and simple-text command strategies (Mako template → single parsed command).
• Unified run limits — cap any run by rounds, tokens, cost (in dollars) and wall-clock duration (--limits.max_rounds/max_tokens/max_cost/max_duration).
• One LLM upstream: litellm. Any provider is reachable through the llm.model string — OpenAI, OpenRouter (the default endpoint), Anthropic, Azure, a local Ollama, and more. Route API traffic through an intercepting proxy (Burp/mitmproxy) with --llm.proxy.
• Structured, self-contained logging — every run is written as an append-only OpenTelemetry/GenAI JSONL trace, with CLI tools to replay and aggregate runs.
• Fully asynchronous execution model built on asyncio.
• Ground-truth-verified success detection for privilege escalation (a claimed "got root" is checked against real command output).
• Docker-fleet benchmark launcher for regression testing against many targets at once.

Installation & setup

Requirements: Python 3.13+. The project uses the uv build backend; we recommend uv to manage the environment, but a plain python -m venv + pip works too.

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 .

Optional dependency groups: testing (pytest & friends), dev (ruff), and rag (the RAG stack for PrivEscLinux --rag_path). Install them with e.g. uv sync --extra testing or pip install '.[testing]'.

Configuration

Configuration is resolved from four layers, each overriding the previous one:

1. environment variables,
2. a .env file in the current directory (start from cp .env.example .env),
3. a JSON file passed with --config config.json,
4. --key=value command-line flags (highest priority).

Any option you can pass on the command line can also be set in .env or the JSON config. LLM selection is provider-agnostic through litellm: