Contributing

The basics of contributing to Atomic Red Team™ on Github.

Contents

• Contents
• Submit an issue
• Open a pull request
  • Edit or add atomic tests
  • Make changes to the repository
  • Fix failed checks
  • Claim your free t-shirt
• Designing atomic tests
  • Cleanup commands
  • Dependencies
  • Directory structure
  • Input and output
  • Test descriptions
  • Test names
  • Test portability
• How to write atomics for cloud

Submit an issue

We use Github issues to track the following:

• Bug reports, including broken atomic tests
• New feature requests
• Requests for updates or changes

View the list of current issues here. If you have a new issue, submit it here.

Open a pull request

Demo Video for creating and submitting Pull Requests

Use pull requests to submit changes to the repository for review.

Submitting a basic PR using the Web Interface is easier for beginners and more intuitive. If you are making changes to multiple files within the repository, you may prefer to use Git to make your changes. For more information on how to get started using Git on the command line, we have provided a walkthrough.

Edit or add atomic tests

There are two ways to create new atomic tests:

• Use the atomic GUI web interface. See the atomic GUI wiki page.
• Write a new test by hand. Use the atomic test YAML specification file as a template. If you would like to validate your file against a YAML schema, you can use this schema.

You can also make changes to existing atomic tests by editing the YAML test file in a given technique directory. For example, you can make changes to existing Process Injection tests by editing atomic-red-team/atomics/T1055/T1055.yaml.

👉 Note: Automated GitHub Actions will generate the auto_generated_guid for a new test (in the YAML). You don't need to add this manually.

Make changes to the repository

When you're ready to open a pull request, follow these steps:

1. Navigate to the atomics directory of the Atomic Red Team repository.
2. Select the directory named after the MITRE ATT&CK® technique you want to contribute to. If no such directory exists, create one.
3. Make changes to the YAML file in the technique directory.
   • Add source file dependencies to the src directory, if necessary.
   • Add binary dependencies to the bin directory, if necessary.
4. Commit your changes and open a pull request.

👉 Note: Automated GitHub Actions generate the Markdown test files and the list of tests in atomics/Indexes. You never need to update them manually.

Fix failed checks

You must fix any failed checks before a project maintainer can approve your pull request:

1. Go to your pull request page on GitHub.
2. Select Conversation > Details.
3. Read GitHub's error messages and make the required changes.
4. Commit the changes to your existing pull request.

You'll know your test is ready for manual review when GitHub displays the "All checks have passed" message:

Claim your free t-shirt

First-time contributors get a free Red Canary t-shirt when their pull request is merged. To claim your t-shirt, fill out this form.

Designing atomic tests

Adhere to these guidelines when designing new atomic tests.

Cleanup commands

• Users should be able to execute cleanup commands repeatedly without generating errors. You can accomplish this by piping error outputs to null in most command lines, or by using the -ErrorAction Ignore argument in PowerShell.
• Don't write cleanup commands that delete dependencies.

Dependencies

• Provide the source code of any custom binaries.
• Don't commit dependencies that have their own external GitHub repositories into this project. Instead, use the prereq_commands YAML key to download any dependencies from their original sources into the ExternalPayloads directory which is in the same folder as the atomics folder.
• Refer to external repositories with permanent GitHub links to prevent unexpected changes.
• If a dependency is built into an operating system by default, don't write any commands to check for or install it.

Directory structure

Each technique directory contains the following:

• A YAML test file
• A human-readable, Markdown test file (automatically generated from the YAML file)
• An optional src directory for source file dependencies
• An optional bin directory for binary dependencies

Input and output

• Use input arguments for items that the user might want to customize.
• Include the technique number in any output file names.

Test descriptions

• Include a description of what the test does and a description of the expected output.
• Include links to web pages that describe the attack in detail, if possible.

Test names

• Include enough information in the test name to give the user a general idea of what the test does.

Test portability

• Make tests as portable as possible. For example, use environment variables instead of hard-coded paths.
• Prefer sh to bash for Linux tests.

How to write atomics for cloud

There are several ways to write an atomic against a AWS/Azure/GCP environments, but these are the three ways to simulate an attack against cloud using Atomic Red Team:

1. Command Line Interface (CLI)- All major cloud providers have their CLI (Command Line Interface) tools available, each specific to a particular cloud provider for example: AWS CLI, Azure CLI, Gcloud CLI

While authoring an atomic using this method, the user will ensure these tools are installed and configured in the prerequisites section and then use the same CLI tools to attack the cloud environment.

TLDR; Use the CLI tools to create appropriate resources in your cloud environment and then simulate the attack using specific command line arguments

Example : AWS CloudWatch Log Stream Deletes - We use the aws cli to create and delete a cloud watch log stream

2. Using Terraform and Cloud CLI tools

In this method of writing an atomic, we will be using a combination of terraform and cloud cli tools to simulate an attack. However, when using this there are terraform files needed in a specific directory structure. Let’s take this example:

AWS - CloudTrail Changes (T1562.008-1)

In the above atomic, we are using terraform to create and configure a cloudtrail as a part of the pre-requisites and then update/stop/delete the cloudtrail using the AWS CLI tool command.

Terraform files: For the desired atomic, create a folder in the src directory with the atomic test number. Eg: T1562.008/src/T1562.008-1/

In this folder, there are two terraform files needed to create/configure appropriate resource like create S3 bucket in AWS, configure cloudtrail.

• T1562.008-1.tf : This file is essentially a set of instructions that define the resources that Terraform should create, modify, or delete in a cloud environment.

• Terraform.tfvars: This file is a file format used by Terraform to define values for variables used in a Terraform configuration file (.tf file)

Invoke-AtomicRedTeam can programmatically identify these files to execute this new flavor of atomics. When you execute pre-reqs, the code will run terraform init and terraform apply -auto-approve to create a .tfstate and tfvars.json file based on the input arguments.

In the execution section: we can simply run AWS CLI commands to simulate the attack and during clean up: we would run terraform destroy -auto-approve to destroy the resources.

3. **Using third party tools **

One such example of this method is using Stratus Red Team, an open source tool developed by DataDog.

Example - AWS - Retrieve EC2 Password Data using stratus