Designing Atomic Tests

Writing new Atomic Red Team tests is a great way to contribute to the security community, extend the functionality of the Atomic Red Team project, and help share your knowledge with practitioners everywhere.

The power of the Atomic Red Team project is in our contributors and we'd love to have you as part of that group!

If you've identified a method for testing a MITRE ATT&CK technqiue that is not yet covered in the Atomic Red Team repository, or want to extend, improve, or otherwise enhance the coverage of an existing test, the following guidelines should get you started. This is also a great use of the Atomic Red Team Slack workspace and Atomic Red Team subreddit if you're stuck or need a gut-check. TODO LINKS

Directory structure

Each technique directory contains the following:

• A YAML test file.
• A human-readable, Markdown test file. (This is automatically generated from the YAML file - don't create this file yourself!)
• An optional src directory for source file dependencies.
• An optional bin directory for binary dependencies.

Note

👉 Automated GitHub Actions will generate the auto_generated_guid for a new test (in the YAML). Don't to add this manually.

Test names

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

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 portability

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

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 an ExternalPayloads directory at the top-level of the checked-out atomic-red-team repository.
• 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.

Input and output

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

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 delete dependencies while running cleanup commands.