From 40c627c4796037f18a742cd1ce48ae6530414812 Mon Sep 17 00:00:00 2001 From: hulto <7121375+hulto@users.noreply.github.com> Date: Tue, 30 Jan 2024 01:05:22 +0000 Subject: [PATCH 1/4] Docs updated. --- docs/_docs/user-guide/eldritch.md | 3 +- docs/_docs/user-guide/golem.md | 101 ++++++++++++++++++++++++++++++ 2 files changed, 103 insertions(+), 1 deletion(-) diff --git a/docs/_docs/user-guide/eldritch.md b/docs/_docs/user-guide/eldritch.md index 6ad9cb7b5..0fc3e5bb4 100644 --- a/docs/_docs/user-guide/eldritch.md +++ b/docs/_docs/user-guide/eldritch.md @@ -14,6 +14,8 @@ By embedding the interpreter into the agent conditional logic can be quickly eva Eldritch is currently under active development to help delineate methods in development the description contains the phrase `X method will`. +**Trying to create a new tome check out the guide in [Golem](/user-guide/golem)** + ## Examples _Kill a specific process name_ @@ -91,7 +93,6 @@ It currently contains seven modules: - `sys` - General system capabilities can include loading libraries, or information about the current context. - `time` - General functions for obtaining and formatting time, also add delays into code. - Functions fall into one of these seven modules. This is done to improve clarity about function use. **🚨 DANGER 🚨: Name shadowing** diff --git a/docs/_docs/user-guide/golem.md b/docs/_docs/user-guide/golem.md index ebd29f1c4..12eec7055 100644 --- a/docs/_docs/user-guide/golem.md +++ b/docs/_docs/user-guide/golem.md @@ -24,6 +24,107 @@ cargo build --release && \ ../target/debug/golem ../../tests/golem_cli_test/tomes/hello_world.tome ``` +## Creating and testing tomes + +Golem is a great way to create and test tomes without deploying the entire Realm project. +Golem operates in three different modes: + +- Interactive `-i` +- With embedded tomes _no args_ +- On a specific tome `/path/to/tome/eldritch.main` + +In this guide we'll leverage the last one. + +### Tome structure + +Copy an existing tome and rename it to your desired name. + +```bash +[~/realm]$ cd tavern/tomes/ +[./tomes]$ cp -r ./file_list ./new_tome +``` + +This will setup the boiler plate. +A tome file structure should look like this: + +``` +./new_tome/ +├── files +│ └── test-file +├── main.eldritch +└── metadata.yml +``` + +_If you have no files associated with your tome you can ommit the `files` dir_ + +- main.eldritch - Defines our actual eldritch functionality and what will be executed on the agent. +- metadata.yaml - Defines information that tavern will use to prepare your tome including prompting users for input. + +### Tome Metadata + +Your tome Metadata should look like this: + +```yaml +name: List files # The name of your tome. +description: List the files and directories found at the path # A description to help users understand what your tome does. +author: hulto # Your Github username. +support_model: FIRST_PARTY # Is this a tome that ships with Realm or not? +tactic: RECON # What stage of the MITRE ATT&CK chain does this tome fall into? +paramdefs: # A list of inputs the tome requires. +- name: path # The name of the input parameter `input_params['path']`. + type: string # The type of the input parameter. + label: File path # A Label that will be displayed in the UI to help users understand the purpose. + placeholder: "/etc/" # A placeholder to give users an idea of how their input should be formatted. +``` + +### Building your eldritch script + +Eldritch while it looks like python is distinct and many features in python do not exist in Eldritch. + +For an almost complete list of syntax checkout the starlark (DSL which eldritch is based on) docs +*Note: The docs may be incorrect in some places as we're using the starlark-rust implementation which doesn't always adhere to the starlark spec.* + +```python +# Define our function for the tome and any inputs +def file_list(path): + # make sure you proactively check the state of the system. + # Users may pass bad data in or the system may be in an + # unexpected state so always check if something is a dir + # before treatingi it like one. + if file.is_dir(path): + files = file.list(path) + for f in files: + type_str = "" + if f['type'] == "Directory": + type_str = "Dir" + if f['type'] == "Link": + type_str = "Link" + if f['type'] == "File": + type_str = "File" + # Formatting - By default eldritch will print data as a JSON Dictionary which is easy for scripts to read but + # not great for humans to make your tome more usable make sure you print data in a readable way. + print(f['permissions']+"\t"+f['owner']+"\t"+f['group']+"\t"+str(f['size'])+"\t"+f['modified']+"\t"+type_str+"\t"+f['file_name']+"\n") + else: + print("Error: Invalid Path ("+path+")\n") + +# Call our tomes function. +file_list(input_params['path']) +# `input_params` is a dictionary that's implicitly passed into the eldritch runtime. +# The key value pairs in input_params is defined by the users answers to the paramdefs in the UI. +# For example if you specify `name: path` in your `metadata.yml` file the UI will ask the user for +# a path and then populate the `path` key in `input_params` when the tome runs. +# Input params is unique to each task so setting a var in one task won't affect others. +print("\n") +print("\n") +``` + +### Design ideology + +Tomes are designed to accomplish specific workflows. +Some small tomes have been created to accomplish basic sysadmin tasks like reading, writing files, checking processes etc. +Ideally though if you have a specific workflow you'll define it as a tome. +We want to avoid queueing multiple questst to accomplish a workflow. + ## Golem embedded files The Eldritch interpreter can embed files at compile time. To interact with these assets use the `assets` module in eldritch. In addition to programmatic access the embedded files can be automatically executed at run time. If no other option is specified `-i` or a file path, golem will iterate over every instance of `main.eldritch` in the embedded assets launching each one as a separate thread. This behavior is desirable when trying to perform recon or deploy persistence quickly. From 7801696c7097ced43a9d1a38e6500dededa5a5fe Mon Sep 17 00:00:00 2001 From: hulto <7121375+hulto@users.noreply.github.com> Date: Tue, 30 Jan 2024 01:05:27 +0000 Subject: [PATCH 2/4] Docs updated. --- docs/_docs/user-guide/golem.md | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) diff --git a/docs/_docs/user-guide/golem.md b/docs/_docs/user-guide/golem.md index 12eec7055..4b8ea3053 100644 --- a/docs/_docs/user-guide/golem.md +++ b/docs/_docs/user-guide/golem.md @@ -125,6 +125,25 @@ Some small tomes have been created to accomplish basic sysadmin tasks like readi Ideally though if you have a specific workflow you'll define it as a tome. We want to avoid queueing multiple questst to accomplish a workflow. +### Testing your tome + +Now that your tome is created lets test it locally. + +```bash +[~]$ cd realm/implants/golem +[./golem]$ cargo run -- ~/realm/tavern/tomes/new_tome/main.eldritch +# ... +# Tome output +# ... +``` + +_If you have input_params that you need to define for your tome manually set them for your test by adding a line like this:_ + +```python +input_params['path'] = "/tmp/" +file_list(input_params['path']) +``` + ## Golem embedded files The Eldritch interpreter can embed files at compile time. To interact with these assets use the `assets` module in eldritch. In addition to programmatic access the embedded files can be automatically executed at run time. If no other option is specified `-i` or a file path, golem will iterate over every instance of `main.eldritch` in the embedded assets launching each one as a separate thread. This behavior is desirable when trying to perform recon or deploy persistence quickly. From 1117520b62e0d9bde63d327b36038cac509e7449 Mon Sep 17 00:00:00 2001 From: hulto <7121375+hulto@users.noreply.github.com> Date: Tue, 30 Jan 2024 01:18:47 +0000 Subject: [PATCH 3/4] Resolve nits. --- docs/_docs/user-guide/golem.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/_docs/user-guide/golem.md b/docs/_docs/user-guide/golem.md index 4b8ea3053..2c0818dd6 100644 --- a/docs/_docs/user-guide/golem.md +++ b/docs/_docs/user-guide/golem.md @@ -123,11 +123,11 @@ print("\n") Tomes are designed to accomplish specific workflows. Some small tomes have been created to accomplish basic sysadmin tasks like reading, writing files, checking processes etc. Ideally though if you have a specific workflow you'll define it as a tome. -We want to avoid queueing multiple questst to accomplish a workflow. +We want to avoid queueing multiple quests to accomplish a workflow. ### Testing your tome -Now that your tome is created lets test it locally. +Now that your tome is created let's test it locally. ```bash [~]$ cd realm/implants/golem From fa2a9f69eb7537e869fea49684c4b5f6b42e823b Mon Sep 17 00:00:00 2001 From: hulto <7121375+hulto@users.noreply.github.com> Date: Tue, 30 Jan 2024 01:43:12 +0000 Subject: [PATCH 4/4] Resolve feedback. --- docs/_docs/user-guide/eldritch.md | 2 +- docs/_docs/user-guide/golem.md | 16 ++++++++-------- 2 files changed, 9 insertions(+), 9 deletions(-) diff --git a/docs/_docs/user-guide/eldritch.md b/docs/_docs/user-guide/eldritch.md index 0fc3e5bb4..09c80f00c 100644 --- a/docs/_docs/user-guide/eldritch.md +++ b/docs/_docs/user-guide/eldritch.md @@ -14,7 +14,7 @@ By embedding the interpreter into the agent conditional logic can be quickly eva Eldritch is currently under active development to help delineate methods in development the description contains the phrase `X method will`. -**Trying to create a new tome check out the guide in [Golem](/user-guide/golem)** +**Trying to create a tome? Check out the guide in [Golem](/user-guide/golem).** ## Examples diff --git a/docs/_docs/user-guide/golem.md b/docs/_docs/user-guide/golem.md index 2c0818dd6..5cdcb6fda 100644 --- a/docs/_docs/user-guide/golem.md +++ b/docs/_docs/user-guide/golem.md @@ -26,7 +26,7 @@ cargo build --release && \ ## Creating and testing tomes -Golem is a great way to create and test tomes without deploying the entire Realm project. +Golem is a great way to quickly develop and iterate tomes without needing to deploy an agent and wait for callbacks. It enables a more interactive experience for Eldritch, which helps tome developers move quickly. Golem operates in three different modes: - Interactive `-i` @@ -57,7 +57,7 @@ A tome file structure should look like this: _If you have no files associated with your tome you can ommit the `files` dir_ -- main.eldritch - Defines our actual eldritch functionality and what will be executed on the agent. +- main.eldritch - Defines our actual Eldritch functionality and what will be executed on the agent. - metadata.yaml - Defines information that tavern will use to prepare your tome including prompting users for input. ### Tome Metadata @@ -69,7 +69,7 @@ name: List files # The name of your tome. description: List the files and directories found at the path # A description to help users understand what your tome does. author: hulto # Your Github username. support_model: FIRST_PARTY # Is this a tome that ships with Realm or not? -tactic: RECON # What stage of the MITRE ATT&CK chain does this tome fall into? +tactic: RECON # Which MTIRE ATT&CK Tactic best describes this tome? paramdefs: # A list of inputs the tome requires. - name: path # The name of the input parameter `input_params['path']`. type: string # The type of the input parameter. @@ -77,11 +77,11 @@ paramdefs: # A list of inputs the tome requires. placeholder: "/etc/" # A placeholder to give users an idea of how their input should be formatted. ``` -### Building your eldritch script +### Building your Eldritch script Eldritch while it looks like python is distinct and many features in python do not exist in Eldritch. -For an almost complete list of syntax checkout the starlark (DSL which eldritch is based on) docs +For an almost complete list of syntax checkout the starlark (DSL which Eldritch is based on) docs *Note: The docs may be incorrect in some places as we're using the starlark-rust implementation which doesn't always adhere to the starlark spec.* ```python @@ -101,7 +101,7 @@ def file_list(path): type_str = "Link" if f['type'] == "File": type_str = "File" - # Formatting - By default eldritch will print data as a JSON Dictionary which is easy for scripts to read but + # Formatting - By default Eldritch will print data as a JSON Dictionary which is easy for scripts to read but # not great for humans to make your tome more usable make sure you print data in a readable way. print(f['permissions']+"\t"+f['owner']+"\t"+f['group']+"\t"+str(f['size'])+"\t"+f['modified']+"\t"+type_str+"\t"+f['file_name']+"\n") else: @@ -109,7 +109,7 @@ def file_list(path): # Call our tomes function. file_list(input_params['path']) -# `input_params` is a dictionary that's implicitly passed into the eldritch runtime. +# `input_params` is a dictionary that's implicitly passed into the Eldritch runtime. # The key value pairs in input_params is defined by the users answers to the paramdefs in the UI. # For example if you specify `name: path` in your `metadata.yml` file the UI will ask the user for # a path and then populate the `path` key in `input_params` when the tome runs. @@ -146,7 +146,7 @@ file_list(input_params['path']) ## Golem embedded files -The Eldritch interpreter can embed files at compile time. To interact with these assets use the `assets` module in eldritch. In addition to programmatic access the embedded files can be automatically executed at run time. If no other option is specified `-i` or a file path, golem will iterate over every instance of `main.eldritch` in the embedded assets launching each one as a separate thread. This behavior is desirable when trying to perform recon or deploy persistence quickly. +The Eldritch interpreter can embed files at compile time. To interact with these assets use the `assets` module in Eldritch. In addition to programmatic access the embedded files can be automatically executed at run time. If no other option is specified `-i` or a file path, golem will iterate over every instance of `main.eldritch` in the embedded assets launching each one as a separate thread. This behavior is desirable when trying to perform recon or deploy persistence quickly. ## Golem as a stage 0