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

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

Use pull requests to submit changes to the repository for review. All pull requests are reviewed by the project maintainers and the continuous integration program CircleCI.

Submitting a basic PR using the Web Interface is easier for beginners and more intuitive. You can find a demo video for creating a Pull Request using the web interface here. 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.

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 > Show all checks > Details.
3. Read CircleCI'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 CircleCI 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, message Adam Mashinchi on the Atomic Red Team Slack workspace.

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 with dedicated repositories. Instead, use the prereq_commands YAML key to download any dependencies from their original sources.
• 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, CircleCI-generated Markdown test 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.