Installation Guide

Invoke-AtomicRedTeam requires PowerShell 5.0 or higher. For macOS and Linux systems, PowerShell Core (pwsh) must be installed before installing the module framework.

Installing the environment involves downloading the execution engine module (Invoke-AtomicRedTeam) and, optionally, the definitions directory (atomics folder).

Prerequisites

Ensure your system meets the platform-specific requirements listed below before starting the installation process:

Operating System Minimum PowerShell Key Prerequisites
Windows Windows PowerShell 5.1 or PowerShell Core 6.0+ Elevated privileges, execution policy modifications
macOS PowerShell Core 7.0+ Homebrew (optional, for tool dependencies)
Linux PowerShell Core 7.0+ Package manager configuration (apt, yum, dnf)

Execution Policy Configuration (Windows)

On Windows, default execution policies prevent running downloaded scripts. Before installation, open an elevated PowerShell window and set the policy to allow local execution:

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope LocalMachine -Force

Automated Installation

The repository provides helper scripts to install the framework and the definitions folder with correct directory mappings.

Installing the Invoke-AtomicRedTeam Module

Run the following commands in an elevated PowerShell session to download the setup utility and run the installation:

# Download the helper utility from the repository
Invoke-WebRequest -Uri "https://raw.githubusercontent.com/redcanaryco/invoke-atomicredteam/master/install-atomicredteam.ps1" -OutFile "install-atomicredteam.ps1"

# Execute the setup script locally
.\install-atomicredteam.ps1

By default, the script will install the module in the following locations:

  • Windows: C:\AtomicRedTeam\invoke-atomicredteam
  • macOS/Linux: $HOME/AtomicRedTeam/invoke-atomicredteam

Customizing the Installation

Install-AtomicRedTeam exposes parameters to configure paths, repository branches, and dependencies:

# Example of installing to a custom folder and automatically downloading the atomics folder
Install-AtomicRedTeam -InstallPath "D:\SecurityTesting" -getAtomics -Force

Parameters Available:

  • -InstallPath: Base directory where the framework will be saved.
  • -DownloadPath: Scratch directory used to save intermediate ZIP archives during download (defaults to $InstallPath).
  • -RepoOwner: GitHub owner of the repository (defaults to redcanaryco).
  • -Branch: Target branch to download (defaults to master).
  • -getAtomics: Switch parameter that automatically triggers the atomic definitions download after the module is installed.
  • -Force: Re-installs by wiping the target installation directory if it already exists.
  • -NoPayloads: During an atomic definitions download, only saves the core YAML test declarations, skipping companion scripts, source directories, or pre-compiled binaries (/src and /bin).

Installing the Atomics Definitions Directory

If you installed the execution engine without the -getAtomics switch, or if you need to refresh your local verification suite separately, run the following helper:

# Download the folder installer script
Invoke-WebRequest -Uri "https://raw.githubusercontent.com/redcanaryco/invoke-atomicredteam/master/install-atomicsfolder.ps1" -OutFile "install-atomicsfolder.ps1"

# Run the installer locally
.\install-atomicsfolder.ps1

This executes Install-AtomicsFolder, downloading definitions from the separate atomic-red-team repository. The folder structure maps to:

  • Windows: C:\AtomicRedTeam\atomics
  • macOS/Linux: $HOME/AtomicRedTeam/atomics

Manual Installation

If the target testing machine does not have external internet connectivity, you can install the module manually:

  1. Download the invoke-atomicredteam repository as a ZIP archive from a machine with internet access.
  2. Extract the archive into a preferred directory (e.g., C:\AtomicRedTeam\invoke-atomicredteam).

  3. Install the required dependency module, powershell-yaml. For offline systems, download this module beforehand and copy it into one of your system's module folders, such as C:\Program Files\WindowsPowerShell\Modules\powershell-yaml: 

    # If online, run this to install dependency:
Install-Module -Name powershell-yaml -Scope CurrentUser -Force

  4. Import the module directly using its manifest path: 

    Import-Module "C:\AtomicRedTeam\invoke-atomicredteam\Invoke-AtomicRedTeam.psd1" -Force

Verification

To confirm the module is loaded and operational, check the exported cmdlets:

Get-Command -Module Invoke-AtomicRedTeam

If the cmdlets are visible, you are ready to proceed. For next steps on basic operations, consult the Quick Start Guide or see Configuration to adapt default paths.