restructure documentation a bit

Author: andreashappe

src/app/docs/core-concepts/executables/page.md

@@ -0,0 +1,63 @@
+---
+title: Executables
+nextjs:
+  metadata:
+    title: Executables
+    description: 'HackingBuddyGPT: how to execute?'
+---
+
+When it comes to executables, the most important tool is `wintermute.py`. This python program identifies all implemented use-cases/agents and their respective configuration options, and allows end-users to configure and start an use-case/agent.
+
+The following `wintermute` output lists all currently available use-cases (`linux_privesc_hintfile`, `linux_privesc_guided`, `linux_privesc`, `windows_privesc`, `minimal_linux_privesc`, `simple_web_test`):
+
+```bash
+$ python wintermute.py 
+usage: wintermute.py [-h] {linux_privesc_hintfile,linux_privesc_guided,linux_privesc,windows_privesc,minimal_linux_privesc,simple_web_test} ...
+wintermute.py: error: the following arguments are required: {linux_privesc_hintfile,linux_privesc_guided,linux_privesc,windows_privesc,minimal_linux_privesc,simple_web_test}
+```
+
+When called with a concrete use-case and the `--help` option, all available configuration options for the given use-case are shown:
+
+```bash
+$python wintermute.py linux_privesc_hintfile --help
+usage: wintermute.py linux_privesc_hintfile [-h] [--conn.host CONN.HOST] [--conn.hostname CONN.HOSTNAME] [--conn.username CONN.USERNAME] [--conn.password CONN.PASSWORD]
+                                            [--conn.port CONN.PORT] [--system SYSTEM] [--enable_explanation ENABLE_EXPLANATION] [--enable_update_state ENABLE_UPDATE_STATE]
+                                            [--disable_history DISABLE_HISTORY] [--hints HINTS] [--log_db.connection_string LOG_DB.CONNECTION_STRING] [--llm.api_key LLM.API_KEY]
+                                            [--llm.model LLM.MODEL] [--llm.context_size LLM.CONTEXT_SIZE] [--llm.api_url LLM.API_URL] [--llm.api_timeout LLM.API_TIMEOUT]
+                                            [--llm.api_backoff LLM.API_BACKOFF] [--llm.api_retries LLM.API_RETRIES] [--tag TAG] [--max_turns MAX_TURNS]
+
+options:
+  -h, --help            show this help message and exit
+  --conn.host CONN.HOST
+  --conn.hostname CONN.HOSTNAME
+  --conn.username CONN.USERNAME
+  --conn.password CONN.PASSWORD
+  --conn.port CONN.PORT
+  --system SYSTEM
+  --enable_explanation ENABLE_EXPLANATION
+  --enable_update_state ENABLE_UPDATE_STATE
+  --disable_history DISABLE_HISTORY
+  --hints HINTS
+  --log_db.connection_string LOG_DB.CONNECTION_STRING
+                        sqlite3 database connection string for logs
+  --llm.api_key LLM.API_KEY
+                        OpenAI API Key
+  --llm.model LLM.MODEL
+                        OpenAI model name
+  --llm.context_size LLM.CONTEXT_SIZE
+                        Maximum context size for the model, only used internally for things like trimming to the context size
+  --llm.api_url LLM.API_URL
+                        URL of the OpenAI API
+  --llm.api_timeout LLM.API_TIMEOUT
+                        Timeout for the API request
+  --llm.api_backoff LLM.API_BACKOFF
+                        Backoff time in seconds when running into rate-limits
+  --llm.api_retries LLM.API_RETRIES
+                        Number of retries when running into rate-limits
+  --tag TAG
+  --max_turns MAX_TURNS
+```
+
+Finally you can execute a use-case by calling it through `wintermute.py`. Configuration for the use-case will be initially be populated from an `.env` file. If any command line arguments are given, these over-write configuration options read form configuration files.
+
+We provide scripts for later analysis of use-cases/agent runs, e.g., `stats.py` and `viewer.py`, but we will extend and move them into a dedicated analysis-scripts directory soon.

src/app/docs/core-concepts/project-layout/page.md

@@ -3,73 +3,35 @@ title: Project Layout
 nextjs:
   metadata:
     title: Project Layout
-    description: On this page we'll give you a high-level overview of our project's structure.
+    description: 'HackingBuddyGPT: High-Level Overview'
 ---
 
-hackingBuddyGPT uses a simple project structure to make onboarding of new developers easier.
+After you checked out the project's source [from github](https://github.com/ipa-lab/hackingBuddyGPT) you might wonder where all the juicy bits are.
 
-## Source Code and Components
+Let's do a quick overview before we delve deeper into our components.
 
-The project's source code is roughly structured into three directories:
+Broadly speaking, we have separated our code base into three concerns:
 
-- `usecases`: use-case (often also named agents) describe one pen-testing strategy. For example, you might want to write an use-case for hacking a linux system, or write an use-case to hack a web-site. Typically you call an use-case through our command line tool (`wintermute.py`) and pass the target information, e.g., the to be tested website, also through command line parameters.
+1. The Hacking 'Use-Cases' which are python classes describing how our hacking automatons should work.
+2. Capabilities (or in simpler terms, 'actions') that describe how our hacking automatons can interact with the outside world.
+3. Helpers in 'utils' that are reused between the different hacking use-cases, e.g., output or database helpers.
 
-- `capabilities`: use-case/agents needs to interact with the real world (otherwise hacking would be a bit boring) and they do this through capabilities. We intend for capabilities to be shared between multiple use-cases so that new use-cases can be developed rapidly. Examples for capabilities are executing a system command over SSH, test for credentials, or executing a HTTP request.
+## Source Code and Components
 
-- `utils`: this project area includes helper infrastructure for operating the use-cases/agents. For example, this section includes a general OpenAI connector that abstracts away most of the tedious bits of creating a connection to an LLM API.
+Our project structure roughly mirrors the just mentioned three concerns:
 
-## Executable files
+- [`usecases/`](/docs/core-concepts/use-cases): within this directory are all out implemented 'use-cases' (or hacking automatons). We use subdirectories for additional structure, e.g., all local privilege escalation automatons are located in `usecases/privesc/`.
 
-When it comes to executables, the most important tool is `wintermute.py`. This python program identifies all implemented use-cases/agents and their respective configuration options, and allows end-users to configure and start an use-case/agent.
+  To prevent code-duplication we provide additional base-classes such as `Agent` which implement use-cases that contain capabilities (see next section) as well as a maximum round limit (so that the automaton will not run forever and thus use up lots of credits).
 
-The following output shows how `wintermute.py` lists all available use-cases (`linux_privesc_hintfile`, `linux_privesc_guided`, `linux_privesc`, `windows_privesc`, `minimal_linux_privesc`, `simple_web_test`) when called without parameters:
+  Once you implement a custom use-case, you can configure and start it through [wintermute.py](/docs/core-concepts/executables).
 
-```bash
-$ python wintermute.py 
-usage: wintermute.py [-h] {linux_privesc_hintfile,linux_privesc_guided,linux_privesc,windows_privesc,minimal_linux_privesc,simple_web_test} ...
-wintermute.py: error: the following arguments are required: {linux_privesc_hintfile,linux_privesc_guided,linux_privesc,windows_privesc,minimal_linux_privesc,simple_web_test}
-```
+- [`capabilities/`](/docs/core-concepts/capabilities): our automatons need to interact with the real world (otherwise hacking would be a bit boring) and they do this through capabilities.
 
-When called with a concrete use-case and passed the `--help` option, all available configuration options for the given use-case are shown:
+  Examples for capabilities are executing a system command over SSH, test for credentials, or executing a HTTP request.
 
-```bash
-$python wintermute.py linux_privesc_hintfile --help
-usage: wintermute.py linux_privesc_hintfile [-h] [--conn.host CONN.HOST] [--conn.hostname CONN.HOSTNAME] [--conn.username CONN.USERNAME] [--conn.password CONN.PASSWORD]
-                                            [--conn.port CONN.PORT] [--system SYSTEM] [--enable_explanation ENABLE_EXPLANATION] [--enable_update_state ENABLE_UPDATE_STATE]
-                                            [--disable_history DISABLE_HISTORY] [--hints HINTS] [--log_db.connection_string LOG_DB.CONNECTION_STRING] [--llm.api_key LLM.API_KEY]
-                                            [--llm.model LLM.MODEL] [--llm.context_size LLM.CONTEXT_SIZE] [--llm.api_url LLM.API_URL] [--llm.api_timeout LLM.API_TIMEOUT]
-                                            [--llm.api_backoff LLM.API_BACKOFF] [--llm.api_retries LLM.API_RETRIES] [--tag TAG] [--max_turns MAX_TURNS]
+  To prevent code duplications capabilities can easily be shared between multiple usecases.
 
-options:
-  -h, --help            show this help message and exit
-  --conn.host CONN.HOST
-  --conn.hostname CONN.HOSTNAME
-  --conn.username CONN.USERNAME
-  --conn.password CONN.PASSWORD
-  --conn.port CONN.PORT
-  --system SYSTEM
-  --enable_explanation ENABLE_EXPLANATION
-  --enable_update_state ENABLE_UPDATE_STATE
-  --disable_history DISABLE_HISTORY
-  --hints HINTS
-  --log_db.connection_string LOG_DB.CONNECTION_STRING
-                        sqlite3 database connection string for logs
-  --llm.api_key LLM.API_KEY
-                        OpenAI API Key
-  --llm.model LLM.MODEL
-                        OpenAI model name
-  --llm.context_size LLM.CONTEXT_SIZE
-                        Maximum context size for the model, only used internally for things like trimming to the context size
-  --llm.api_url LLM.API_URL
-                        URL of the OpenAI API
-  --llm.api_timeout LLM.API_TIMEOUT
-                        Timeout for the API request
-  --llm.api_backoff LLM.API_BACKOFF
-                        Backoff time in seconds when running into rate-limits
-  --llm.api_retries LLM.API_RETRIES
-                        Number of retries when running into rate-limits
-  --tag TAG
-  --max_turns MAX_TURNS
-```
+- `utils/`: this area includes helper infrastructure that are re-used for all automatons and use-cases. For example, this section includes a general OpenAI connector that abstracts away most of the tedious bits of creating a connection to an LLM API.
 
-We provide scripts for later analysis of use-cases/agent runs, e.g., `stats.py` and `viewer.py`, but we will extend and move them into a dedicated analysis-scripts directory soon.
+  To highlight the difference between 'utils' and 'capabilities': capabilities are actions that can be called from LLMs, while utils include common functionality that is often used from within the different use-cases' source code.

src/app/docs/core-concepts/python-infrastructure/page.md

@@ -3,34 +3,13 @@ title: Python Infrastructure and used Technology
 nextjs:
   metadata:
     title: Python Infrastructure and used Technology
-    description: Quidem magni aut exercitationem maxime rerum eos.
+    description: 'HackingBuddyGPT: What technology are we depending upon?'
 ---
 
 We try to base our software on modern python libraries and techniques and want to highlight some of those here.
 
-## Quis vel iste dicta
+Things you will encounter within our source code:
 
-Sit commodi iste iure molestias qui amet voluptatem sed quaerat. Nostrum aut pariatur. Sint ipsa praesentium dolor error cumque velit tenetur.
-
-### Et pariatur ab quas
-
-Sit commodi iste iure molestias qui amet voluptatem sed quaerat. Nostrum aut pariatur. Sint ipsa praesentium dolor error cumque velit tenetur quaerat exercitationem. Consequatur et cum atque mollitia qui quia necessitatibus.
-
-```js
-/** @type {import('@tailwindlabs/lorem').ipsum} */
-export default {
-  lorem: 'ipsum',
-  dolor: ['sit', 'amet', 'consectetur'],
-  adipiscing: {
-    elit: true,
-  },
-}
-```
-
-Possimus saepe veritatis sint nobis et quam eos. Architecto consequatur odit perferendis fuga eveniet possimus rerum cumque. Ea deleniti voluptatum deserunt voluptatibus ut non iste. Provident nam asperiores vel laboriosam omnis ducimus enim nesciunt quaerat. Minus tempora cupiditate est quod.
-
-### Natus aspernatur iste
-
-Sit commodi iste iure molestias qui amet voluptatem sed quaerat. Nostrum aut pariatur. Sint ipsa praesentium dolor error cumque velit tenetur quaerat exercitationem. Consequatur et cum atque mollitia qui quia necessitatibus.
-
-Voluptas beatae omnis omnis voluptas. Cum architecto ab sit ad eaque quas quia distinctio. Molestiae aperiam qui quis deleniti soluta quia qui. Dolores nostrum blanditiis libero optio id. Mollitia ad et asperiores quas saepe alias.
+- [Python Type Hints](https://docs.python.org/3/library/typing.html)
+- [Pydantic Mdoels](https://docs.pydantic.dev/latest/)
+- [abc -- Abstract Base Classes](https://docs.python.org/3/library/abc.html)

src/app/docs/core-concepts/use-cases/page.md

@@ -1,9 +1,9 @@
 ---
-title: Use-Cases
+title: Use-Cases and Agents
 nextjs:
   metadata:
-    title: Use-Cases
-    description: Quidem magni aut exercitationem maxime rerum eos.
+    title: Use-Cases and Agents
+    description: 'HackingBuddyGPT: Use-Case and Agent Infrastructure'
 ---
 
 Wintermute consists of different use-cases (classes extending `UseCase`, being annotated with `@use_case` and being imported somewhere from the main `wintermute.py` file), which can be run individually.

src/app/docs/core-concepts/configuration-magic/page.md renamed to src/app/docs/dev-guide/configuration-magic/page.md

@@ -3,7 +3,7 @@ title: How to Contribute?
 nextjs:
   metadata:
     title: How to Contribute?
-    description: 'You want to contribute to HackingBuddyGPT? Please do (:'
+    description: 'HackingBuddyGPT: You want to contribute to HackingBuddyGPT? Please do (:'
 ---
 
 So you want to contribute to hackingBuddyGPT? First of all, thank you! Second of all, how to best continue?
@@ -12,6 +12,6 @@ So you want to contribute to hackingBuddyGPT? First of all, thank you! Second of
 2. Maybe check the [list of open issues](https://github.com/ipa-lab/hackingBuddyGPT/issues), some of them are tagged as `good first issue` even
 3. fork the projects
 4. have fun and work on the issue (or your new hacking agent)
-5. create a pull request to contribute the code back to hackingBuddyGPT
+5. [create a pull request](https://github.com/ipa-lab/hackingBuddyGPT/pulls) to contribute the code back to hackingBuddyGPT
 6. get your code reviewed and maybe improvments suggested by a maintainer
 7. Fame and Profit!

src/app/docs/introduction/how-to-contribute/page.md

@@ -16,7 +16,7 @@ export const navigation = [
       { title: 'Python Infrastructure', href: '/docs/core-concepts/python-infrastructure' },
       { title: 'Use-Cases and Agents', href: '/docs/core-concepts/use-cases', },
       { title: 'Capabilities: Adding Actions', href: '/docs/core-concepts/capabilities', },
-      { title: 'Configuration Magic', href: '/docs/core-concepts/configuration-magic' },
+      { title: 'Executables', href: '/docs/core-concepts/executables', },
     ],
   },
   {
@@ -33,6 +33,7 @@ export const navigation = [
     title: 'Developer Guide',
     links: [
       { title: 'Quickstart', href: '/docs/dev-guide/dev-quickstart' },
+      { title: 'Configuration Magic', href: '/docs/dev-guide/configuration-magic' },
       { title: 'Using Usecases from Agents', href: '/docs/dev-guide/including-use-cases' },
       { title: 'Multiple LLMs within an Agent', href: '/docs/dev-guide/using-multiple-llms' },
     ],