hackingBuddyGPT: An LLM Agent Framework Wired to SSH, psexec and a Privilege-Escalation Benchmark

What hackingBuddyGPT actually removes from the work

The repository describes itself as a framework for building LLM-driven security-testing agents, and the selling point is subtraction. LLM connectivity, target connectors, capability wiring, run limits and structured logging are the parts every experiment needs and nobody wants to rewrite. The README frames the goal as letting a new experiment, called a use-case, be expressed in a few dozen lines.

The audience is narrow and stated: security researchers and pen-testers who want to use LLMs or LLM-based autonomous agents for security testing. The project also maintains a Linux privilege-escalation benchmark and publishes open-access reports, which tells you the maintainers care about reproducible comparison, not just demo output. If you are building a product feature that happens to call a model, this is not aimed at you. If you are asking whether an agent can escalate from a low-privilege shell to root, it is.

Two execution styles sharing one loop

The framework supports two ways for a model to act. Tool-calling agents keep a real chat history and drive the target through function calling. Command strategies render a Mako template into a prompt, take the reply, and parse a single command out of it. Both sit on the same asynchronous asyncio loop, and both are capped by the same limit set.

The minimal Linux privilege-escalation use-case is the clearest illustration of the second style. According to the README it templates the whole history into one prompt each round and parses a bare command out of the reply, which it calls the classic hackingBuddyGPT loop. Its tool-calling twin keeps a real chat history instead. That difference matters more than it looks: templating the full history into one prompt is simple and inspectable, but it grows the prompt every round, and the limit on tokens and cost is what stops it.

Success detection is where the two diverge sharply. The README states that MinimalToolCallPrivEscLinux verifies its task_solved tool against ground truth, so a hallucinated or conceding got-root cannot score a false success. Nothing in the supplied material claims the same guarantee for the minimal command-strategy variant, and a reviewer should treat that as the framework's most important internal asymmetry.

The use-case catalogue: privesc, web, API, Active Directory

Use-cases are registered as wintermute sub-commands. On the privilege-escalation side there are four beyond the two minimal ones. PrivEscLinux adds strategy-based operation with optional retrieval-augmented generation via --rag_path, chain-of-thought via --enable_cot, state tracking and structured guidance. PrivEscWindows does the same kind of work against Windows, driving the target through psexec rather than SSH. ExPrivEscLinuxLSE runs lse.sh on the target, converts its output into hints, then orchestrates PrivEscLinux per hint, which the README calls out as an example of a use-case that calls another use-case.

The web and API entries follow different shapes. WebTestingWithExplanation tests a page over HTTP while letting the model narrate its reasoning, and includes an OWASP-style pentest playbook capability. WebTestingWithShell adds shell access to a Kali-style attacker box. AdvancedWebTesting is a top-level agent with no direct target access that delegates to bounded sub-agents through a sub-agent capability. WebAPITesting first detects whether the target exposes an OpenAPI spec or a website sitemap, then pentests the REST API, with --mode values of document, test and auto.

The AD use-case is the most architecturally distinct: an assumed-breach Active Directory pentest ported from the cochise tool, built as a planner and executor. A persistent strategic planner holds a task tree and a shared knowledge base and delegates each task to a fresh, memoryless tactical executor. That design trades context continuity for bounded, restartable units of work.

Getting it running: uv, .env, and the wintermute command

The README requires Python 3.13 or newer and uses the uv build backend. Installation is a clone, uv sync, and activating the virtual environment. A plain python -m venv plus pip is listed as workable too. Configuration starts from .env.example copied to .env, which is where the LLM key and target details go.

Installing the package provides the wintermute command. Run with no arguments it lists every registered use-case; wintermute <UseCase> --help shows that use-case's options. The README's worked example runs the minimal Linux privesc against an SSH target with --conn=ssh, --conn.host, --conn.username and --conn.password.

Model routing goes through litellm, so any provider reachable through the llm.model string works: OpenAI, OpenRouter as the default endpoint, Anthropic, Azure, a local Ollama. Traffic can be sent through an intercepting proxy such as Burp or mitmproxy with --llm.proxy. Limits are unified across rounds, tokens, cost in dollars and wall-clock duration, exposed as --limits.max_rounds, --limits.max_tokens, --limits.max_cost and --limits.max_duration. Every run is written as an append-only OpenTelemetry and GenAI JSONL trace, and the project ships CLI tools to replay and aggregate those traces.

Where the framework stops helping you

The README's own warning is blunt: the software executes real commands on live systems, on your machine in local-shell mode, on the target in SSH or psexec mode. The stated mitigation is to run only against systems you own or are explicitly authorized to test, and to prefer isolated VMs or containers. That is not boilerplate. An agent that parses a command out of a model reply will eventually produce a command you did not anticipate, and the framework's job is to log it, not to second-guess it.

The second limitation is the false-success problem. Ground-truth verification is advertised for privilege escalation specifically. A use-case that reports completion without checking real command output can record a success that never happened, and if you are using the JSONL traces as research data, that error propagates into your results silently. The README gives no general mechanism that would catch it for web or API use-cases.

Third, the framework is not a scanner. It has no vulnerability database, no signature set, no reporting layer aimed at a client deliverable. It is a harness for experiments, and the use-case catalogue is the experiment set. If what you need is a repeatable scan of a known surface, the agent loop adds cost and nondeterminism without adding coverage.

The alternative: a direct litellm script, and why the framework exists

The honest alternative for a one-off experiment is a short Python script that calls litellm directly, holds your own message list, and shells out with paramiko or subprocess. You get exactly the loop you wrote and nothing else. The difference in approach is that you also own the run limits, the trace format, the connector abstraction and the retry behaviour, and you will re-derive them the second time you write an experiment.

hackingBuddyGPT is the bet that the second experiment is the common case. Its value is the shared surface: one CLI, one limit vocabulary, one trace schema, one place where SSH, local shell and psexec targets look the same to the agent. The cost is that you inherit the framework's abstractions, including the command-strategy loop whose success detection is weaker than its tool-calling sibling. If your experiment does not resemble any of the shipped use-cases, the abstractions may cost more than they save.

Maintenance, releases and the MIT licence

The project is under the MIT licence, which permits commercial use, modification and redistribution provided the copyright notice and permission notice are retained. That is the standard permissive position; if you plan to redistribute a modified wintermute or embed the framework in a product, have counsel confirm the notice requirements rather than treating this paragraph as advice.

Release cadence visible in the supplied material is roughly annual: v0.3.0 in August 2024, v0.4.0 in April 2025, v0.5.0 in August 2025, with the repository's last push in August 2026. Version numbers below 1.0 signal that interfaces can move between releases, and a framework whose use-cases are registered as CLI sub-commands has a wide interface surface. The Python 3.13 floor is a real upgrade cost: environments pinned to older interpreters cannot install it without a version bump, and the uv build backend means a pip-only workflow needs the plain venv path the README describes rather than a bare pip install from a lockfile you do not have.

The maintenance burden you take on is not the framework itself but your use-cases. Each one encodes assumptions about how a target behaves and how success is detected, and those assumptions are what break when the models or the targets change.

Editorial conclusion

Adopt hackingBuddyGPT if you are a security researcher or pentester who wants to write a new LLM testing experiment as a use-case rather than rebuild SSH connectors, run limits and trace logging each time, and if you have isolated VMs or containers to point it at. Do not adopt it as a scanner for production or client networks: the README states the software executes real commands on live systems, and the MinimalPrivEscLinux loop parses a bare command out of a templated reply. Verify two things first: that your Python is 3.13 or newer, and that the use-case you pick detects success against ground truth. MinimalToolCallPrivEscLinux verifies its task_solved tool that way; the minimal command-strategy variant does not.

Official sources

1. ipa-lab/hackingBuddyGPT on GitHub
2. License: MIT
3. Project website
4. README
5. Releases