An open-source Python framework that gives ethical hackers the plumbing for LLM-driven penetration testing agents, expressing complete experiments in roughly fifty lines of code against authorized targets.
| Tool | ipa-lab/hackingBuddyGPT — MIT-licensed framework for building LLM-driven security-testing agents in ~50 lines of code |
| Category | LLM agent framework for offensive security research and authorized penetration testing |
| Primary Use | Running LLM-driven experiments such as Linux/Windows privilege escalation, web/API testing, and AD assumed-breach testing against owned lab VMs |
| Safe Use | The README explicitly warns that it executes real commands on live systems; it must only be run against systems you own or are explicitly authorized to test, ideally isolated VMs or benchmark containers |
| Telemetry Note | Each run writes an append-only OpenTelemetry JSONL trace (gen_ai.* spans, OWASP AOS-compatible) capturing every prompt, completion, token count and cost — fully auditable by defenders and researchers alike |
ipa-lab/hackingBuddyGPT positions itself as the go-to framework for security researchers and penetration testers who want to experiment with large language models as autonomous testing agents. Rather than shipping yet another closed chat wrapper, it provides the unglamorous infrastructure — LLM connectivity, target connectors, capability wiring, run limits, and structured logging — so that a researcher can express a complete experiment, called a use-case, in a few dozen lines of code. With 1,284 stars, a Python codebase requiring 3.13+, an MIT license, and active CI, it reads as a serious academic-adjacent project rather than a weekend script.
The installation story is deliberately boring, which is a good sign. After cloning the repository, the recommended path is uv sync && source .venv/bin/activate, with a plain python -m venv plus pip install -e . as a fallback. Installing the package exposes a single wintermute entrypoint; invoking it with no arguments lists every registered use-case, and wintermute <UseCase> --help dumps the full option surface. There is also a published container image at ghcr.io/ipa-lab/hackingbuddygpt:latest, built on python:3.13-slim, for those who prefer not to touch their host Python.
Architecturally, the framework's central abstraction is the use-case, and each one becomes a wintermute sub-command. The README distinguishes two execution styles riding on one shared loop: native tool-calling agents that maintain a real chat history and drive targets through function calling, and simpler command strategies where a Mako template renders the whole history into one prompt and a single command is parsed from the reply. This dual design is pedagogically smart — the text-parsing loop is trivially hackable for prototyping, while the tool-calling variant is closer to how production agents operate.
The shipped privilege-escalation use-cases illustrate the progression clearly. MinimalPrivEscLinux is the classic loop in about twenty lines, and it is explicitly recommended as the starting point for building your own. Its twin, MinimalToolCallPrivEscLinux, keeps a genuine chat history and uses function calling, with a task_solved tool that is verified against ground truth — meaning a hallucinated or overly conceding claim of having obtained root cannot register a false success. This ground-truth verification is one of the framework's most important research contributions, because self-reported agent success is notoriously unreliable.
Beyond the minimal examples, PrivEscLinux adds optional retrieval-augmented generation via --rag_path, chain-of-thought with --enable_cot, state tracking, and structured guidance, while PrivEscWindows ports the strategy-based approach to Windows targets driven through psexec instead of SSH. A composed example, ExPrivEscLinuxLSE, runs lse.sh on the target first, converts the enumeration output into hints, and then orchestrates PrivEscLinux per hint — demonstrating that use-cases can call other use-cases, which is effectively an agent-orchestration pattern.
Web and API coverage is broader than the project's name might suggest. WebTestingWithExplanation autonomously tests a web page over HTTP while surfacing the model's reasoning and includes an OWASP-style playbook capability; WebTestingWithShell adds shell access to a Kali-style attacker box; and AdvancedWebTesting introduces a top-level agent with no direct target access that delegates to bounded sub-agents. On the API side, WebAPITesting detects whether the target exposes an OpenAPI spec or a sitemap, then pentests the REST surface in document, test, or auto modes.
The most ambitious entry is the AD use-case, an autonomous assumed-breach Active Directory test ported from the cochise attack tool. Its planner/executor split is worth studying: a persistent strategic planner maintains a task tree and a shared knowledge base, while each task is delegated to a fresh, memoryless tactical executor. This mirrors well-known human red-team tradecraft — separating strategy from execution — and it is a design pattern that other agent builders would do well to copy, whether for offensive research or defensive simulation.
Configuration is resolved through four layers, each overriding the previous: environment variables, a .env file (started from cp .env.example .env), a JSON file via --config config.json, and finally --key=value CLI flags with the highest priority. All LLM traffic flows through litellm, so llm.model accepts provider-agnostic strings like gpt-4o, openrouter/anthropic/claude-3.5-sonnet, or ollama_chat/llama3 for a fully local setup. Notably, the default llm.api_base points at OpenRouter, so anyone wanting direct OpenAI connectivity or a local Ollama must change it — an operational detail worth knowing before your first run. The --llm.proxy option lets you route API traffic through Burp or mitmproxy, which is exactly the kind of observability hook a professional reviewer wants to see.
Run governance is unusually disciplined. Any run can be capped simultaneously by rounds, tokens, cost in dollars, and wall-clock duration through --limits.max_rounds, --limits.max_tokens, --limits.max_cost, and --limits.max_duration. This matters in practice because LLM agents are famous for spiraling; hard financial ceilings in the CLI defaults (ten dollars in the example output) show the authors have actually burned their own money on runaway loops. Execution is fully asynchronous on asyncio, and a Docker-fleet benchmark launcher supports regression testing across many targets simultaneously.
Logging may be the framework's strongest defensive-facing feature. Every run emits an append-only logs/log-<timestamp>.jsonl file where each line is a complete OpenTelemetry span following GenAI semantic conventions (gen_ai.*), with prompts and completions stored as structured message parts matching the OWASP Agent Observability Standard. Because the format is self-contained, traces can be inspected directly or piped into external OTel tooling, and two companion CLIs — hackingbuddygpt-log-view for replaying a run and hackingbuddygpt-log-analyze for aggregating duration, token counts, cost, and tool calls across runs, including LaTeX table export — make post-run analysis a first-class workflow.
The research context around the project reinforces its credibility: the team maintains a reusable Linux privilege-escalation benchmark repository, publishes findings as open-access reports, and offers an arXiv paper comparing multiple LLMs for these tasks. For practice targets, the README points at its own benchmark fleet and deliberately vulnerable VMs such as Lin.Security from VulnHub. The disclaimers are prominent and correct — the tool executes real commands, in local-shell mode on your own machine and over SSH or psexec on whatever you point it at, and the authors state plainly that it should only ever target systems you own or are explicitly authorized to test, preferring isolated VMs or containers.
For authorized professionals, hackingBuddyGPT occupies a distinctive niche: it is less a weaponized tool and more a reproducible experimental harness for studying how LLMs behave in offensive workflows. Defenders benefit from the same body of work — ground-truth-verified agent runs, cost-bounded experiments, and fully traced agent behavior are exactly the artifacts needed to understand and detect agentic attack tooling. If your team is evaluating how LLM agents perform in penetration testing, or building training labs around them, this repository and its benchmark ecosystem are among the most rigorous places to start.
ipa-lab/hackingBuddyGPT.Educational analysis for authorized security professionals. Use only in controlled, authorized environments.
Related coverage
0 comentários:
Post a Comment
Note: Only a member of this blog may post a comment.