Atomic Red Team is a library of portable, repeatable tests mapped to the MITRE ATT&CK framework. Each “atomic” test simulates a specific adversary technique (e.g., T1059 Command and Scripting Interpreter) at a granular level. Security teams use Atomic Red Team for purple team exercises, testing detection rules, validating security controls, and training incident response teams. Tests are lightweight, include cleanup commands, and can run on Windows, macOS, and Linux.
# Install via PowerShell Gallery
Install-Module -Name AtomicRedTeam -Scope CurrentUser
# Verify installation
Get-Module AtomicRedTeam
# For administrator-level use
Set-ExecutionPolicy -ExecutionPolicy Bypass -Scope Process -Force
Import-Module AtomicRedTeam
# Clone repository
git clone https://github.com/redcanaryco/atomic-red-team.git
cd atomic-red-team
# Set execution policy
Set-ExecutionPolicy -ExecutionPolicy Bypass -Scope Process
# Import module
Import-Module .\atomic-red-team\Public\Invoke-AtomicTest.ps1
# Install via pip
pip install atomic-red-team
# Or clone repository
git clone https://github.com/redcanaryco/atomic-red-team.git
cd atomic-red-team
# Install Python dependencies
pip install -r requirements.txt
# Make executable
chmod +x ./atomic-red-team.py
# Install Homebrew formula (if available)
brew tap redcanaryco/homebrew-formula
brew install atomic-red-team
# Or install via pip
pip3 install atomic-red-team
# Pull pre-built Atomic Red Team container
docker pull redcanaryco/atomic-red-team:latest
# Run atomic tests in container
docker run --rm -it redcanaryco/atomic-red-team:latest
# Mount local directory
docker run -v /path/to/atomics:/atomics redcanaryco/atomic-red-team:latest
| Component | Description | Example |
|---|
| Technique ID | MITRE ATT&CK ID | T1059 (Command and Scripting Interpreter) |
| Atomic Test | Individual test for technique | T1059.001 (PowerShell execution) |
| Test Name | Human-readable description | Execute PowerShell script inline |
| Prerequisites | Dependencies that must exist | PowerShell available, admin rights |
| Executor | Platform/runtime for test | command_prompt, powershell, bash, sh |
| Commands | Steps to execute attack | echo/write-host payload, execute |
| Cleanup | Restore system to original state | Remove created files, kill processes |
Each atomic test maps to specific MITRE ATT&CK techniques:
Tactic (e.g., Execution)
└─ Technique (e.g., T1059 Command and Scripting Interpreter)
└─ Sub-technique (e.g., T1059.001 PowerShell)
└─ Atomic Tests (5-10 small tests per sub-technique)
# Import module
Import-Module AtomicRedTeam
# List all available tests
Get-AtomicTechnique
# List tests for specific technique
Get-AtomicTechnique -Technique T1059
# Get details about specific test
Get-AtomicTechnique -Technique T1059 | Select-Object -ExpandProperty 'atomic_tests'
# Filter by platform
Get-AtomicTechnique | Where-Object {$_.platform -contains "windows"}
# Search by name
Get-AtomicTechnique | Where-Object {$_.display_name -like "*Command*"}
# Import library
from atomic_red_team import AtomicRedTeam
# Initialize
art = AtomicRedTeam()
# List all techniques
all_tests = art.get_all_techniques()
print(all_tests)
# Get specific technique
t1059_tests = art.get_technique('T1059')
# List by platform
windows_tests = art.get_by_platform('windows')
# Get test details
details = art.get_technique_details('T1059.001')
# List all tests
atomic-red-team list
# List specific technique
atomic-red-team list -t T1059
# Get test metadata
atomic-red-team info -t T1059.001
# Search tests
atomic-red-team search --keyword "PowerShell"
# Filter by platform
atomic-red-team list --platform windows
# Run single test
Invoke-AtomicTest -Technique T1059 -TestNumber 1
# Run all tests for technique
Invoke-AtomicTest -Technique T1059
# Run with verbose output
Invoke-AtomicTest -Technique T1059 -Verbose
# Dry-run (show commands without executing)
Invoke-AtomicTest -Technique T1059 -DryRun
# Specify exact test
Invoke-AtomicTest -Technique T1059.001 -Atomic "Execute PowerShell script inline"
# Execute test
from atomic_red_team import AtomicRedTeam
art = AtomicRedTeam()
result = art.run_test('T1059.001', test_number=1)
# Check result
print(result.status)
print(result.output)
# Run with parameters
params = {'CommandPath': 'C:\\Scripts\\malware.ps1'}
result = art.run_test('T1059.001', params=params)
# Run test in container
docker run --rm redcanaryco/atomic-red-team:latest \
Invoke-AtomicTest -Technique T1059 -TestNumber 1
# Mount host directory and run
docker run -v /tmp:/tmp redcanaryco/atomic-red-team:latest \
Invoke-AtomicTest -Technique T1003 -TestNumber 5
# T1059.001 - PowerShell
Invoke-AtomicTest T1059.001 -TestNumber 1
# T1059.003 - Windows Command Shell (cmd.exe)
Invoke-AtomicTest T1059.003
# T1059.004 - Unix Shell (bash/sh)
Invoke-AtomicTest T1059.004
# T1003.001 - LSASS Memory Dump
Invoke-AtomicTest T1003.001
# T1003.002 - SAM Database
Invoke-AtomicTest T1003.002
# T1003.005 - Cached Domain Credentials
Invoke-AtomicTest T1003.005
# T1053.005 - Windows Scheduled Task
Invoke-AtomicTest T1053.005
# T1053.006 - systemd Timer (Linux)
Invoke-AtomicTest T1053.006
# T1053.007 - cron (Linux/macOS)
Invoke-AtomicTest T1053.007
# T1566.002 - Phishing - Spearphishing Link
Invoke-AtomicTest T1566.002
# T1566.003 - Phishing - Spearphishing via Service
Invoke-AtomicTest T1566.003
# T1136.001 - Create Account (Local)
Invoke-AtomicTest T1136.001
# T1136.003 - Create Account (Cloud)
Invoke-AtomicTest T1136.003
# T1021.001 - Remote Service - RDP
Invoke-AtomicTest T1021.001
# T1021.002 - SSH
Invoke-AtomicTest T1021.002
# T1021.003 - WinRM
Invoke-AtomicTest T1021.003
# T1098.001 - Additional Cloud Credentials
Invoke-AtomicTest T1098.001
# T1098.002 - Add Office 365 Global Admin
Invoke-AtomicTest T1098.002
# Check if test prerequisites are met
Invoke-AtomicTest -Technique T1059 -CheckPrerequisites
# Get prerequisite details
$test = Get-AtomicTechnique -Technique T1059 | Select-Object -ExpandProperty atomic_tests
$test[0].input_arguments
| Prerequisite | Purpose | Example |
|---|
| Software installed | Tool/binary exists | PowerShell, Python, Mimikatz |
| File exists | Payload or script available | Malware sample, script file |
| Admin rights | Elevated privileges needed | UAC bypass, credential dumping |
| Network access | External connectivity | Download from URL |
| User account | Specific user required | Domain admin, service account |
# Run specific prerequisite setup
Invoke-AtomicTest -Technique T1003 -Prerequisites
# Install missing software (example: Mimikatz)
# Download from: https://github.com/gentilkiwi/mimikatz/releases
# Place in known path for atomic tests to find
# Create test files
New-Item -Path "C:\temp\test.txt" -ItemType File
Atomic tests are defined in YAML format. Create custom tests:
---
attack_technique: T1059.001
display_name: Custom PowerShell Test
atomic_tests:
- name: Custom PowerShell Execution
description: Execute custom PowerShell command
supported_platforms:
- windows
input_arguments:
command_string:
description: PowerShell command to execute
type: string
default: Write-Host "Custom Atomic Test"
executor:
name: powershell
elevation_required: false
command: |
{{ command_string }}
cleanup_command: |
Write-Host "Cleanup completed"
# Specify custom directory
$CustomPath = "C:\custom_atomics"
Invoke-AtomicTest -Technique T1059.001 -AtomicsFolder $CustomPath
# Or add to default location
# %USERPROFILE%\Documents\Atomic Red Team\
# Copy custom YAML files there
Every atomic test includes cleanup commands to restore system state:
# View cleanup commands for test
Get-AtomicTechnique -Technique T1059.001 | Select-Object -ExpandProperty cleanup_command
# Example output:
# Remove-Item -Path C:\temp\payload.exe -Force
# Stop-Process -Name notepad -Force
# Execute cleanup for specific test
Invoke-AtomicTest -Technique T1059.001 -TestNumber 1 -Cleanup
# Run cleanup without running test
Invoke-AtomicTest -Technique T1059.001 -Cleanup -DryRun
# Manual cleanup
Remove-Item -Path C:\temp\* -Force
Stop-Process -Name powershell -Force
Get-ScheduledTask -TaskName "AtomicTest*" | Unregister-ScheduledTask -Force
# Capture output to variable
$result = Invoke-AtomicTest -Technique T1059.001 -TestNumber 1
# Log to file
Invoke-AtomicTest -Technique T1059.001 | Out-File -FilePath "atomic_results.txt" -Append
# Detailed logging
$VerbosePreference = "Continue"
Invoke-AtomicTest -Technique T1059.001 -Verbose | Out-File "detailed_log.txt"
# Run multiple techniques and collect results
$techniques = @('T1059.001', 'T1003.001', 'T1053.005')
$report = @()
foreach ($technique in $techniques) {
$result = Invoke-AtomicTest -Technique $technique -DryRun
$report += [PSCustomObject]@{
Technique = $technique
Status = $result.Status
Output = $result.Output
Time = Get-Date
}
}
# Export to CSV
$report | Export-Csv -Path "atomic_report.csv" -NoTypeInformation
# Run atomic test to generate telemetry
Invoke-AtomicTest -Technique T1003.001
# Monitor logs during test execution (separate terminal)
Get-WinEvent -LogName Security | Where-Object {$_.TimeCreated -gt (Get-Date).AddSeconds(-10)}
# Check Sysmon logs
Get-WinEvent -LogName "Sysmon/Operational" | Where-Object {$_.TimeCreated -gt (Get-Date).AddSeconds(-10)}
# Parse results
Get-WinEvent -LogName Security |
Where-Object {$_.ID -eq 4688} | # Process creation
Select-Object TimeCreated, Message
| Step | Action | Command |
|---|
| 1 | Identify technique | Get-AtomicTechnique T1059 |
| 2 | Enable logging | Configure Sysmon, Process Monitor |
| 3 | Run atomic test | Invoke-AtomicTest T1059.001 |
| 4 | Collect telemetry | Event logs, Sysmon logs |
| 5 | Validate detection | Check SIEM/logging system |
| 6 | Refine rules | Update detection signatures |
# Run single test (fast)
Invoke-AtomicTest -Technique T1059.001 -TestNumber 1
# Dry-run for quick preview
Invoke-AtomicTest -Technique T1059.001 -DryRun
# Measure execution time
Measure-Command {
Invoke-AtomicTest -Technique T1059.001 -TestNumber 1
}
# Run multiple techniques
$techniques = Get-AtomicTechnique | Where-Object {$_.platform -contains "windows"}
foreach ($technique in $techniques) {
Write-Host "Running: $($technique.technique_id)"
Invoke-AtomicTest -Technique $technique.technique_id -TestNumber 1
Start-Sleep -Seconds 5 # Stagger tests
}
# T1059 - Command execution
Invoke-AtomicTest T1059.001 # PowerShell
Invoke-AtomicTest T1059.003 # cmd.exe
# T1047 - WMI Command Execution
Invoke-AtomicTest T1047
# T1053 - Scheduled tasks
Invoke-AtomicTest T1053.005
# T1110 - Brute Force
Invoke-AtomicTest T1110.001
# T1187 - Forced Authentication
Invoke-AtomicTest T1187
# T1056 - Input Capture
Invoke-AtomicTest T1056.004
# T1021 - Remote Service Session Initiation
Invoke-AtomicTest T1021.001 # RDP
Invoke-AtomicTest T1021.003 # WinRM
# T1570 - Lateral Tool Transfer
Invoke-AtomicTest T1570
# T1547 - Boot or Logon Autostart Execution
Invoke-AtomicTest T1547.001
# T1136 - Create Account
Invoke-AtomicTest T1136.001
# T1546 - Event Triggered Execution
Invoke-AtomicTest T1546.015
| Issue | Cause | Solution |
|---|
| ”Not running as admin” | Elevated privileges required | Run PowerShell as Administrator |
| ”Prerequisites not met” | Missing dependencies | Run prerequisite setup or install software |
| ”Technique not found” | Wrong technique ID format | Verify ID (e.g., T1059.001 not T1059.1) |
| “Module not found” | AtomicRedTeam not imported | Import-Module AtomicRedTeam |
| ”DLL error” | Windows API unavailable | Install required Windows SDK |
# Enable verbose output
$VerbosePreference = "Continue"
Invoke-AtomicTest -Technique T1059.001 -Verbose
# Check prerequisites in detail
Invoke-AtomicTest -Technique T1003 -CheckPrerequisites -Verbose
# Dry-run to see commands without executing
Invoke-AtomicTest -Technique T1059.001 -DryRun
| Practice | Reason | Implementation |
|---|
| Test in isolated environment | Prevent accidental impact | Use lab VM or sandbox |
| Enable logging first | Capture activity for analysis | Enable Sysmon, Event logs |
| Communicate with team | Prevent false alarms | Notify security ops before testing |
| Review cleanup commands | Ensure proper restoration | Run cleanup after each test |
| Use DryRun mode | Verify commands before execution | -DryRun flag |
# Start Sysmon driver before testing
# Download from: https://docs.microsoft.com/en-us/sysinternals/downloads/sysmon
# Enable Process Creation auditing
auditpol /set /subcategory:"Process Creation" /success:enable
# Enable Command Line auditing (Windows 10+)
# Group Policy: Computer Configuration > Administrative Templates >
# System > Audit Process Creation > Include command line in process creation events
# Check logs after running atomic test
Get-WinEvent -LogName Security -FilterXPath "*[System[(EventID=4688)]]" -MaxEvents 10
| Resource | URL | Purpose |
|---|
| GitHub Repository | github.com/redcanaryco/atomic-red-team | Official source code |
| MITRE ATT&CK | attack.mitre.org | Technique framework reference |
| Documentation | atomicredteam.io | Official docs & tutorials |
| Slack Community | #atomic-red-team | Community support |
| Purple Team Guide | purpleteaming.org | Purple team best practices |
# Run test with custom input parameters
Invoke-AtomicTest -Technique T1059.001 `
-InputArgument @{command_string = "whoami"}
# Multiple parameters
Invoke-AtomicTest -Technique T1003.001 `
-InputArgument @{
dump_path = "C:\temp\lsass.dmp"
tool = "rundll32"
}
# Execute multiple related tests
$technique_chain = @(
@{Technique = 'T1003.001'; Name = 'Credential Dump'},
@{Technique = 'T1059.001'; Name = 'Execute Command'},
@{Technique = 'T1053.005'; Name = 'Persist via Scheduled Task'}
)
foreach ($test in $technique_chain) {
Write-Host "Running: $($test.Name)"
Invoke-AtomicTest -Technique $test.Technique -TestNumber 1
Start-Sleep -Seconds 5
}
# Count total available tests
(Get-AtomicTechnique).Count
# Count tests by platform
Get-AtomicTechnique |
ForEach-Object {$_.platform} |
Group-Object |
Select-Object Name, Count
# Find most coverage techniques
Get-AtomicTechnique |
Sort-Object @{Expression = {$_.atomic_tests.count}} -Descending |
Select-Object technique_id, display_name, @{Name="TestCount"; Expression = {$_.atomic_tests.count}} |
Head -20
