diff --git a/docs/_docs/dev-guide/eldritch.md b/docs/_docs/dev-guide/eldritch.md index bc0585eed..85464303c 100644 --- a/docs/_docs/dev-guide/eldritch.md +++ b/docs/_docs/dev-guide/eldritch.md @@ -186,7 +186,7 @@ Limit changes to the implementation file. OS specific restrictions should be done in the **Eldritch Implementation** you should only have to worry about it in your: `function_impl.rs`. This ensures that all functions are exposed in every version of the Eldritch language. -To prevent errors and compiler warnings use the `#[cfg(target_os = "windows")]` conditional compiler flag to supress OS specific code. +To prevent errors and compiler warnings use the `#[cfg(target_os = "windows")]` conditional compiler flag to suppress OS specific code. For all non supported OSes return an error with a message explaining which OSes are supported. **Example** ```rust @@ -198,7 +198,7 @@ For all non supported OSes return an error with a message explaining which OSes --- The `Dict` type requires dynamic memory allocation in starlark. In order to achieve this we can leverage the `starlark::Heap` and push entries onto it. It's pretty simple to implement and starlark does some magic to streamline the process. To make the heap available to your function simply add it as an argument to your function. -## Different function declerations +## Different function decelerations `implants/lib/eldritch/src/module.rs` ```rust @@ -207,11 +207,11 @@ The `Dict` type requires dynamic memory allocation in starlark. In order to achi `implants/lib/eldritch/src/module/function_impl.rs` ```rust -pub fn function(starlark_heap: &Heap) -> Result { +pub fn function(starlark_heap: &Heap, arg1: String, arg2: u8, arg3: Vec) -> Result { ``` ## Split starlark boilerplate and function implementation -One note is when working with starlark `Dict` types it preferedd that a `handle_` function be implemented which returns a real data type and that data type is translated from the rust data type to starlark `Dict` in the `function` for example: +One note is when working with starlark `Dict` types it preferred that a `handle_` function be implemented which returns a real data type and that data type is translated from the rust data type to starlark `Dict` in the `function` for example: ```rust struct OsInfo { @@ -328,7 +328,9 @@ pub fn function(arg1: Vec) -> Result> { ### Testing async code requires some additional work You'll need to write tests for your synchronous and asynchronous code. -Async tests will start +Async tests will usually start two threads one for your function and one that mocks (or reimplements) the feature you're testing against. +For example if testing a port scanner or netcat like function you'll want to run a test port listener for your feature to connect to. +Network ports test servers have been implemented in `pivot.ncat` and `pivot.port_scan` an example SSH server has been implemented in `pivot.ssh_exec`. Tests for async functions may look like this: ```rust diff --git a/docs/_docs/dev-guide/introduction.md b/docs/_docs/dev-guide/introduction.md index a534a9b1b..c5e592483 100644 --- a/docs/_docs/dev-guide/introduction.md +++ b/docs/_docs/dev-guide/introduction.md @@ -17,11 +17,11 @@ We will do our best during code review to catch changes that require documentati ### Testing -Realm contains code across a variety of languages and frameworks. Testing helps ensure our codebase remains stable, enables us to refactor and develop new features with confidence, and can help new Realm developers understand the expected behaviour of our code. Below is an outline of the testing requirements for each portion of the codebase, as well as guidance on testing best practices. +Realm contains code across a variety of languages and frameworks. Testing helps ensure our codebase remains stable, enables us to refactor and develop new features with confidence, and can help new Realm developers understand the expected behavior of our code. Below is an outline of the testing requirements for each portion of the codebase, as well as guidance on testing best practices. #### Eldritch -Any methods added to the Eldritch Standard Library should have tests colocated in the method's `_impl.rs` file. Here are a few things to keep in mind: +Any methods added to the Eldritch Standard Library should have tests collocated in the method's `_impl.rs` file. Here are a few things to keep in mind: * Tests should be cross platform * Rely on [NamedTempFile](https://docs.rs/tempfile/1.1.1/tempfile/struct.NamedTempFile.html) for temporary files * Rely on [path.join](https://doc.rust-lang.org/stable/std/path/struct.Path.html) to construct OS-agnostic paths @@ -34,7 +34,7 @@ All code changes to Tavern must be tested. Below are some standards for test wri * Conventionally, please colocate your test code with the code it is testing and include it in the `_test` package * We rely on the standard [testify](https://github.com/stretchr/testify) assert & require libraries for ensuring expected values (or errors) are returned * To enable a variety of inputs for a test case, we rely on closure-driven testing for Golang, you can read more about it [here](https://medium.com/@cep21/closure-driven-tests-an-alternative-style-to-table-driven-tests-in-go-628a41497e5e) -* Reuseable test code should go in a subpackage suffixed with test +* Reuseable test code should go in a sub-package suffixed with test * For example, reuseable test code for the `ent` package would be located in the `ent/enttest` package * This convention is even used in the Golang standard library (e.g. [net/http](https://pkg.go.dev/net/http/httptest)) * Please use existing tests as a reference for writing new tests @@ -48,7 +48,7 @@ In an attempt to reduce the complexity of merges, we enforce a linear history fo # Terminology -Throughout the documentation terms like "agent" or "implant" are used to refrence various components (or types of components) in our codebase. Below we attempt to define some of those terms, to add some clarity to that other documentation. +Throughout the documentation terms like "agent" or "implant" are used to reference various components (or types of components) in our codebase. Below we attempt to define some of those terms, to add some clarity to that other documentation. ### Target A Target is a system that is in-scope for the current engagement. It is used to establish a logical boundary between different systems in an engagement (e.g. between a webserver and a database). This enables operations to _target_ a particular system, for example you may want to list files on a web server in your engagement scope. @@ -57,19 +57,22 @@ A Target is a system that is in-scope for the current engagement. It is used to A Task represents a set of instructions to perform on a Target system. For example, listing files could be a Task. When listing files across various Targets, one Task per Target will be created for tracking the individual execution output. ### Implant -References malicious code or persistence mechanisms that are deployed to compromise target systems. Some configration information for Implants (e.g. `ImplantConfigs`) can be managed through Tavern. +References malicious code or persistence mechanisms that are deployed to compromise target systems. Some configuration information for Implants (e.g. `ImplantConfigs`) can be managed through Tavern. ### Agent -An Agent is a type of implant which retrieves execution instructons by connecting to our backend infrastructure (calling back) and querying for new tasks. +An Agent is a type of implant which retrieves execution instructions by connecting to our backend infrastructure (calling back) and querying for new tasks. # Project Structure * **[.devcontainer](https://github.com/KCarretto/realm/tree/main/.devcontainer)** contains settings required for configuring a VSCode dev container that can be used for Realm development * **[.github](https://github.com/KCarretto/realm/tree/main/.github)** contains GitHub related actions, issue templates, etc +* **[docker](https://github.com/KCarretto/realm/tree/main/docker)** docker containers for production builds * **[docs](https://github.com/KCarretto/realm/tree/main/docs)** contains the Jekyll code for the documentation site that you're reading now! * **[implants](https://github.com/KCarretto/realm/tree/main/implants)** is the parent folder of any implant executables or libraries - * **[implants/contrib](https://github.com/KCarretto/realm/tree/main/implants/contrib)** contains example information which might be useful to project contributors - * **[implants/eldritch](https://github.com/KCarretto/realm/tree/main/implants/eldritch)** is the source of our eldritch library (Rust) + * **[implants/golem](https://github.com/KCarretto/realm/tree/main/implants/golem)** the stand-alone interpreter that implements the eldritch language (Rust) + * **[implants/golem/embed_files_golem_prod](https://github.com/KCarretto/realm/tree/main/implants/golem/embed_files_golem_prod)** Files and scripts that will be embedded into production builds of imix, golem, and eldritch. These files can be accessed through the [`assets` module.](https://docs.realm.pub/user-guide/eldritch#assets) * **[implants/imix](https://github.com/KCarretto/realm/tree/main/implants/imix)** is our agent that executes eldritch tomes (Rust) + * **[implants/lib/eldritch](https://github.com/KCarretto/realm/tree/main/implants/lib/eldritch)** is the source of our eldritch library (Rust) + * **[implants/lib/tavern](https://github.com/KCarretto/realm/tree/main/implants/lib/tavern)** is the source of our agents graphql API to interface with Tavern (Rust) * **[tavern](https://github.com/KCarretto/realm/tree/main/tavern)** is the parent folder of Tavern related code and packages, and stores the `main.go` executable for the service * **[tavern/auth](https://github.com/KCarretto/realm/tree/main/tavern/auth)** is a package for managing authentication for Tavern, and is used by various packages that rely on obtaining viewer information * **[tavern/ent](https://github.com/KCarretto/realm/tree/main/tavern/ent)** contains models and related code for interacting with the database (most of this is code generated by **[entgo](https://entgo.io/))** @@ -77,7 +80,9 @@ An Agent is a type of implant which retrieves execution instructons by connectin * **[tavern/graphql](https://github.com/KCarretto/realm/tree/main/tavern/graphql)** contains our GraphQL definitions and resolvers (most of this code is generated by **[entgo](https://entgo.io/)** and **[gqlgen](https://github.com/99designs/gqlgen))** * **[tavern/internal](https://github.com/KCarretto/realm/tree/main/tavern/internal)** contains various internal packages that makeup Tavern * **[tavern/internal/www](https://github.com/KCarretto/realm/tree/main/tavern/internal/www)** contains Tavern's UI code -* **[vscode](https://github.com/KCarretto/realm/tree/main/vscode)** contains our Eldritch VSCode integration source code +* **[terraform](https://github.com/KCarretto/realm/tree/main/terraform)** contains the Terraform used to deploy a production ready Realm instance. See [Tavern User Guide](https://docs.realm.pub/user-guide/tavern) to learn how to use. +* **[tests](https://github.com/KCarretto/realm/tree/main/tests)** miscellaneous files and example code used for testing. Generally won't be used but required for some niche situations like deadlocking cargo build. +* **[vscode](https://github.com/KCarretto/realm/tree/main/vscode)** contains our Eldritch VSCode integration source code **(Unmaintained)** # Where to Start? If you'd like to make a contribution to Realm but aren't sure where to start or what features could use help, please consult our [Good First Issues](https://github.com/KCarretto/realm/labels/good%20first%20issue) for some starting ideas. diff --git a/docs/_docs/dev-guide/tavern.md b/docs/_docs/dev-guide/tavern.md index 9fa945cd7..d31428a8a 100644 --- a/docs/_docs/dev-guide/tavern.md +++ b/docs/_docs/dev-guide/tavern.md @@ -218,7 +218,7 @@ query get_task_res { ### Adding Mutations 1. Update the `mutation.graphql` schema file to include your new mutation and please include it in the section for the model it's mutating if applicable (e.g. createUser should be defined near all the related User mutations) - * **Note:** Input types such as `CreateInput` or `UpdateInput` will already be generated if you [added the approproate annotations to your ent schema](https://entgo.io/docs/tutorial-todo-gql#install-and-configure-entgql). If you require custom input mutations (e.g. `ClaimTasksInput`) then add them to the `inputs.graphql` file (Golang code will be generated in tavern/graphql/models e.g. `models.ClaimTasksInput`). + * **Note:** Input types such as `CreateInput` or `UpdateInput` will already be generated if you [added the appropriate annotations to your ent schema](https://entgo.io/docs/tutorial-todo-gql#install-and-configure-entgql). If you require custom input mutations (e.g. `ClaimTasksInput`) then add them to the `inputs.graphql` file (Golang code will be generated in tavern/graphql/models e.g. `models.ClaimTasksInput`). 2. Run `go generate ./...` 3. Implement generated the generated mutation resolver method in `tavern/graphql/mutation.resolvers.go` * Depending on the mutation you're trying to implement, a one liner such as `return r.client..Create().SetInput(input).Save(ctx)` might be sufficient diff --git a/docs/_docs/user-guide/eldritch.md b/docs/_docs/user-guide/eldritch.md index 77aee6432..cdab7eeca 100644 --- a/docs/_docs/user-guide/eldritch.md +++ b/docs/_docs/user-guide/eldritch.md @@ -139,7 +139,7 @@ The file.is_file method checks if a path exists and is a file. If it does ### file.list `file.list(path: str) -> List` -The file.list method returns a list of files at the specified path. The path is relative to your current working directory and can be traveresed with `../`. +The file.list method returns a list of files at the specified path. The path is relative to your current working directory and can be traversed with `../`. Each file is represented by a Dict type. Here is an example of the Dict layout: diff --git a/docs/_docs/user-guide/golem.md b/docs/_docs/user-guide/golem.md index dd13d257b..efa32f9ab 100644 --- a/docs/_docs/user-guide/golem.md +++ b/docs/_docs/user-guide/golem.md @@ -23,7 +23,7 @@ cargo build --release && \ ``` ## 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 programatic 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.eld` in the embedded assets launching each one as a seperate 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.eld` 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 Golem can also be used as a stage 0 to load imix or other c2 agents. @@ -50,7 +50,7 @@ def decrypt(payload_bytes): def main(): if is_windows(): - for proc in proccess.list(): + for proc in process.list(): if "svchost.exe" in proc['name']: let enc_bytes = assets.read_bytes("imix.dll") sys.dll_reflect(decrypt(enc_bytes), proc['pid'], 'imix_main') @@ -63,7 +63,7 @@ main() ```python def main(): - for proc in proccess.list(): + for proc in process.list(): if "MsMpEng.exe" in proc['name']: return run_payload() diff --git a/docs/_docs/user-guide/imix.md b/docs/_docs/user-guide/imix.md index 95e76275b..74a129d7e 100644 --- a/docs/_docs/user-guide/imix.md +++ b/docs/_docs/user-guide/imix.md @@ -39,7 +39,7 @@ The imix config is as follows: ``` - `service_configs`: Currently unused. -- `target_forward_connect_ip`: The IP address that you the red teamer would interact with the host through. This is to help keep track of agents when a hosts internal IP is different from the one you interact with in the case of a proxied host. +- `target_forward_connect_ip`: The IP address that you the red teamer would interact with the host through. This is to help keep track of agents when a hosts internal IP is different from the one you interact with in the case of a host behind a proxy. - `target_name`: Currently unused. - `callback_config`: Define where and when the agent should callback. - `interval`: Number of seconds between callbacks. diff --git a/docs/pages/user-guide.md b/docs/pages/user-guide.md index 3fbf9246a..a33d1d08f 100644 --- a/docs/pages/user-guide.md +++ b/docs/pages/user-guide.md @@ -35,7 +35,7 @@ Want to get hands on now? Standalone interpreter (golem)
  • Interactive shell for testing hands-on testing.
  • -
  • Embedded files that execute autonomously on execuiton.
  • +
  • Embedded files that execute autonomously on execution.
Built-in interpreter (eldritch)