{ "$schema": "https://readbeforerun.ai/schema/entry.schema.json", "entry": { "id": "hackingbuddygpt", "name": "hackingBuddyGPT", "summary": "Open-source framework for building LLM-driven security-testing agents, with use cases for Linux privilege escalation and web API testing.", "draft": "review", "type": "agent", "mission": [ "offensive" ], "task": [ "web-api-testing", "identity-attack-paths" ], "domain": [ "application-security", "identity-access" ], "runtime": [ "standalone" ], "tier": "listed", "last_checked": "2026-10-19", "next_check": "2027-01-17", "freshness": "fresh", "superseded": false, "in_my_kit": null, "advice": null, "code_shows": "writes outside the project · talks to any host · runs shell commands or eval · reads broad tokens or the environment · changes config or installs globally · has broad pre-approvals", "source": { "repo": "https://github.com/ipa-lab/hackingBuddyGPT", "subpath": null, "commit": "799f57e9d439ff80da506714fcf6c5124b342cd6", "version": "0.5.0", "license": "MIT" }, "install": { "skills_cli": null, "claude_code": null, "upstream": "git clone https://github.com/ipa-lab/hackingBuddyGPT.git\ncd hackingBuddyGPT\nuv sync\nsource .venv/bin/activate", "bundled": false }, "scan": { "status": "static scan pending (not run)" }, "reach": { "method": "reach-v0.1", "level": 2, "level_source": "static", "level_label": "open", "unknown_axes": 0, "verdict": "not-run", "badge": "reach 2 · not run yet", "long": "reach 2 from code (open); lab: not run yet", "declared": { "fs": 2, "net": 1, "exec": 2, "cred": 1, "hitl": 2 }, "static": { "level": 2, "fs": 2, "net": 2, "exec": 2, "cred": 2, "persist": 2, "hitl": 2, "unknown": [] }, "observed": null, "surplus": null, "fit": null, "exports": { "aivss": { "fs": 0.5, "net": 0.5, "exec": 0.5, "cred": 0.5, "persist": 0.5, "hitl": 0.5 }, "usf_risk_tier": "L2" } }, "profile": { "read_at": "799f57e9d439ff80da506714fcf6c5124b342cd6", "read_on": "2026-10-25", "overview": "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.", "purpose": [ "Build LLM-driven security-testing agents while the framework supplies LLM connectivity, target connectors, run limits and logging.", "Support reproducible research alongside a re-usable Linux privilege-escalation benchmark." ], "use_cases": [ { "text": "Escalate privileges on a Linux SSH target", "task": "identity-attack-paths" }, { "text": "Pentest a REST API detected from an OpenAPI spec or sitemap", "task": "web-api-testing" }, { "text": "Run an Active Directory assumed-breach pentest", "task": "identity-attack-paths" }, { "text": "Test a web page over HTTP", "task": "web-api-testing" } ], "maturity": "beta", "capabilities": [ { "name": "LocalShellCapability", "effects": [ "runs-commands" ], "enabled": "optional" }, { "name": "PSExecRunCommand", "effects": [ "runs-commands" ], "enabled": "optional" }, { "name": "HTTPRequest", "effects": [ "sends-data" ], "enabled": "optional" }, { "name": "PentestPlaybook", "effects": [ "reads" ], "enabled": "optional" }, { "name": "record_note / submit_flag / task_solved", "effects": [ "reads" ], "enabled": "optional" }, { "name": "SubAgentCapability", "effects": [ "runs-commands" ], "enabled": "optional" }, { "name": "HTTPRequest", "effects": [ "changes", "deletes", "sends-data" ], "enabled": "optional" } ], "effects": [ "reads", "changes", "deletes", "runs-commands", "sends-data" ], "runs": "local-program", "listens": [], "sends_to": [ { "to": "OpenRouter / litellm-reachable LLM provider", "kind": "model-provider", "when": "always" }, { "to": "SSH target", "kind": "target", "when": "default" }, { "to": "HTTP target host", "kind": "target", "when": "optional" }, { "to": "Windows psexec target", "kind": "target", "when": "optional" }, { "to": "intercepting proxy (Burp/mitmproxy)", "kind": "other", "when": "optional" }, { "to": "OpenAI embeddings", "kind": "model-provider", "when": "optional" }, { "to": "OpenRouter / Anthropic", "kind": "model-provider", "when": "default" } ], "model": "own-key", "needs": [ { "kind": "runtime", "text": "Python 3.13 or newer." }, { "kind": "model-key", "text": "An LLM provider API key (litellm format), default endpoint OpenRouter." }, { "kind": "credentials", "text": "Target credentials for target-driving use-cases (SSH or Windows username and password)." }, { "kind": "authorization", "text": "A target you own or are authorized to test." }, { "kind": "tools", "text": "A running tmux session when using local_shell mode." } ] }, "urls": { "page": "/catalog/hackingbuddygpt/", "json": "/entries/hackingbuddygpt.json", "md": "/catalog/hackingbuddygpt.md", "badge": "/badge/hackingbuddygpt.svg" } }, "data": { "schema_version": "0.5", "slug": "hackingbuddygpt", "name": "hackingBuddyGPT", "summary": "Open-source framework for building LLM-driven security-testing agents, with use cases for Linux privilege escalation and web API testing.", "draft": "review", "in_my_kit": null, "type": "agent", "mission": [ "offensive" ], "task": [ "web-api-testing", "identity-attack-paths" ], "domain": [ "application-security", "identity-access" ], "phase": [ "off:post-access" ], "role": [ "pentest" ], "runtime": [ "standalone" ], "auth": null, "autonomy": 3, "addresses": [], "frameworks": { "owasp_ast": [], "owasp_asi": [], "attack_tactic": [], "atlas": [] }, "source": { "repo": "https://github.com/ipa-lab/hackingBuddyGPT", "commit": "799f57e9d439ff80da506714fcf6c5124b342cd6", "version": "0.5.0", "license": "MIT", "manifest": "pyproject.toml", "also_listed": {} }, "upstream": { "checked_at": "2026-10-19", "updated_at": "2026-10-01", "current_release": null, "archived": false, "stars": 1276, "commit_history": {}, "releases_since_pin": 0 }, "install": { "upstream": "git clone https://github.com/ipa-lab/hackingBuddyGPT.git\ncd hackingBuddyGPT\nuv sync\nsource .venv/bin/activate", "upstream_evidence": "README.md#L93-98", "bundled": false }, "scan": [ { "tool": "cisco-skill-scanner", "version": "not-run", "llm_judge": false, "date": "2026-10-19", "result": "pending" } ], "privileges": { "method": "reach-v0.1", "declared": { "axes": { "fs": 2, "net": 1, "exec": 2, "cred": 1, "hitl": 2 }, "evidence": { "fs": "README.md#L19 author states local-shell mode runs commands on the user's own machine", "net": "README.md#L19 author declares the network target is the host the user points it at in SSH or psexec mode", "exec": "README.md#L19 author states the software executes real commands on live systems", "cred": "README.md#L120 author says one provider API key is supplied by the user", "hitl": "README.md#L62 author describes use cases that run autonomously with no human approval step" } }, "static": { "level": 2, "axes": { "fs": 2, "net": 2, "exec": 2, "cred": 2, "persist": 2, "hitl": 2 }, "evidence": { "fs": "src/hackingBuddyGPT/capabilities/ssh_execute_command.py#L25 the SSH capability runs arbitrary commands on the target machine, which can create or modify files there (F.3 FS 2: on the target)", "net": "src/hackingBuddyGPT/utils/llm.py#L32 all prompt data goes to a configurable LLM endpoint defaulting to a third party, and the HTTP capability reaches LLM-chosen URLs", "exec": "src/hackingBuddyGPT/utils/connectors/psexec.py#L35 runs arbitrary attacker- or model-chosen shell commands on the target", "cred": "src/hackingBuddyGPT/utils/configurable.py#L717 the config layer enumerates the entire process environment, and a run also needs an LLM key plus SSH credentials", "persist": "src/hackingBuddyGPT/utils/connectors/psexec.py#L23 the psexec connector installs a service on the Windows target to execute commands", "hitl": "src/hackingBuddyGPT/strategies.py#L80 each model-proposed command is run immediately with no human confirmation, and only the configured run limits gate a run" }, "unknown": [] }, "min_config": { "status": "derived", "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" }, "override": null, "reviews": [] }, "status": { "tier": "listed", "last_checked": "2026-10-19", "next_check": "2027-01-17", "freshness": "fresh", "superseded": false, "superseded_by": null, "added": "2026-10-19", "added_by": "scout" }, "evidence": { "runs": [], "badge": "/badge/hackingbuddygpt.svg" }, "changes": [] }, "profile": { "schema_version": "0.1", "entry": "hackingbuddygpt", "draft": "review", "commit": "799f57e9d439ff80da506714fcf6c5124b342cd6", "read_on": "2026-10-25", "check": { "date": "2026-10-25", "facts": 53, "confirmed": 53, "verified": 47 }, "overview": { "text": "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.", "ev": "README.md#L15 author's one-line description of the framework" }, "maturity": { "word": "beta", "text": "The package classifiers set Development Status :: 4 - Beta.", "ev": "pyproject.toml#L22 development status classifier" }, "purpose": [ { "text": "Build LLM-driven security-testing agents while the framework supplies LLM connectivity, target connectors, run limits and logging.", "ev": "README.md#L15 states what the framework is for" }, { "text": "Support reproducible research alongside a re-usable Linux privilege-escalation benchmark.", "ev": "README.md#L17 states the research/benchmark purpose" } ], "use_cases": [ { "text": "Escalate privileges on a Linux SSH target", "task": "identity-attack-paths", "ev": "README.md#L52 MinimalPrivEscLinux use-case description" }, { "text": "Pentest a REST API detected from an OpenAPI spec or sitemap", "task": "web-api-testing", "ev": "README.md#L70 WebAPITesting use-case description" }, { "text": "Run an Active Directory assumed-breach pentest", "task": "identity-attack-paths", "ev": "README.md#L76 AD use-case description" }, { "text": "Test a web page over HTTP", "task": "web-api-testing", "ev": "README.md#L62 WebTestingWithExplanation description" } ], "not_for": [ { "text": "The author restricts use to educational purposes and systems you are authorized to test.", "ev": "README.md#L322 legal and ethical use disclaimer" }, { "text": "The author warns never to run it against real production systems and to prefer vulnerable VMs.", "ev": "README.md#L174 connection-modes warning" } ], "autonomy": { "text": "An autonomous use-case loops over model-chosen rounds with no per-step approval, stopping only when a configured limit on rounds, tokens, cost or duration is reached.", "ev": "src/hackingBuddyGPT/usecases/usecase.py#L78 the unattended round loop bounded by limits" }, "capabilities": { "coverage": "partial", "missing": "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.", "groups": [ { "name": "LocalShellCapability", "does": "Run commands on your own machine by attaching to a named tmux session.", "effects": [ "runs-commands" ], "enabled": "optional", "ev": "src/hackingBuddyGPT/capabilities/local_shell.py#L14 describes running the command on the local shell via tmux" }, { "name": "PSExecRunCommand", "does": "Run commands on a Windows target through a psexec-created service.", "effects": [ "runs-commands" ], "enabled": "optional", "ev": "src/hackingBuddyGPT/capabilities/psexec_run_command.py#L12 describes running the command on the windows machine" }, { "name": "HTTPRequest", "does": "Send HTTP requests to a fixed target host and return the response.", "effects": [ "sends-data" ], "enabled": "optional", "ev": "src/hackingBuddyGPT/capabilities/http_request.py#L37 describes sending a request to the host" }, { "name": "PentestPlaybook", "does": "Return OWASP-style web/API test checklists for a given topic (no side effects).", "effects": [ "reads" ], "enabled": "optional", "ev": "src/hackingBuddyGPT/capabilities/pentest_playbook.py#L20 describes returning a checklist" }, { "name": "record_note / submit_flag / task_solved", "does": "RecordNote stores a note in an in-memory registry for run bookkeeping.", "effects": [ "reads" ], "enabled": "optional", "ev": "src/hackingBuddyGPT/capabilities/record_note.py#L13 describes recording a note" }, { "name": "SubAgentCapability", "does": "A top-level agent with no direct target access delegates work to bounded sub-agents that hold the command capabilities.", "effects": [ "runs-commands" ], "enabled": "optional", "ev": "src/hackingBuddyGPT/usecases/web/advanced.py#L40 sub-agent is given submit_flag and kali command capabilities" }, { "name": "HTTPRequest", "does": "The HTTP capability can issue state-changing and destructive methods (POST, PUT, DELETE, PATCH) against the target, not only read it.", "effects": [ "changes", "deletes", "sends-data" ], "enabled": "optional", "ev": "src/hackingBuddyGPT/capabilities/http_request.py#L55 method literal lists DELETE/PUT/POST/PATCH" } ] }, "architecture": { "summary": { "text": "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.", "ev": "README.md#L15 lists the groundwork parts and connectors" }, "runs": { "where": "local-program", "text": "You run the installed wintermute CLI yourself in a terminal.", "ev": "README.md#L40 installing the package provides the wintermute command" }, "modes": [ { "where": "container", "mode": "docker", "switch": "ghcr.io/ipa-lab/hackingbuddygpt:latest", "text": "A bundled Dockerfile and a published GHCR image run wintermute inside a container.", "ev": "README.md#L181 docker run of the published image" }, { "where": "local-program", "mode": "benchmark launcher", "switch": "benchmark_privesc.py", "text": "A benchmark launcher attacks a fleet of locally running privesc_ Docker targets.", "ev": "README.md#L212 benchmark launcher invocation" } ], "parts": [ { "name": "wintermute CLI / use-case runner", "zone": "machine", "does": "The wintermute CLI lists use-cases and starts the selected one on your machine.", "ev": "README.md#L40 wintermute command provided by the package" }, { "name": "LLM provider (via litellm)", "zone": "outside", "does": "An LLM provider reached through litellm; the endpoint defaults to OpenRouter.", "ev": "src/hackingBuddyGPT/utils/llm.py#L32 api_base default is OpenRouter" }, { "name": "Target connector (SSH / psexec)", "zone": "outside", "does": "The SSH/psexec connector drives the remote target you point it at.", "ev": "src/hackingBuddyGPT/utils/connectors/ssh_connection.py#L10 connects to a remote host via SSH" }, { "name": "Local tmux shell", "zone": "machine", "does": "In local_shell mode commands run on your own machine through a tmux session.", "ev": "src/hackingBuddyGPT/utils/connectors/local_shell.py#L12 attaches to a local shell inside tmux" }, { "name": "JSONL run logs", "zone": "machine", "does": "Each run is written as an append-only JSONL trace under a logs directory.", "ev": "src/hackingBuddyGPT/utils/logging.py#L94 log_dir default is logs" } ], "listens": [], "connections": [ { "to": "OpenRouter / litellm-reachable LLM provider", "kind": "model-provider", "when": "always", "what": "Sends prompts and receives completions from the model provider; endpoint defaults to OpenRouter.", "ev": "src/hackingBuddyGPT/utils/llm.py#L32 api_base default OpenRouter" }, { "to": "SSH target", "kind": "target", "when": "default", "what": "Connects to the SSH target you specify and runs commands on it.", "ev": "src/hackingBuddyGPT/utils/connectors/ssh_connection.py#L10 connects to a remote host via SSH" }, { "to": "HTTP target host", "kind": "target", "when": "optional", "what": "Sends HTTP requests to the named target host during web/API testing.", "ev": "src/hackingBuddyGPT/capabilities/http_request.py#L37 sends a request to the host" }, { "to": "Windows psexec target", "kind": "target", "when": "optional", "what": "Connects to a Windows target over psexec to run commands.", "ev": "src/hackingBuddyGPT/utils/connectors/psexec.py#L9 connects to a remote host via PSExec" }, { "to": "intercepting proxy (Burp/mitmproxy)", "kind": "other", "when": "optional", "what": "Optionally routes LLM API traffic through an intercepting proxy such as Burp or mitmproxy.", "ev": "src/hackingBuddyGPT/utils/llm.py#L39 proxy URL parameter" }, { "to": "OpenAI embeddings", "kind": "model-provider", "when": "optional", "what": "In RAG mode sends documents to OpenAI embeddings to build a vector store.", "ev": "src/hackingBuddyGPT/utils/rag.py#L28 OpenAI embeddings call" }, { "to": "OpenRouter / Anthropic", "kind": "model-provider", "when": "default", "what": "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.", "ev": ".env.example#L13 default llm.model value" } ], "model": { "who": "own-key", "text": "The framework calls an LLM provider with your API key through litellm; the client's own model is not used.", "ev": "src/hackingBuddyGPT/utils/llm.py#L29 api_key parameter for the upstream" } }, "needs": [ { "kind": "runtime", "text": "Python 3.13 or newer.", "ev": "pyproject.toml#L15 requires-python" }, { "kind": "model-key", "text": "An LLM provider API key (litellm format), default endpoint OpenRouter.", "ev": "README.md#L120 llm.api_key is the provider key" }, { "kind": "credentials", "text": "Target credentials for target-driving use-cases (SSH or Windows username and password).", "ev": "README.md#L37 example SSH username and password flags" }, { "kind": "authorization", "text": "A target you own or are authorized to test.", "ev": "README.md#L322 authorized-use statement" }, { "kind": "tools", "text": "A running tmux session when using local_shell mode.", "ev": "README.md#L161 create a named tmux session first" } ], "installer": [ { "text": "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.", "ev": "README.md#L100-102 venv plus editable pip install" } ], "limits": [ { "text": "It executes real commands on live systems: in local-shell mode on your own machine, in SSH/psexec mode on the target.", "ev": "README.md#L19 top-of-readme warning" }, { "text": "The target SSH username and password are interpolated into the prompt text sent to the LLM provider.", "ev": "src/hackingBuddyGPT/usecases/priv_esc/_base.py#L22 prompt template embeds conn.username and conn.password" }, { "text": "SSH connections to targets do not verify host keys (known_hosts set to None).", "ev": "src/hackingBuddyGPT/utils/connectors/async_ssh_connection.py#L45 disables host key checking" }, { "text": "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.", "ev": "src/hackingBuddyGPT/usecases/priv_esc/minimal_linux_privesc_tool_calling.py#L113 system-message instruction" }, { "text": "Setting proxy_insecure turns off TLS certificate verification for the LLM API session.", "ev": "src/hackingBuddyGPT/utils/llm.py#L54 httpx client verify tied to proxy_insecure" }, { "text": "The author describes the software as a research prototype and supports only the main branch.", "ev": "SECURITY.md#L5 supported versions note" }, { "text": "By default a run stops after 100 rounds or 10 dollars of cost; token and duration limits are off (0) unless set.", "ev": "src/hackingBuddyGPT/utils/limits.py#L30-33 default limit values" }, { "text": "When a CLIENT_HTTP_PROXY/CLIENT_HTTPS_PROXY env var is set, HTTPRequest disables TLS certificate verification for target requests.", "ev": "src/hackingBuddyGPT/capabilities/http_request.py#L28 sets verify False under a client proxy" }, { "text": "The psexec target connector creates a Windows service on the target and runs each command through cmd.exe /c.", "ev": "src/hackingBuddyGPT/utils/connectors/psexec.py#L23 init creates a service on the target" }, { "text": "SSHRunCommand auto-answers the target's sudo password prompt with the connection password supplied for the low-privilege user.", "ev": "src/hackingBuddyGPT/capabilities/ssh_run_command.py#L24-27 a Responder matches the sudo prompt and replies with conn.password" }, { "text": "A privilege-escalation success claimed by the model is checked against real command output from the run before it counts.", "ev": "README.md#L85 framework feature: a claimed root is verified against real command output (code: task_solved is rejected unless uid=0 output, a root login test or the live shell supports it)" } ], "not_found": [ { "field": "listen", "searched": "README.md, utils/llm.py, utils/logging.py, cli/log_viewer.py, connectors; no bind/port/listener code in the download (copilot-instructions.md#L60 only warns about a web viewer)" }, { "field": "capability_count", "searched": "README.md and pyproject.toml for an author-stated number of tools/use-cases; found descriptive counts like '50 lines' and '~20-line' but no tool/use-case total" } ] }, "verdict": null, "runs": [] }