Guide · Open source
How to use atomic-red-team: clone, run tests and read results
Updated · written with AI from the project's own documentation and checked against our catalogue data
Atomic Red Team is an open-source library of small tests, each mapped to a technique in MITRE's ATT&CK framework, which catalogs how attackers behave. It is built for security teams and detection engineers who want to check whether their tools would notice those behaviors. After this guide you will know how to get the repository, where the tests live, and what the project recommends for running them.
Atomic Red Teamredcanaryco/atomic-red-team · ★ 12.8k · MIT Install options & downloads Quick start
- 1Clone the repository. Run the git clone command from the README to download the atomic tests to your machine.
- 2Read the Getting started page. Open the project's wiki Getting started page to learn how to execute atomic tests from the command line.
- 3Pick a technique. Choose an ATT&CK technique you want to test and find its matching atomic test in the repository.
- 4Prepare a safe test system. Use a lab or authorized test machine so the simulated behavior does not affect production systems.
- 5Run the test. Execute the chosen atomic test from the command line as described in the wiki.
- 6Check your detections. Confirm whether your security tools logged or alerted on the behavior, and fix gaps you find.
What Atomic Red Team is and who it is for
Atomic Red Team is a collection of small tests. Each test is mapped to a MITRE ATT&CK technique, so you can see which attacker behavior it is meant to exercise. The README describes the tests as quick, portable, and reproducible, which makes them useful for checking an environment repeatedly.
It is a set of security tests, not an app or library for building software. Security teams testing whether their detection tools catch ATT&CK techniques and detection engineers who want small, repeatable test cases are the intended users.
Get the repository
The README lists a single install command: cloning the repository from GitHub. The project does not list any prerequisites, so the clone command is the only setup step it documents.
git clone https://github.com/redcanaryco/atomic-red-teamRun tests from the command line
The README says you can execute atomic tests directly from the command line with no installation required. The project's Getting started page on its wiki explains how to do this, so read that page before running anything in a real environment.
Only run tests on systems you own or are authorized to test. Each test simulates attacker behavior, so check what a test does before you execute it.
- Start in a lab or test machine, not production.
- Read the test description and ATT&CK mapping first.
- Check your detection tools (EDR, SIEM, logging) for the expected alerts after each test.
Know the documentation and community resources
The documentation is hosted as a wiki in the repository. The project also has a website at atomicredteam.io, a newsletter, and a Slack workspace linked from the README.
If you want to contribute, the README points to the contribution guide on the wiki, the issue tracker for bug reports and feature requests, and the code of conduct. Linux atomics can be contributed from GitHub Codespaces, as described in the wiki.
Use a more robust framework when you need one
The README says that for a more robust testing experience you should consider an execution framework, and it names Invoke-Atomic. Atomic Red Team on its own is a library of tests, so if you need a full testing platform, plan to pair it with an execution framework or pick a different tool.
Other projects often compared with it are MITRE Caldera and Sigma. They are different kinds of tools, so check what each one does before choosing.
What people use it for
- Checking whether an EDR or SIEM alerts on a specific ATT&CK technique.
- Building small, repeatable test cases for detection engineering work.
- Running quick command-line tests on a lab machine without installing extra software.
- Adding Linux atomic tests through GitHub Codespaces as a contributor.
Frequently asked questions
Is atomic-red-team free to use?
Atomic Red Team is released under the MIT licence, according to the project's repository details. Check the LICENSE file in the repository for the full terms before you distribute or modify it.
How do I install atomic-red-team?
The README's install step is to clone the repository with git clone https://github.com/redcanaryco/atomic-red-team. It also says you can run tests from the command line without installing anything else.
Does atomic-red-team need any prerequisites?
The README does not list any prerequisites. The Getting started page on the project wiki is the place to check how to run tests on your system.
What is MITRE ATT&CK and how does it relate to atomic tests?
MITRE ATT&CK is a public catalog of how attackers behave. Each atomic test is mapped to a technique in that framework, so you can test whether your systems notice a specific behavior.
What is the difference between Atomic Red Team and Invoke-Atomic?
Atomic Red Team is the library of tests. The README points to Invoke-Atomic as an execution framework for a more robust testing experience, so the two are used together or Invoke-Atomic is chosen for fuller runs.
What are alternatives to atomic-red-team?
The project's comparable projects are Invoke-Atomic, MITRE Caldera, and Sigma. Invoke-Atomic is the one the README recommends for a more robust experience.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
Atomic Red Team suits security teams and detection engineers who want small, repeatable ATT&CK-mapped tests they can run from the command line. It is not a general-purpose library for building software, and if you need a full testing platform, the README points you to Invoke-Atomic.
Install options & downloads