Skip to content

Commit 5460731

Browse files
andreashappeandreashappe
committed
update README.md
1 parent 138e44c commit 5460731

1 file changed

Lines changed: 57 additions & 54 deletions

File tree

‎README.md‎

Lines changed: 57 additions & 54 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,7 @@
1-
**NEITHER THE IPA-LAB NOR HACKINGBUDDYGPT ARE INVOLVED IN ANY CRYPTO COIN! ALL INFORMATION TO THE CONTRARY IS BEING USED TO SCAM YOU! THE TWITTER ACCOUNT THAT CURRENTLY EXISTS IS JUST TRYING TO GET YOUR MONEY, DO NOT FALL FOR IT!**
2-
3-
4-
# <div class="vertical-align: middle"><img src="https://github.com/ipa-lab/hackingBuddyGPT/blob/main/docs/hackingbuddy-rounded.png?raw=true" width="72"> HackingBuddyGPT [![Discord](https://dcbadge.vercel.app/api/server/vr4PhSM8yN?style=flat&compact=true)](https://discord.gg/vr4PhSM8yN)</div>
1+
# <div class="vertical-align: middle"><img src="https://github.com/ipa-lab/hackingBuddyGPT/blob/main/docs/hackingbuddy-rounded.png?raw=true" width="72"> HackingBuddyGPT</div>
52

63
*Helping Ethical Hackers use LLMs in 50 Lines of Code or less..*
74

8-
[Read the Docs](https://docs.hackingbuddy.ai) | [Join us on discord!](https://discord.gg/vr4PhSM8yN)
9-
105
HackingBuddyGPT helps security researchers use LLMs to discover new attack vectors and save the world (or earn bug bounties) in 50 lines of code or less. In the long run, we hope to make the world a safer place by empowering security professionals to get more hacking done by using AI. The more testing they can do, the safer all of us will get.
116

127
**🆕 New Feature**: hackingBuddyGPT now supports both SSH connections to remote targets and local shell execution for easier testing and development!
@@ -45,11 +40,7 @@ hackingBuddyGPT is described in [Getting pwn'd by AI: Penetration Testing with L
4540
}
4641
~~~
4742

48-
## Getting help
49-
50-
If you need help or want to chat about using AI for security or education, please join our [discord server where we talk about all things AI + Offensive Security](https://discord.gg/vr4PhSM8yN)!
51-
52-
### Main Contributors
43+
## Main Contributors
5344

5445
The project originally started with [Andreas](https://github.com/andreashappe) asking himself a simple question during a rainy weekend: *Can LLMs be used to hack systems?* Initial results were promising (or disturbing, depends whom you ask) and led to the creation of our motley group of academics and professional pen-testers at TU Wien's [IPA-Lab](https://ipa-lab.github.io/).
5546

@@ -159,24 +150,28 @@ To run it, continue with the next section:
159150

160151
We try to keep our python dependencies as light as possible. This should allow for easier experimentation. To run the main priv-escalation program (which is called `wintermute`) together with an OpenAI-based model you need:
161152

162-
1. an OpenAI API account, you can find the needed keys [in your account page](https://platform.openai.com/account/api-keys)
153+
1. **Python 3.13 or newer.** The project builds with the [uv](https://docs.astral.sh/uv/) build backend, and we recommend using `uv` to manage the environment (a plain `python -m venv` + `pip` still works too).
154+
2. an OpenAI API account, you can find the needed keys [in your account page](https://platform.openai.com/account/api-keys)
163155
- please note that executing this script will call OpenAI and thus charges will occur to your account. Please keep track of those.
164-
2. a target environment to test against. You have two options:
156+
3. a target environment to test against. You have two options:
165157
- **Local Shell**: Use your local system (useful for testing and development)
166158
- **SSH Target**: A remote machine accessible over SSH. You can use a deliberately vulnerable machine such as [Lin.Security.1](https://www.vulnhub.com/entry/) or a security benchmark such as our [linux priv-esc benchmark](https://github.com/ipa-lab/benchmark-privesc-linux).
167159

168-
To get everything up and running, clone the repo, download requirements, setup API keys and credentials, and start `wintermute.py`:
160+
To get everything up and running, clone the repo, install the package, setup API keys and credentials, and start `wintermute`:
169161

170162
```bash
171163
# clone the repository
172164
$ git clone https://github.com/ipa-lab/hackingBuddyGPT.git
173165
$ cd hackingBuddyGPT
174166

175-
# setup virtual python environment
167+
# option A (recommended): let uv create the environment and install the project
168+
$ uv sync
169+
# prefix later commands with `uv run`, or activate the environment:
170+
$ source .venv/bin/activate
171+
172+
# option B: use a plain virtual environment + pip
176173
$ python -m venv venv
177174
$ source ./venv/bin/activate
178-
179-
# install python requirements
180175
$ pip install -e .
181176

182177
# copy default .env.example
@@ -188,49 +183,57 @@ $ cp .env.example.aws .env
188183
# IMPORTANT: setup your OpenAI API key, the VM's IP and credentials within .env
189184
$ vi .env
190185

191-
# if you start wintermute without parameters, it will list all available use cases
192-
$ python src/hackingBuddyGPT/cli/wintermute.py
186+
# installing the project provides the `wintermute` command; if you start it without
187+
# parameters, it will list all available use cases
188+
$ wintermute
193189
No command provided
194-
usage: src/hackingBuddyGPT/cli/wintermute.py <command> [--help] [--config config.json] [options...]
190+
usage: wintermute <command> [--help] [--config config.json] [options...]
195191

196192
commands:
197-
ExPrivEscLinux Showcase Minimal Linux Priv-Escalation
198-
ExPrivEscLinuxTemplated Showcase Minimal Linux Priv-Escalation
199-
LinuxPrivesc Linux Privilege Escalation
200-
WindowsPrivesc Windows Privilege Escalation
201-
ExPrivEscLinuxHintFile Linux Privilege Escalation using hints from a hint file initial guidance
202-
ExPrivEscLinuxLSE Linux Privilege Escalation using lse.sh for initial guidance
203-
WebTestingWithExplanation Minimal implementation of a web testing use case while allowing the llm to 'talk'
204-
SimpleWebAPIDocumentation Minimal implementation of a web API testing use case
205-
SimpleWebAPITesting Minimal implementation of a web API testing use case
206-
ThesisLinuxPrivescPrototype Thesis Linux Privilege Escalation Prototype
193+
AdvancedWebTesting Advanced of a web testing use case
194+
WebTestingWithExplanation Minimal implementation of a web testing use case while allowing the llm to 'talk'
195+
WebTestingWithShell Minimal implementation of a web testing use case with shell access
196+
SimpleWebAPIDocumentation Minimal implementation of a web API testing use case
197+
SimpleWebAPITesting Minimal implementation of a web API testing use case
198+
MinimalPrivEscLinux Minimal Strategy-based Linux Priv-Escalation
199+
PrivEscLinux Strategy-based Linux Priv-Escalation
200+
ExPrivEscLinuxLSE Linux Privilege Escalation using lse.sh for initial guidance
207201

208202
# to get more information about how to configure a use case you can call it with --help
209-
$ python src/hackingBuddyGPT/cli/wintermute.py LinuxPrivesc --help
210-
usage: src/hackingBuddyGPT/cli/wintermute.py LinuxPrivesc [--help] [--config config.json] [options...]
203+
$ wintermute PrivEscLinux --help
204+
usage: wintermute PrivEscLinux [--help] [--config config.json] [options...]
211205

212206
--log.log_dir='logs' directory for the per-run JSONL log files (default from builtin)
213207
--log.tag='' Tag for your current run (default from builtin)
214-
--max_turns='30' (default from .env file, alternatives: 10 from builtin)
215-
--llm.api_key=<secret> OpenAI API Key (default from .env file)
216-
--llm.model OpenAI model name
217-
--llm.context_size='100000' Maximum context size for the model, only used internally for things like trimming to the context size (default from .env file)
218-
--llm.api_url='https://api.openai.com' URL of the OpenAI API (default from builtin)
219-
--llm.api_path='/v1/chat/completions' Path to the OpenAI API (default from builtin)
220-
--llm.api_timeout=240 Timeout for the API request (default from builtin)
221-
--llm.api_backoff=60 Backoff time in seconds when running into rate-limits (default from builtin)
222-
--llm.api_retries=3 Number of retries when running into rate-limits (default from builtin)
223-
--system='linux' (default from builtin)
224-
--enable_explanation=False (default from builtin)
225-
--enable_update_state=False (default from builtin)
208+
--limits.max_rounds=100 Maximum number of rounds (0 is no limit) (default from builtin)
209+
--limits.max_tokens=0 Maximum number of tokens (input+output+thinking, 0 is no limit) (default from builtin)
210+
--limits.max_cost=10.0 Maximum cost in dollars (0 is no limit) (default from builtin)
211+
--limits.max_duration=0 Maximum duration of the run in seconds (0 is no limit) (default from builtin)
212+
--max_turns=10 (default from builtin)
213+
--llm.api_key API key for the upstream
214+
--llm.model model name in litellm format, e.g. 'gpt-4o' or 'openrouter/anthropic/claude-3.5-sonnet'
215+
--llm.context_size maximum context size of the model (used for prompt trimming)
216+
--llm.api_base='https://openrouter.ai/api' base URL of the API (default from builtin)
217+
--llm.api_timeout=60 timeout for a single request in seconds (default from builtin)
218+
--llm.api_retries=3 number of retries when running into rate-limits (default from builtin)
219+
--llm.provider='' OpenRouter provider routing, only useful when using OpenRouter, otherwise leave empty (default from builtin)
220+
--llm.proxy='' Proxy URL for the API calls (default from builtin)
221+
--llm.proxy_insecure=False Disable TLS certificate verification for the proxy (only for intercepting proxies like Burp/mitmproxy) (default from builtin)
226222
--disable_history=False (default from builtin)
227-
--hint='' (default from builtin)
223+
--enable_compressed_history=False (default from builtin)
228224
--conn.host
229-
--conn.hostname
230225
--conn.username
231226
--conn.password
232-
--conn.keyfilename
233-
--conn.port='2222' (default from .env file, alternatives: 22 from builtin)
227+
--conn.hostname='' (default from builtin)
228+
--conn.keyfilename='' (default from builtin)
229+
--conn.port=22 (default from builtin)
230+
--conn.banner='' (default from builtin)
231+
--hints='' (default from builtin)
232+
--enable_update_state=False (default from builtin)
233+
--enable_explanation=False (default from builtin)
234+
--enable_structured_guidance=False (default from builtin)
235+
--enable_cot=False (default from builtin)
236+
--rag_path='' (default from builtin)
234237
```
235238
236239
### Connection Options: Local Shell vs SSH
@@ -249,7 +252,7 @@ Use your local system for testing and development. This is useful for quick expe
249252
2. Once you have the tmux shell running, use hackingBuddyGPT to interact with it:
250253
```bash
251254
# Local shell with tmux session
252-
$ python src/hackingBuddyGPT/cli/wintermute.py LinuxPrivesc --conn=local_shell --conn.tmux_session=<session_name>
255+
$ wintermute PrivEscLinux --conn=local_shell --conn.tmux_session=<session_name>
253256
```
254257
255258
**Example:**
@@ -258,15 +261,15 @@ Use your local system for testing and development. This is useful for quick expe
258261
$ tmux new-session -s hacking_session
259262

260263
# Step 2: In another terminal, run hackingBuddyGPT
261-
$ python src/hackingBuddyGPT/cli/wintermute.py LinuxPrivesc --conn=local_shell --conn.tmux_session=hacking_session
264+
$ wintermute PrivEscLinux --conn=local_shell --conn.tmux_session=hacking_session
262265
```
263266
264267
#### SSH Mode
265268
Connect to a remote target machine over SSH. This is the traditional mode for testing against vulnerable VMs.
266269
267270
```bash
268271
# SSH connection (note the updated format with --conn=ssh)
269-
$ python src/hackingBuddyGPT/cli/wintermute.py LinuxPrivesc --conn=ssh --conn.host=192.168.122.151 --conn.username=lowpriv --conn.password=trustno1
272+
$ wintermute PrivEscLinux --conn=ssh --conn.host=192.168.122.151 --conn.username=lowpriv --conn.password=trustno1
270273
```
271274
272275
When using SSH mode, the target machine should be situated at your specified IP address (e.g., `192.168.122.151` in the example above).
@@ -322,13 +325,13 @@ With that out of the way, let's look at an example hackingBuddyGPT run. Each run
322325
# Example 1: Using local shell with tmux session
323326
# First create the tmux session: tmux new-session -s hacking_session
324327
# Then run hackingBuddyGPT:
325-
$ python src/hackingBuddyGPT/cli/wintermute.py LinuxPrivesc --llm.api_key=sk...ChangeMeToYourOpenAiApiKey --llm.model=gpt-4-turbo --llm.context_size=8192 --conn=local_shell --conn.tmux_session=hacking_session
328+
$ wintermute PrivEscLinux --llm.api_key=sk...ChangeMeToYourOpenAiApiKey --llm.model=gpt-4-turbo --llm.context_size=8192 --conn=local_shell --conn.tmux_session=hacking_session
326329
327330
# Example 2: Using SSH connection (updated format)
328-
$ python src/hackingBuddyGPT/cli/wintermute.py LinuxPrivesc --llm.api_key=sk...ChangeMeToYourOpenAiApiKey --llm.model=gpt-4-turbo --llm.context_size=8192 --conn=ssh --conn.host=192.168.122.151 --conn.username=lowpriv --conn.password=trustno1 --conn.hostname=test1
331+
$ wintermute PrivEscLinux --llm.api_key=sk...ChangeMeToYourOpenAiApiKey --llm.model=gpt-4-turbo --llm.context_size=8192 --conn=ssh --conn.host=192.168.122.151 --conn.username=lowpriv --conn.password=trustno1 --conn.hostname=test1
329332
330333
# install dependencies for testing if you want to run the tests
331-
$ pip install '.[testing]'
334+
$ uv sync --extra testing # or: pip install '.[testing]'
332335
```
333336
334337
## Publications about hackingBuddyGPT

0 commit comments

Comments
 (0)