atomic-red-team/docs/contributing.md

layout

layout
default

Contributing to Atomic Red Team

NOTE: We have sweet stickers for people who contribute; if you’re interested send a message to gear@redcanary.com with your mailing address

• Atomic Philosophy
• How to contribute
• Atomic Test structure
• Generating Atomic docs yourself (optional)

Atomic Philosophy

Atomic Red Team welcomes all types of contributions as long as it is mapped to MITRE ATT&CK. A few guidelines:

• Tests are made to be "easy". If your Atomic Test is complicated and requires multiple external utilities/packages/Kali, we may ask that you simplify it.

• TEST YOUR ATOMIC TEST! Be sure to run it from a few OSes/platforms before submitting a pull request to ensure everything is working correctly.

• If sourcing from another tool/product (ex. generated command), be sure to cite it in the test's description.

How to contribute

Fork

Fork the atomic-red-team repository in Github, then checkout the repository and make a branch for your new test:

git clone git@github.com/YOUR_GITHUB_ACCOUNT/atomic-red-team
cd atomic-red-team

git checkout -b t1234-something-describing-your-test

Add Atomic Test

Pick the technique you want to add a test for (ie, T1234) and run the generator. This makes a new test for the technique with a bunch of TODOs you'll fill in and opens up your editor so you can get to work.

bin/new-atomic.rb T1234

Don't have Ruby? Use the Atomic Test template here as a starting point for your new test.

Fill in the TODOs with the information for your test. See the Atomic Test structure section below.

Validate

Validate that your Atomic Test is up to spec!

bin/validate-atomics.rb

Don't have Ruby? The automated build system will validate the techniques on your branch as soon as you commit to your branch and push to your fork.

Push it

Submit a Pull Request once your test is complete and everything validates.

git add atomics/T1234
git commit -m "Add test for T1234 that does XYZ"
git push -u origin $(git branch |grep '*'|cut -f2 -d' ')

Go to github.com/YOUR_GITHUB_ACCOUNT/atomic-red-team and follow the instructions to create a new Pull Request.

Atomic Test structure

This spec describes the format of Atomic Red Team atomic tests that are defined in YAML format.

The Atomic YAML schema is specified in the Atomic Red Team YAML Spec. See that file for complete details about what each field means and a list of possible values.

The source of truth for a test is the YAML file - the associated human readable Markdown file is automatically generated via bin/generate-atomic-docs.rb and atomic_red_team/atomic_doc_template.md.erb.

The directory structure is:

• Tests reside in the atomics directory
• One directory per ATT&CK technique, named as T1234
• All the atomic tests for a technique in a file named T1234.yaml inside that directory
• Any payloads, supporting materials, etc for the atomic tests also live in that directory

For example:

atomic_red_team/
atomic_red_team/atomics
atomic_red_team/atomics/T1234
atomic_red_team/atomics/T1234/T1234.yaml   <-- where all the atomic tests for a technique live
atomic_red_team/atomics/T1234/payload1.sct <-- payload file needed by one of the T1234 atomics

In general, a set of atomic tests for a technique should never depend on payloads or supporting files from other atomic directories. We want to keep things nice and close. Use git symlinks if you really need to share files between techniques.

Generating Atomic docs yourself (optional)

If you want to see what the pretty Markdown version of your Atomic Test is going to look like, you can generate the Atomic Docs yourself:

bin/generate-atomic-docs.rb

The CircleCI build will automatically generate docs and commit them to master when your pull request is merged.