Contributing to Atomic Red Team
NOTE: We have sweet stickers for people who contribute; if you’re interested send a message to firstname.lastname@example.org with your mailing address
- Atomic Philosophy
- How to contribute
- Atomic Test structure
- Generating Atomic docs yourself (optional)
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 the atomic-red-team repository in Github, then checkout the repository and make a branch for your new test:
git clone email@example.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.
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 that your Atomic Test is up to spec!
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.
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
The directory structure is:
- Tests reside in the
- One directory per ATT&CK technique, named as
- All the atomic tests for a technique in a file named
T1234.yamlinside that directory
- Any payloads, supporting materials, etc for the atomic tests also live in that directory
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:
The CircleCI build will automatically generate docs and commit them to master when your pull request is merged.