Skip to content

Contributing

Jump to bottom
Carrie Roberts edited this page Aug 27, 2020 · 72 revisions

Contributing to Atomic Red Team comes with a variety of benefits to build your career including:

Atomic Red Team is an open-source, community developed resource. A GitHub repository is used to host the project and make it easy for multiple people to contribute using pull requests. A pull request (PR) is a way of requesting that a change or be added into the official repository. You must have an account on GitHub to submit a PR. Please review our Code of Conduct and License before contributing.

Bonus: First-time contributors get a free Red Canary t-shirt when their first Pull Request is merged. Direct message Brian Donohue on the Atomic Red Team Slack Workspace.

Submit an Idea, Feature Request or Report an Issue

The most basic way that you can contribute is by submitting an issue to report a problem, such as a broken atomic test, or request a new feature or other change. Your ideas are valuable to us and submitting an issue allows us to be aware and keep track of all issues. It also gives the community of developers ideas on needed fixes and features to implement. You can view the list of current issues by clicking on the Issues link on the top menu bar of this repository.

PR Approval and Continuous Integration with Circle CI

When a PR is submitted it must be reviewed and approved by one of the project maintainers before it is merged (becomes part of) the official project. Simply submitting a PR will draw the attention of the maintainers but you can request a specific reviewer using the web interface if you prefer.

If you look at the PR as soon as it is created you might notice a yellow message like the one below saying "Some Checks haven't completed yet" and a little sub-note about circleci running some pending tasks. image This is because every time a PR, or make a commit to a PR, some scripts run automatically using to circleci platform to validate that the contribution meets certain specifications. Don't panic if your PR fails these checks, you can click on the Details link to find out why. You can then edit the PR to fix any issues until you get things to pass the automated tests.

Another helpful thing that the automated scripts do is build those beautiful markdown files (.md) that describe the atomic test in a easily human-readable format. The markdown files are built from the test definition yaml files, which contain the same information, but are more machine readable than human readable.

After your PR has passed the automated checks you will see the "All checks have passed" message as shown below. image

The messages in red indicate that merging is blocked until the PR has been reviewed and approved by one of the project maintainers. Your contribution will not become a part of the official project until it has been both approved and merged by a maintainer. Check back on your PR regularly as a maintainer may post comments or request changes to your PR before they will approve it.

Create Basic PR through the Web Interface

You can make a quick fix to an existing atomic test by using the GitHub web interface. This is a good technique to use if you are simply fixing a typo or making a description more verbose or clear for an existing test. This 5 minute video walks you through the process of submitting a simple PR in this way.

Create New Atomic and Submit PR through the Web Interface

If you would like to add a brand new atomic test, you can write the atomic test definition yaml manually according to this spec, or you can use the Atomic-Gui web interface. The Atomic GUI will help you avoid the many pitfalls that are common when manually writing yaml. This 12 minute video will walk you through using the Atomic GUI and submitting a Pull Request.

Note: To use the Atomic GUI you must have first installed the execution framework and imported the module.

Use Git Command Line

Submitting a basic PR using the Web Interface is easier for beginners and more intuitive, but it is not ideal for making large or complicated changes affecting multiple files within the repository. In this case, you can use the git command line tool for Windows, Linux and macOS.

The following summary of git commands will help you know how to clone and setup your repository in preparation for submitting a PR.

# Clone your fork of the Red Canary Atomic Red Team Repository
git clone https://github.com/<your-github-username>/atomic-red-team.git
​
# Change directories into your cloned repository
cd atomic-red-team
​
# Set your origin (your fork) and your upstream (Red Canary's repo)
# You have to do this every time you re-clone your repo, which likely is not often
git remote set-url origin https://github.com/<your-github-username>/atomic-red-team.git
git remote add upstream https://github.com/redcanaryco/atomic-red-team.git
​
# Update your forked master branch to match Red Canary's repo
# Do this right before creating a feature branch and working on it
git checkout master
git fetch --all
git rebase upstream/master
git push origin master
​
# Create a new branch from master to work on your new feature and switch to it (replace <branch-name> with whatever name you would like to use for your branch)
git checkout -b <branch-name>

# Add and commit your new/modified files to your local branch (not on the web), use "git status" to see what is new/changed
git add /path/to/new/changed/file.yaml    # repeat for multiple files as needed
git commit -m "This should be a short message describing what changed."

# Push the changes out to your repository residing in GitHub on the web
# The output from this command will tell you where to go on the web to submit the PR
git push origin <branch-name>

Remember that the goal is to synchronize your master branch with Red Canary's master branch immediately before creating a feature branch. It is best to always make your changes to a branch other than master branch. Therefore, you should expect to repeat the steps from "Update your forked master branch to match Red Canary's repo" and below often (immediately before working on each new feature or addition).

Atomic Test Design Guidelines

  • Atomic folder structure
    • Each Technique Folder (e.g. T1003) will have one yaml file and one markdown file. It will optionally contain a bin and/or src folder. The bin folder should contain any supporting files that are binary files and the src directory should contain any supporting files that are human readable.
  • Provide source for binary files
    • If you have created a custom binary for an atomic test, please provide the source code for it in the src folder if possible.
  • Avoid committing tools and scripts to this repository that live elsewhere
    • Instead of copying a tool from another repository or online source and committing into this repository, use prereq_commands to automatically pull down these tools from their original source as needed. This avoids copyright issues and excessive tripping of alerts when simply installing Atomic Red Team. See the yaml spec file for more details on how dependencies and prereq commands are intended to work.
  • Use GitHub permanent links for files outside of this Repo
    • If your test downloads a tool from another GitHub repository, please refer to it by a permanent GitHub link so that it does not change unexpectedly. Permanent links include a specific commit ID and are static files that do not change.
  • Include Technique number in output file name
    • If your test writes an output file to disk, use the technique number (e.g. T1103.001) in the file name to help distinguish it from other output files.
  • Dependencies (aka Prereqs)
    • Prereqs allow a user to validate that the system they are about to run the test on has the files and programs needed in order to successfully execute the test. Prereqs are expected to only need to be installed once per host and should not be removed by cleanup commands. If needed files and programs come on the operating system by default, then there is generally no need to write a dependency check for it.
  • Cleanup commands
    • Cleanup commands should be able to be run multiple times in a row without generating error messages to the user. This can be accomplished in most cases by using -ErrorAction Ignore in PowerShell or piping output to nul from the command prompt. The most common cleanup command is to delete a file, so running the cleanup command when that file doesn't exist should just silently continue.
  • Use descriptive test names
    • The name of the atomic test should be descriptive enough to give a basic understanding of what the test does. Basic names like "PowerShell" or "Recon" should be expanded to give a better indication of what the test does and to distinguish it from other tests.
  • Test descriptions
    • Please describe what the test does AND what the user should look for to determine if the test ran successfully. If possible, include a link to a web page with more information about the attack.
  • Tests should work out-of-the-box
    • Make every effort to make a test work by default for anyone. This can be facilitated by using environment variables to specify a user or known path instead of hard-coding them into the test.
  • Use input arguments
    • Use input arguments for items that the executor of the test is likely to want to customize.
  • sh vs bash executor
    • It is preferred to use the sh over the bash executor for Linux tests unless there is a compelling reason to use bash. This is because sh is installed by default on all *nix distributions.

Hints and Tips

  • The Invoke-AtomicRedTeam Wiki
    • Invoke-AtomicRedTeam is a PowerShell tool for automatically executing the atomic tests defined within the yaml files in this repository. It has an excellent wiki that will help you understand how many of the atomic test yaml elements are used. You can review the Invoke-AtomicRedTeam wiki here.
  • Editing an existing PR
    • If you find that you need to make a change to a PR that you have already submitted (but has not yet been merged), you can simply push a change to the same branch and it will automatically become part of that PR. You do not need to close the PR and create a new one.
  • Auto generated guid
    • When an atomic test is first merged into the official repository is will be assigned a unique guid which you can find in the yaml file as the auto_generated_guid element. When submitting a new test, do not include this yaml attribute and it will be added for you when merged. If you are working with a pre-existing test, do not remove or edit the auto_generated_guid.
  • Validating yaml and building Markdown files locally (optional)
    • When you submit a PR, some scripts will validate your yaml files and generate the markdown files in the cloud. If you want to validate or generate the markdown files locally you can use Ruby to execute the validate-atomics.rb and generate-atomic-docs.rb from the bin directory.
  • Join the Atomic Red Team Slack workspace

Useful Coding Examples

Examples

Dependencies (Prereqs)

Adding dependencies to atomic tests allow users to check if their system meets the pre-requisites required to successfully execute a test. When possible, it also defines commands the the user can run to satisfy the prereqs and thus be able to run the test. Some examples are included below that may help you develop prerequisites for your own tests.

PowerShell

Command Prompt

Cleanup Commands

Ideally, users can run cleanup commands multiple times in a row without receiving unnecessary errors. For example, if the cleanup command is trying to delete a file that has already been deleted it should just silently continue.

PowerShell

Command Prompt

Questions? Get connected to the community on the Atomic Red Team™ Slack channel.

Clone this wiki locally