ReadBeforeRunAgentic Security Field Guide

Catalog / Agent

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.

Beta: The package classifiers set Development Status :: 4 - Beta. pyproject.toml L22

For Web and API testing, Identity attack pathsWorks with Standalone (own model access)Maintained ipa-lab, last push 2026-10-01

AgentAn agent is a program with its own model access that works through a task on its own. by ipa-lab · read from the code at 799f57e (0.5.0) on 2026-10-19The date we last read the tool’s files. The code after “at” names the exact version (the git commit) we read; a newer version may differ. · Not run yet.Whether we have run the tool in our lab. “Did more than it said” means the run used rights its description does not name; “did no more than it said” means it stayed within them.

Code showsWhat a reading of the code found the tool can do, at the checked version, in the words of the rights table in the record. It is a ceiling, not what the tool did. A right marked unknown has no evidence either way, and that never counts as harmless.

What the code shows, worst first. No run advice yet: the one word needs a read under the full rule.

  1. Files. The SSH capability runs arbitrary commands on the target machine, which can create or modify files there (F.3 FS 2: on the target).

    ssh_execute_command.py L25

  2. Network. All prompt data goes to a configurable LLM endpoint defaulting to a third party, and the HTTP capability reaches LLM-chosen URLs.

    llm.py L32

  3. Execution. Runs arbitrary attacker- or model-chosen shell commands on the target.

    psexec.py L35

  4. Secrets. The config layer enumerates the entire process environment, and a run also needs an LLM key plus SSH credentials.

    configurable.py L717

  5. Persistence. The psexec connector installs a service on the Windows target to execute commands.

    psexec.py L23

  6. Approval. Each model-proposed command is run immediately with no human confirmation, and only the configured run limits gate a run.

    strategies.py L80

Before first useSettings for your AI client that limit the tool to the rights its task needs; derived from the code unless marked tested. derived from the code, not tested

  1. 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.

What we checked, and what we foundDisagree?

Agent · code showsreach 2 · open
222222FilesNetworkExecutionSecretsPersistenceApproval

What the code can reach, 0 to 3 per right; a dashed point means no evidence, never zero. The three readings

Is it for you?

Made for
  • 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 it when
Not for
  • The author restricts use to educational purposes and systems you are authorized to test.
  • The author warns never to run it against real production systems and to prefer vulnerable VMs.
You need
  • 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

Details

Install

linked, not distributed: the Field Guide does not bundle agents or MCP servers

Upstream (linked)

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

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

End of the card. Below: what we checked, and what we found.MarkdownJSON

The record · every value with its evidence

What we checked, and what we found.

Profile read at commit 799f57e on 2026-10-25: 53 facts, each with its quoted line confirmed by script; not installed, not run in the lab.Each fact was read from the tool's files at the checked version and links to the line it comes from. Where nothing was found, the page says so instead of assuming “none”.

Selected by criteria v0.1, approved by Ilja Schlak: awaiting approval. Each section opens with the answer; the file and line of every fact follow it.

What it can change the capability groups as upstream groups them, worst first

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.

GroupWhat it coversEffectOn by default
HTTPRequestThe HTTP capability can issue state-changing and destructive methods (POST, PUT, DELETE, PATCH) against the target, not only read it. http_request.py L55changes, deletes, sends data outno, optional
LocalShellCapabilityRun commands on your own machine by attaching to a named tmux session. local_shell.py L14runs commandsno, optional
PSExecRunCommandRun commands on a Windows target through a psexec-created service. psexec_run_command.py L12runs commandsno, optional
SubAgentCapabilityA top-level agent with no direct target access delegates work to bounded sub-agents that hold the command capabilities. advanced.py L40runs commandsno, optional
HTTPRequestSend HTTP requests to a fixed target host and return the response. http_request.py L37sends data outno, optional
PentestPlaybookReturn OWASP-style web/API test checklists for a given topic (no side effects). pentest_playbook.py L20readsno, optional
record_note / submit_flag / task_solvedRecordNote stores a note in an in-memory registry for run bookkeeping. record_note.py L13readsno, optional

Where it sends data and who can connect to it

7 outside connections found in the files read: OpenRouter / litellm-reachable LLM provider, SSH target, HTTP target host, Windows psexec target, intercepting proxy (Burp/mitmproxy), OpenAI embeddings, OpenRouter / Anthropic.

Listens for no connections in the files read.

Other connections not ruled out: read in the documentation and the cited code, not searched in full.

How it runs generated from the files read, never drawn by hand

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

Your machine

Programs and files on the machine where you run the tool.

Outside your machine

Remote services: vendor APIs, model providers, targets, telemetry endpoints. Data sent here leaves your machine.

The six rights, read three waysThe six rights a tool can take (files, network, execution, secrets, persistence, approval), each read three ways and rated 0 to 3. 0 never means safe; “?” means no evidence. what the author says, what the code shows, what one lab run showed

Level 2 (open), read from the code. Not run in our lab yet.

RightAuthor sayswhat the author saysCode showswhat static analysis findsRun showedwhat one lab run showed
Fileswhere does it read and write?
Networkwhom does it talk to?
Executionwhat does it run?
Secretswhich credentials does it touch?
Persistencewhat survives the run?
Approvaldoes it ask before acting?

0 contained · 1 scoped · 2 open · 3 privileged · ? no evidence · 0 never means safe · zero means: none declared (Declared), none found (Code), none observed (Lab)

Author says: the evidence

  • Files · 2README.md L19 author states local-shell mode runs commands on the user's own machine
  • Network · 1README.md L19 author declares the network target is the host the user points it at in SSH or psexec mode
  • Execution · 2README.md L19 author states the software executes real commands on live systems
  • Secrets · 1README.md L120 author says one provider API key is supplied by the user
  • Approval · 2README.md L62 author describes use cases that run autonomously with no human approval step

Code shows: the evidence

  • Files · 2ssh_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)
  • Network · 2llm.py L32 all prompt data goes to a configurable LLM endpoint defaulting to a third party, and the HTTP capability reaches LLM-chosen URLs
  • Execution · 2psexec.py L35 runs arbitrary attacker- or model-chosen shell commands on the target
  • Secrets · 2configurable.py L717 the config layer enumerates the entire process environment, and a run also needs an LLM key plus SSH credentials
  • Persistence · 2psexec.py L23 the psexec connector installs a service on the Windows target to execute commands
  • Approval · 2strategies.py L80 each model-proposed command is run immediately with no human confirmation, and only the configured run limits gate a run

Valid for commit 799f57e (0.5.0) · checked 2026-10-19 · method reach-v0.1The published rules we follow: how tools are selected, how their rights are read and rated, how a lab run is done.

Limits and risks what the files say that fits nowhere else, and what this reading does not cover

What you need and what the documented installer does

KindWhat
AI clientStandalone (own model access)
RuntimePython 3.13 or newer. pyproject.toml L15
Model keyAn LLM provider API key (litellm format), default endpoint OpenRouter. README.md L120
CredentialsTarget credentials for target-driving use-cases (SSH or Windows username and password). README.md L37
AuthorisationA target you own or are authorized to test. README.md L322
Other toolsA running tmux session when using local_shell mode. README.md L161

What the documented installer does

Lab runs one run is an observation, not a benchmark

No lab run yet. Once we run it, this section shows what it did and whether it did more than it said.

About this entry

AutonomyHow much the tool decides on its own, from 0 (every step is yours) to 5 (runs a whole task unattended), as the author describes it.
level 3 of 5
Source
github.com/ipa-lab/hackingBuddyGPT · MIT · manifest pyproject.toml
Version readThe install command installs exactly the version we checked (the pinned git commit), so what you get is what the card describes.
799f57e · 0.5.0 · last upstream push 2026-10-01 · no release since the pinned commit
In the catalog
listed · added 2026-10-19 · last checked 2026-10-19 · next check 2027-01-17 · fresh
ScannersA scan of the tool's files with a scanner for malicious patterns. “Pending” means it has not run yet.
cisco-skill-scanner: not run, pending
Changes
none since the entry was added on 2026-10-19
MethodThe published rules we follow: how tools are selected, how their rights are read and rated, how a lab run is done.
v0.1 · reach-v0.1 · badge · the rules

Disagree?

Dispute a value with evidence (file, line, commit): write to hello@readbeforerun.ai. A dispute is checked against the pinned commit; a changed value is logged under Changes.

This entry as Markdownas JSON

How this entry was checked, and how to cite it

Selected by the published criteria (method v0.1). What the author says comes only from author statements; what the code shows comes from the code and manifests at commit 799f57e, each with one evidence line. A “?” means no evidence, never zero; zero never means safe.

The descriptive profile (what it does, can do, how it runs, what it needs) was read through the same isolated pipeline at commit 799f57e on 2026-10-25: one reader proposed every fact with a quoted line, a script confirmed each quoted line (53 of 53), and a second reader checked each sentence against its lines. Where nothing was found, the page says so instead of assuming “none”.

Known issues and limits: remote server-side behaviour stays “?”; the lab is not your production; static analysis can miss runtime behaviour.

Placement, badges or fast tracks are not for sale. The author is employed by an IT consultancy; the company has no influence on selection, execution or result.

Cite this:

Ilja Schlak. "hackingBuddyGPT". Agentic Security Field Guide, checked 2026-10-19, method reach-v0.1. https://readbeforerun.ai/catalog/hackingbuddygpt/

The method · the rules

For maintainers

Badge for your README (reach 2 · not run yet):

[![reach 2 · not run yet](https://readbeforerun.ai/badge/hackingbuddygpt.svg)](https://readbeforerun.ai/catalog/hackingbuddygpt/)

Dispute a value with evidence (file, line, commit): write to hello@readbeforerun.ai. A dispute is checked against the pinned commit; a changed value is logged under Changes.

Claim the entry with a fieldguide.yaml in your repository: planned.

Other tools for the same task

Tasks: Web and API testing, Identity attack paths. The task pages compare every tool side by side.
  1. 21223?
    Webapp Testing ChecklistSkill · by AccessITGroup · reach 3, privilegedDraft · awaiting review

    Agent skill that walks an authorized web application test through the OWASP WSTG checklist and writes a findings report.

    Can add autostart, users or keys · write outside the project · run shell commands or eval · +1 more · Approval: no evidence · not run yet · checked 2026-10-21

    Code shows
  2. 11113?
    Supercharged Tenable Identity Exposure MCP ServerMCP server · by taherkaraki · reach 3, privilegedDraft · awaiting review

    MCP server that exposes the Tenable Identity Exposure API as 133 tools, from Active Directory exposure queries to user and API-key management.

    Can add autostart, users or keys · Approval: no evidence · not run yet · checked 2026-10-21

    Code shows
  3. 222123
    ShannonAgent · by KeygraphHQ · reach 3, privilegedDraft · awaiting review

    Autonomous white-box AI penetration tester for web apps and APIs; reports only vulnerabilities it proves by exploitation.

    Can bypass approval · write outside the project · talk to any host · +2 more · not run yet · checked 2026-10-19

    Code shows
  4. 233232
    StrixAgent · by usestrix · reach 3, privilegedDraft · awaiting review

    Autonomous AI penetration-testing agents that run offensive tools in a container sandbox and validate findings with a proof of concept.

    Can tunnel or exfiltrate · use sudo or the docker socket · add autostart, users or keys · +3 more · not run yet · checked 2026-10-19

    Code shows