# hackingBuddyGPT

> Draft · awaiting review.

> Open-source framework for building LLM-driven security-testing agents, with use cases for Linux privilege escalation and web API testing.

- Badge: `reach 2 · not run yet`
- Type: Agent; tier: not run yet
- Tasks: Web and API testing, Identity attack paths; mission: Offensive; works with: Standalone (own model access)
- Source: https://github.com/ipa-lab/hackingBuddyGPT, pinned to `799f57e` (0.5.0), licence MIT
- Last checked: 2026-10-19; next check: 2027-01-17; method v0.1, reach-v0.1

## At a glance

- **What it is:** An open-source Python framework for building LLM-driven security-testing agents; experiments are written as use-cases, shipped ones covering Linux and Windows privilege escalation, web and web-API testing, and Active Directory assumed-breach. An agent is a program with its own model access that works through a task on its own.
- **Made for:** Build LLM-driven security-testing agents while the framework supplies LLM connectivity, target connectors, run limits and logging. +1 more
- **Runs:** On your machine, started by you. Other modes: docker (in a container on your machine); benchmark launcher.
- **Sends data to:** OpenRouter / litellm-reachable LLM provider (always), SSH target (by default), HTTP target host (if you turn it on), Windows psexec target (if you turn it on), intercepting proxy (Burp/mitmproxy) (if you turn it on), OpenAI embeddings (if you turn it on), OpenRouter / Anthropic (by default). Other connections not ruled out: read in the documentation and the cited code, not searched in full.
- **Can change things:** Changes, deletes, runs commands, sends data out, according to the capabilities read. Partly listed: AD planner/executor task delegation (perform_task, objective_complete) and knowledge-base capabilities, and the web-API document/test phase engines, are not listed as separate groups.
- **Needs:** Python 3.13 or newer · An LLM provider API key (litellm format), default endpoint OpenRouter · Target credentials for target-driving use-cases (SSH or Windows username and password) · +2 more

Profile read at commit `799f57e` on 2026-10-25; every fact cites a file and line at that commit.

## What it does

An open-source Python framework for building LLM-driven security-testing agents; experiments are written as use-cases, shipped ones covering Linux and Windows privilege escalation, web and web-API testing, and Active Directory assumed-breach. (README.md#L15)

Made for (the author says):

- Build LLM-driven security-testing agents while the framework supplies LLM connectivity, target connectors, run limits and logging. (README.md#L15)
- Support reproducible research alongside a re-usable Linux privilege-escalation benchmark. (README.md#L17)

Documented uses:

- Escalate privileges on a Linux SSH target [Identity attack paths] (README.md#L52)
- Pentest a REST API detected from an OpenAPI spec or sitemap [Web and API testing] (README.md#L70)
- Run an Active Directory assumed-breach pentest [Identity attack paths] (README.md#L76)
- Test a web page over HTTP [Web and API testing] (README.md#L62)

Not for (the author says):

- The author restricts use to educational purposes and systems you are authorized to test. (README.md#L322)
- The author warns never to run it against real production systems and to prefer vulnerable VMs. (README.md#L174)

## What it can do

| Group | What it covers | Effect | On by default |
|---|---|---|---|
| LocalShellCapability | Run commands on your own machine by attaching to a named tmux session. (src/hackingBuddyGPT/capabilities/local_shell.py#L14) | runs commands | no |
| PSExecRunCommand | Run commands on a Windows target through a psexec-created service. (src/hackingBuddyGPT/capabilities/psexec_run_command.py#L12) | runs commands | no |
| HTTPRequest | Send HTTP requests to a fixed target host and return the response. (src/hackingBuddyGPT/capabilities/http_request.py#L37) | sends data out | no |
| PentestPlaybook | Return OWASP-style web/API test checklists for a given topic (no side effects). (src/hackingBuddyGPT/capabilities/pentest_playbook.py#L20) | reads | no |
| record_note / submit_flag / task_solved | RecordNote stores a note in an in-memory registry for run bookkeeping. (src/hackingBuddyGPT/capabilities/record_note.py#L13) | reads | no |
| SubAgentCapability | A top-level agent with no direct target access delegates work to bounded sub-agents that hold the command capabilities. (src/hackingBuddyGPT/usecases/web/advanced.py#L40) | runs commands | no |
| HTTPRequest | The HTTP capability can issue state-changing and destructive methods (POST, PUT, DELETE, PATCH) against the target, not only read it. (src/hackingBuddyGPT/capabilities/http_request.py#L55) | changes, deletes, sends data out | no |

Partly listed: AD planner/executor task delegation (perform_task, objective_complete) and knowledge-base capabilities, and the web-API document/test phase engines, are not listed as separate groups.

## How it runs

Installed as a Python package; the wintermute CLI starts a chosen use-case that runs an asyncio round loop, calling an LLM through litellm (default OpenRouter) and driving a target via SSH, a local tmux shell, psexec or HTTP, writing each run to a JSONL log. (README.md#L15)

- Starts: On your machine, started by you. You run the installed wintermute CLI yourself in a terminal. (README.md#L40)
- Can also run: In a container on your machine (docker, switch `ghcr.io/ipa-lab/hackingbuddygpt:latest`). A bundled Dockerfile and a published GHCR image run wintermute inside a container. (README.md#L181)
- Can also run: On your machine, started by you (benchmark launcher, switch `benchmark_privesc.py`). A benchmark launcher attacks a fleet of locally running privesc_ Docker targets. (README.md#L212)
- Your machine: **wintermute CLI / use-case runner**: The wintermute CLI lists use-cases and starts the selected one on your machine. (README.md#L40)
- Your machine: **Local tmux shell**: In local_shell mode commands run on your own machine through a tmux session. (src/hackingBuddyGPT/utils/connectors/local_shell.py#L12)
- Your machine: **JSONL run logs**: Each run is written as an append-only JSONL trace under a logs directory. (src/hackingBuddyGPT/utils/logging.py#L94)
- Outside your machine: **LLM provider (via litellm)**: An LLM provider reached through litellm; the endpoint defaults to OpenRouter. (src/hackingBuddyGPT/utils/llm.py#L32)
- Outside your machine: **Target connector (SSH / psexec)**: The SSH/psexec connector drives the remote target you point it at. (src/hackingBuddyGPT/utils/connectors/ssh_connection.py#L10)
- Sends data to OpenRouter / litellm-reachable LLM provider (model provider, always): Sends prompts and receives completions from the model provider; endpoint defaults to OpenRouter. (src/hackingBuddyGPT/utils/llm.py#L32)
- Sends data to SSH target (your targets, by default): Connects to the SSH target you specify and runs commands on it. (src/hackingBuddyGPT/utils/connectors/ssh_connection.py#L10)
- Sends data to HTTP target host (your targets, if you turn it on): Sends HTTP requests to the named target host during web/API testing. (src/hackingBuddyGPT/capabilities/http_request.py#L37)
- Sends data to Windows psexec target (your targets, if you turn it on): Connects to a Windows target over psexec to run commands. (src/hackingBuddyGPT/utils/connectors/psexec.py#L9)
- Sends data to intercepting proxy (Burp/mitmproxy) (other, if you turn it on): Optionally routes LLM API traffic through an intercepting proxy such as Burp or mitmproxy. (src/hackingBuddyGPT/utils/llm.py#L39)
- Sends data to OpenAI embeddings (model provider, if you turn it on): In RAG mode sends documents to OpenAI embeddings to build a vector store. (src/hackingBuddyGPT/utils/rag.py#L28)
- Sends data to OpenRouter / Anthropic (model provider, by default): The shipped .env.example sets the model to openrouter/anthropic/claude-3.5-sonnet, so by default prompts (which embed target credentials) go to OpenRouter/Anthropic unless the endpoint is changed. (.env.example#L13)

## What you need

- Runtime: Python 3.13 or newer. (pyproject.toml#L15)
- Model key: An LLM provider API key (litellm format), default endpoint OpenRouter. (README.md#L120)
- Credentials: Target credentials for target-driving use-cases (SSH or Windows username and password). (README.md#L37)
- Authorisation: A target you own or are authorized to test. (README.md#L322)
- Other tools: A running tmux session when using local_shell mode. (README.md#L161)
- Installer: Documented install clones the repo (main branch, not pinned) and installs it editable with uv sync or a venv plus pip install -e .; no pipe-to-shell; it adds the wintermute and log console scripts. (README.md#L100-102)

## Limits and risks

- It executes real commands on live systems: in local-shell mode on your own machine, in SSH/psexec mode on the target. (README.md#L19)
- The target SSH username and password are interpolated into the prompt text sent to the LLM provider. (src/hackingBuddyGPT/usecases/priv_esc/_base.py#L22)
- SSH connections to targets do not verify host keys (known_hosts set to None). (src/hackingBuddyGPT/utils/connectors/async_ssh_connection.py#L45)
- The tool-calling system prompt tells the model not to ask for confirmation because nobody will answer; it keeps going until it escalates or runs out of ideas. (src/hackingBuddyGPT/usecases/priv_esc/minimal_linux_privesc_tool_calling.py#L113)
- Setting proxy_insecure turns off TLS certificate verification for the LLM API session. (src/hackingBuddyGPT/utils/llm.py#L54)
- The author describes the software as a research prototype and supports only the main branch. (SECURITY.md#L5)
- By default a run stops after 100 rounds or 10 dollars of cost; token and duration limits are off (0) unless set. (src/hackingBuddyGPT/utils/limits.py#L30-33)
- When a CLIENT_HTTP_PROXY/CLIENT_HTTPS_PROXY env var is set, HTTPRequest disables TLS certificate verification for target requests. (src/hackingBuddyGPT/capabilities/http_request.py#L28)
- The psexec target connector creates a Windows service on the target and runs each command through cmd.exe /c. (src/hackingBuddyGPT/utils/connectors/psexec.py#L23)
- SSHRunCommand auto-answers the target's sudo password prompt with the connection password supplied for the low-privilege user. (src/hackingBuddyGPT/capabilities/ssh_run_command.py#L24-27)
- A privilege-escalation success claimed by the model is checked against real command output from the run before it counts. (README.md#L85)

## Rights in plain language

- Declared: files 2 (writes outside the project), network 1 (talks only to declared hosts), execution 2 (runs shell commands or eval), secrets 1 (uses one scoped token), approval 2 (has broad pre-approvals).
- Code: reach 2 (open): files 2 (writes outside the project), network 2 (talks to any host), execution 2 (runs shell commands or eval), secrets 2 (reads broad tokens or the environment), persistence 2 (changes config or installs globally), approval 2 (has broad pre-approvals).
- Lab: not run yet.

Why three columns? Declarations are often incomplete and scanners can be bypassed, so we run each tool once and compare.

## Privilege Reach

Reach level 2 (open).

| Right | Declared | Code | Lab |
|---|---|---|---|
| Files: where does it read and write? | 2 writes outside the project | 2 writes outside the project | not run yet |
| Network: whom does it talk to? | 1 talks only to declared hosts | 2 talks to any host | not run yet |
| Execution: what does it run? | 2 runs shell commands or eval | 2 runs shell commands or eval | not run yet |
| Secrets: which credentials does it touch? | 1 uses one scoped token | 2 reads broad tokens or the environment | not run yet |
| Persistence: what survives the run? | not declared | 2 changes config or installs globally | not run yet |
| Approval: does it ask before acting? | 2 has broad pre-approvals | 2 has broad pre-approvals | not run yet |

0 contained · 1 scoped · 2 open · 3 privileged · ? no evidence · 0 never means safe

## Install

### Upstream (linked)

Quoted from `README.md#L93-98` at the pinned commit (not a command to copy): `git clone https://github.com/ipa-lab/hackingBuddyGPT.git
cd hackingBuddyGPT
uv sync
source .venv/bin/activate`


### Run it with least privilege

- note: `derived from the code, not tested in the lab; a research framework, run only against lab VMs you own, and give the lab target a throwaway SSH password, because the password is embedded in the prompt sent to the LLM provider`

- derived, not tested: proposed from the code analysis

## Lab runs

Not run yet.

## Questions and answers

**Why compare declared, code and lab?**

Declarations are often incomplete and scanners can be bypassed, so we run each tool once and compare.

**What rights does hackingBuddyGPT declare?**

files 2 (writes outside the project), network 1 (talks only to declared hosts), execution 2 (runs shell commands or eval), secrets 1 (uses one scoped token), approval 2 (has broad pre-approvals).

**What does its code suggest?**

reach 2 (open): files 2 (writes outside the project), network 2 (talks to any host), execution 2 (runs shell commands or eval), secrets 2 (reads broad tokens or the environment), persistence 2 (changes config or installs globally), approval 2 (has broad pre-approvals).

**What did it use when it ran in the lab?**

not run yet.

**Was it tried, and when?**

Not yet (tier listed).

**What changed since the last check?**

Upstream last pushed 2026-10-01; 0 release(s) since the pinned version.

**How do I run it with least privilege?**

Derived, not tested: note: derived from the code, not tested in the lab; a research framework, run only against lab VMs you own, and give the lab target a throwaway SSH password, because the password is embedded in the prompt sent to the LLM provider

Method: https://readbeforerun.ai/method/