Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

[docs] Update Contributor Docs #381

Merged
merged 3 commits into from
Dec 11, 2023
Merged

[docs] Update Contributor Docs #381

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
01976c4
Update Contributor Docs
KCarretto Nov 18, 2023
11541d1
Update introduction.md
KCarretto Nov 18, 2023
3035745
Merge branch 'main' into contributor-docs-update
KCarretto Dec 11, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
23 changes: 17 additions & 6 deletions docs/_docs/dev-guide/introduction.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 `<packagename>_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)
Expand All @@ -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
Expand Down
Loading