diff --git a/docs/_data/toc.yml b/docs/_data/toc.yml index 4883543e1..69c625aa1 100644 --- a/docs/_data/toc.yml +++ b/docs/_data/toc.yml @@ -3,8 +3,6 @@ links: - title: "Getting Started" url: "user-guide/getting-started" - - title: "UI" - url: "user-guide/ui" - title: "Tomes" url: "user-guide/tomes" - title: "Imix" @@ -46,8 +44,6 @@ - title: "Tavern" url: "dev-guide/tavern" children: - - title: "CDN API" - url: "admin-guide/tavern#cdn-api" - title: "Agent Development" url: "admin-guide/tavern#agent-development" - title: "Eldritch" diff --git a/docs/_docs/dev-guide/tavern.md b/docs/_docs/dev-guide/tavern.md index dc5ee5312..2176b9d33 100644 --- a/docs/_docs/dev-guide/tavern.md +++ b/docs/_docs/dev-guide/tavern.md @@ -99,59 +99,13 @@ apt install -y graphviz ## Agent Development -Tavern provides an HTTP(s) GraphQL API that agents may use directly to claim tasks and submit execution results. This is the standard request flow, and is supported as a core function of realm. To learn more about how to interface with GraphQL APIs, please read [this documentation](https://www.graphql.com/tutorials/#clients) or read on for a simple example. +Tavern provides an HTTP(s) [gRPC API](https://grpc.io/) that agents may use directly to claim tasks and submit execution results. This is the standard request flow, and is supported as a core function of realm. For more information, please consult our [API Specification](https://github.com/spellshift/realm/blob/main/tavern/internal/c2/proto/c2.proto). -![/assets/img/tavern/standard-usage-arch.png](/assets/img/tavern/standard-usage-arch.png) +If you wish to develop an agent using a different transport method (e.g. DNS), your development will need to include a C2. The role of the C2 is to handle agent communication, and translate the chosen transport method into HTTP(s) requests to Tavern's gRPC API. We recommend reusing the existing protobuf definitions for simplicity and forward compatability. This enables developers to use any transport mechanism with Tavern. If you plan to build a C2 for a common protocol for use with Tavern, consider [submitting a PR](https://github.com/spellshift/realm/pulls). -This however restricts the available transport methods the agent may use to communicate with the teamserver e.g. only HTTP(s). If you wish to develop an agent using a different transport method (e.g. DNS), your development will need to include a C2. The role of the C2 is to handle agent communication, and translate the chosen transport method into HTTP(s) requests to Tavern's GraphQL API. This enables developers to use any transport mechanism with Tavern. If you plan to build a C2 for a common protocol for use with Tavern, consider [submitting a PR](https://github.com/spellshift/realm/pulls). +### Agent Loop Lifecycle -![/assets/img/tavern/custom-usage-arch.png](/assets/img/tavern/custom-usage-arch.png) - -### GraphQL Example - -GraphQL mutations enable clients to _mutate_ or modify backend data. Tavern supports a variety of different mutations for interacting with the graph ([see schema](https://github.com/spellshift/realm/blob/main/tavern/internal/graphql/schema/mutation.graphql)). The two mutations agents rely on are `claimTasks` and `submitTaskResult` (covered in more detail below). GraphQL requests are submitted as HTTP POST requests to Tavern, with a JSON body including the GraphQL mutation. Below is an example JSON body that may be sent to the Tavern GraphQL API: - -```json -{ - "query": "mutation ClaimTasks($input: ClaimTasksInput!) {\n claimTasks(input: $input) {\n id\n }\n}", - "variables": { - "input": { - "principal": "root", - "hostname": "test", - "hostIdentifier": "dodo", - "agentIdentifier": "bleep", - "beaconIdentifier": "123" - } - }, - "operationName": "ClaimTasks" -} -``` - -In the above example, `$input` is used to pass variables from code to the GraphQL mutation while avoiding sketchy string parsing. Fields that should be present in the output are included in the body of the query (e.g. 'id'). - -### Claiming Tasks - -The first GraphQL mutation an agent should utilize is `claimTasks`. This mutation is used to fetch new tasks from Tavern that should be executed by the agent. In order to fetch execution information, the agent should perform a graph traversal to obtain information about the associated quest. For example: - -```graphql -mutation ClaimTasks($input: ClaimTasksInput!) { - claimTasks(input: $input) { - id - quest { - tome { - id - eldritch - } - bundle { - id - } - } - } -} -``` - -If the mutation returns a bundle, it should be fetched from the CDN to provide necessary assets (a tar.gz) for eldritch execution. The Task ID should be saved for later reporting results of task execution. - -## Submitting Results - -After task execution has been completed (or as it is being completed), an agent should utilize the `submitTaskResult` mutation to update Tavern with execution output and status information. When task execution is finished, the agent should provide a value for the `execFinishedAt` parameter. If a task fails to complete, the agent should provide a value for the `error` parameter. +1. Claim [Tasks](/user-guide/terminology#task) +2. Execute [Tasks](/user-guide/terminology#task) (happens in parallel and may not finish within one loop) +3. Report available output from [Task](/user-guide/terminology#task) execution +4. Sleep for an interval and repeat diff --git a/docs/_docs/user-guide/eldritch.md b/docs/_docs/user-guide/eldritch.md index 7be2b15e9..ed7b6d1a9 100644 --- a/docs/_docs/user-guide/eldritch.md +++ b/docs/_docs/user-guide/eldritch.md @@ -7,7 +7,7 @@ permalink: user-guide/eldritch --- # Overview -Eldritch is a pythonic red team Domain Specific Language (DSL) based on [starlark](https://github.com/facebookexperimental/starlark-rust). +Eldritch is a Pythonic red team Domain Specific Language (DSL) based on [starlark](https://github.com/facebookexperimental/starlark-rust). It uses and supports most python syntax and basic functionality such as list comprehension, string operations (`lower()`, `join()`, `replace()`, etc.), and built-in methods (`any()`, `dir()`, `sorted()`, etc.). For more details on the supported functionality not listed here, please consult the [Starlark Spec Reference](https://github.com/bazelbuild/starlark/blob/master/spec.md), but for the most part you can treat this like basic Python with extra red team functionality. Eldritch is a small interpreter that can be embedded into a c2 agent as it is with Golem and Imix. By embedding the interpreter into the agent conditional logic can be quickly evaluated without requiring multiple callbacks. diff --git a/docs/_docs/user-guide/getting-started.md b/docs/_docs/user-guide/getting-started.md index bb7faa497..b72cdf80a 100644 --- a/docs/_docs/user-guide/getting-started.md +++ b/docs/_docs/user-guide/getting-started.md @@ -73,6 +73,8 @@ Now it's time to provide our [Beacon](/user-guide/terminology#beacon) it's first Now from the left navigation menu, select "Create new quest". +*Note: `Service + group` searches use `AND` while `service + service` or `group + group` searches use `OR`* + ![create-new-quest](/assets/img/user-guide/getting-started/create-new-quest.png) This view will show all of our active [Beacons](/user-guide/terminology#beacon) available for tasking. For more details on filtering and selecting [Beacons](/user-guide/terminology#beacon), see our [UI guide](/user-guide/ui). For now, simply select your creatively-named [Beacon](/user-guide/terminology#beacon) and click "Continue". diff --git a/docs/_docs/user-guide/golem.md b/docs/_docs/user-guide/golem.md index 5cdcb6fda..7f9a55d4e 100644 --- a/docs/_docs/user-guide/golem.md +++ b/docs/_docs/user-guide/golem.md @@ -8,7 +8,7 @@ permalink: user-guide/golem ## What is Golem Golem is the standalone interpreter for Eldritch. -This program exists to help users get experience with the Eldritch language as well as a jumping off point if you're interested in implementing your own program using the Eldritch language. +This program exists to help users get experience with the Eldritch language as well as a jumping off point if you're interested in implementing your own program using the Eldritch language. Additionally, consult our [Tomes](/user-guide/tomes) documentation for information about packaging [Eldritch](/user-guide/terminology#eldritch) code for use with [Imix](/user-guide/imix) and Tavern. Golem can also be used operationally as an alternative to a system native shell. You can leverage the power of Eldritch with minimal exposure in the system process tree. diff --git a/docs/_docs/user-guide/ui.md b/docs/_docs/user-guide/ui.md deleted file mode 100644 index 7032ee78f..000000000 --- a/docs/_docs/user-guide/ui.md +++ /dev/null @@ -1,47 +0,0 @@ ---- -title: UI -tags: - - User Guide -description: UI Guide -permalink: user-guide/ui ---- - -## Overview - -This section outlines some basic usage and gotchas. - -### Creating quests - -Quests are how you interact with beacons think actions/tasks in other c2s. - -Quests by default are group actions so scaling your activity is easy and built-in. - -Each quest is made up of three main parts: - -- Beacons - What you'll be executing on -- Tomes - What you'll be executing -- Input parameters - arguments passed to the tome and eldritch interpreter as `input_params{}` - -#### To start click "Create new quest" - -First you'll be prompted to select beacons you want this quest to apply to. - -Beacons can be searched by name, group tag, and service tag. - -Just start typing what you're looking for and Tavern will search across all three fields. - -Now you can select individual beacons or use the "Select all" button to add everything that matches your search criteria. - -*Note: `Service + group` searches are and'd while `service + service` or `group + group` searches are or'd.* - -#### Next select the tome you want to run - -Tomes can be searched by name - -If the tome has parameters you'll be prompted. Consult the placeholder text if you're unsure how to format the input. - -#### Finally review and confirm your quest - -The final page gives an overview of what beacons, tome and parameters have been selected. - -Lastly give your quest a descriptive name so you can reference back to it later if you need to lookup the information again. (We recommend this so you can avoid duplicating work and exposure on the system).