diff --git a/docs/_docs/dev-guide/introduction.md b/docs/_docs/dev-guide/introduction.md index 6bf56a4f6..2990904e4 100644 --- a/docs/_docs/dev-guide/introduction.md +++ b/docs/_docs/dev-guide/introduction.md @@ -31,6 +31,8 @@ Any methods added to the Eldritch Standard Library should have tests collocated ##### Tavern Tests (Golang) All code changes to Tavern must be tested. Below are some standards for test writing that can help improve your PRs: * Please submit relevant tests in the same PR as your code change +* For GraphQL API Tests, please refer to our [YAML specification](/dev-guide/tavern#yaml-test-reference-graphql) +* For gRPC API Tests, please refer to our [YAML specification](/dev-guide/tavern#yaml-test-reference-grpc) * 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) @@ -50,18 +52,27 @@ In an attempt to reduce the complexity of merges, we enforce a linear history fo 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. - -### Task -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. +### Host +A Host 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. ### Implant -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. +References malicious code or persistence mechanisms that are deployed to compromise target systems. ### Agent An Agent is a type of implant which retrieves execution instructions by connecting to our backend infrastructure (calling back) and querying for new tasks. +### Beacon +A Beacon is a running instance of an Agent. A Host may have multiple active Beacons that use the same underlying Agent. + +### Task +A Task represents a set of instructions for an Agent to perform. For example, listing files could be a Task. When listing files across various Beacons, one Task per Beacon will be created for tracking the individual execution output. + +### Eldritch +Eldritch is our Pythonic Domain Specific Language (DSL), which can be used to progammatically define red team operations. Many of the language's built-in features do not rely on system binaries. For more information, please see the [Eldritch section](/user-guide/eldritch) of the documentation. + +### Tome +A Tome is a prebuilt Eldritch bundle, which provides execution instructions to a Beacon. Tomes can embed files and accept parameters to change their behaviour at runtime. Tavern's built-in Tomes are defined [here](https://github.com/KCarretto/realm/tree/main/tavern/tomes). + # 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