Invoke-AtomicRedTeam

Invoke-AtomicRedTeam is a PowerShell execution framework designed to run security tests defined in the Red Canary Atomic Red Team project. Tests are mapped directly to the MITRE ATT&CK™ Framework, where each technique has a corresponding folder (T#) containing a YAML declaration of test procedures and a human-readable Markdown equivalent.

This execution framework translates complex, structured test parameters into executable actions across multiple shells on Windows, macOS, and Linux platforms. It serves as an automation agent to test host configurations, endpoint detection and response (EDR) agents, security information and event management (SIEM) ingestion, and general telemetry capture capabilities.

Core Capabilities

  • Cross-Platform Support: Executes natively on Windows PowerShell 5.0+ and PowerShell Core (pwsh) on macOS and Linux.
  • Dependency Resolution: Checks system prerequisites and automatically downloads or configures required tooling before test execution.
  • Parametrization: Allows passing of custom input variables to modify how tests run on target systems.
  • Remote Execution: Supports executing atomic tests on remote endpoints via PowerShell Remoting (PSSession).
  • Modular Logging: Standardizes telemetry generated by test execution using built-in or custom loggers, such as CSV, Attire JSON, Syslog, or Windows Event Logs.
  • Automated Continuous Running: Provides a framework to sequence multiple atomic tests, automatically renaming hostnames to mimic individual test environments and isolation spaces.

Why Use This Execution Framework?

Manual execution of threat replication scripts is prone to human error and difficult to scale across multiple systems. Invoke-AtomicRedTeam provides a programmatic, repeatable approach to threat emulation. This allows security teams to:

  • Validate that security tools and logging agents are collecting expected telemetry.
  • Verify detection rules and alert logic under realistic, controlled conditions.
  • Incorporate security regression testing into CI/CD pipelines to monitor security posture changes.
  • Automate test scheduling and reporting to identify coverage gaps over time.

Core Architecture

The project maintains a decoupled structure. The execution engine (Invoke-AtomicRedTeam) is responsible for parsing YAML test schemas, verifying prerequisites, substituting runtime variables, and executing commands within the target shell. The test payloads (contained within the atomics folder) remain separate, allowing independent updates to the test suite without modifications to the engine.

To learn more about setting up the framework and downloading these resources, refer to the Installation Guide. Once the environment is ready, the Quick Start Guide details how to run a basic test, and the Usage Guide explains more complex configuration options.

Safe Emulation Practices

Adversary emulation can perform system-modifying operations. To prevent unintended operational impact, adhere to the following guidelines:

  • Telemetry Mapping: Verify that security log collection (such as Sysmon, EDR agents, and SIEM forwarders) is active and properly configured before starting tests. This ensures that test activity generates usable telemetry.
  • Isolated Environments: Execute tests inside dedicated lab networks, sandboxes, or virtual environments that replicate production templates. Avoid running invasive or destructive tests on active production assets.
  • Verification: Match the execution timestamps recorded by the framework's logging engines against security consoles to confirm detection or identify telemetry gaps. Detailed logging parameters are described in the Execution Logging section.

For continuous testing across multiple host systems, see the Automated Runner page.