Getting Started

The Invoke-AtomicRedTeam Execution is available for install from the PowerShell Gallery and can be installed with one simple command executed from a PowerShell prompt:

Install-Module -Name invoke-atomicredteam,powershell-yaml -Scope CurrentUser

Register-PSRepository -Default

To install the execution framework without downloading it from the PowerShell Gallery as shown above, you can continue with the following instructions:

IEX (IWR 'https://raw.githubusercontent.com/redcanaryco/invoke-atomicredteam/master/install-atomicredteam.ps1' -UseBasicParsing);
Install-AtomicRedTeam

If you get an Import-Module error stating that the module "cannot be loaded because running scripts is disabled on this system", restart powershell using powershell -exec bypass or bypass execution policy with one of these methods and try again. Method 12 is especially promising.

If you use the Install-Module method, the module will be located in your default PowerShell modules folder and you won't need to manually import the module each time you start a new PowerShell Windows. Otherwise, if you install using Install-AtomicRedTeam, the installer will download and install the execution framework to <BASEPATH>\AtomicRedTeam

Where <BASEPATH> is C: in Windows or ~ in Linux/MacOS

Installing the execution framework (Invoke-AtomicRedTeam) does not download the repository of atomic test definitions by default (aka the Atomics Folder). This is because the atomics folder contains many files likely to trigger AV alerts on the endpoint. You may choose to white-list the install directory (<BASEPATH>\AtomicRedTeam by default) so that files are not quarantined or removed. Or you may choose to copy a version of the atomics folder over to the system that contains only the tests you intend to run.

If you get an error of "Could no create SSL/TLS secure channel." run the following PowerShell command before your run the install commands.

[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12

Install Execution Framework and Atomics Folder

The Atomics Folder contains the test definitions; the commands that the execution framework will execute. If you would like to install the atomics folder at the same time that you install the execution framework, you can do this by adding the -getAtomics switch during the install of the execution framework.

IEX (IWR 'https://raw.githubusercontent.com/redcanaryco/invoke-atomicredteam/master/install-atomicredteam.ps1' -UseBasicParsing);
Install-AtomicRedTeam -getAtomics

If the execution framework or the atomics folder are already found on disk you must use the -Force parameter during install as follows to erase and replace these folders.

IEX (IWR 'https://raw.githubusercontent.com/redcanaryco/invoke-atomicredteam/master/install-atomicredteam.ps1' -UseBasicParsing);
Install-AtomicRedTeam -getAtomics -Force

If you prefer to download the atomics folder with only the test definition yaml files and none of the payloads from the /src or /bin directories, use the -noPayloads flag as follows. You can use the -getPrereq flag with Invoke-AtomicTest to download the payloads for the atomics you choose to run.

IEX (IWR 'https://raw.githubusercontent.com/redcanaryco/invoke-atomicredteam/master/install-atomicredteam.ps1' -UseBasicParsing);
Install-AtomicRedTeam -getAtomics -Force -noPayloads

Install Atomics Folder Only

If you would like to install the atomics folder as a separate step or at a later time, you can do it with the Install-AtomicsFolder function as follows.

IEX (IWR 'https://raw.githubusercontent.com/redcanaryco/invoke-atomicredteam/master/install-atomicsfolder.ps1' -UseBasicParsing);
Install-AtomicsFolder

If you prefer to download the atomics folder with only the test definition yaml files and none of the payloads from the /src or /bin directories, use the -noPayloads flag as follows. You can use the -getPrereq flag with Invoke-AtomicTest to download the payloads for the atomics you choose to run.

IEX (IWR 'https://raw.githubusercontent.com/redcanaryco/invoke-atomicredteam/master/install-atomicsfolder.ps1' -UseBasicParsing);
Install-AtomicsFolder -noPayloads -Force

Optional Installation Parameters

Both the Install-AtomicRedTeam and the Install-AtomicsFolder functions have the following optional parameters:

InstallPath

• Where to install (default: C:\AtomicRedTeam on Windows or ~\AtomicRedteam on MacOS and Linux)

Install-AtomicRedTeam -InstallPath "c:\tools"
Install-AtomicsFolder -InstallPath "c:\tools"

Force

• Remove the previous installation before installing

Install-AtomicRedTeam -Force
Install-AtomicsFolder -Force

RepoOwner

• Install from another GitHub repo. Default RepoOwner is "redcanaryco"

Install-AtomicRedTeam -RepoOwner "clr2of8"
Install-AtomicsFolder -RepoOwner "clr2of8"

Branch

• Install from another branch. Default Branch is "master"

Install-AtomicRedTeam -RepoOwner "clr2of8" -Branch "start-process-branch"
Install-AtomicsFolder -RepoOwner "clr2of8" -Branch "start-process-branch"

To prepare for offline installation you should install Atomic Red Team on an online system of the same OS version where the offline install is to be done. This allows you to easily grab all of the needed files from the online system and move them to the offline system. The instructions below are specific to Windows but you can adjust to make it work on Linux/macOS as well.

Steps to take from the online system:

1. Install Atomic Red Team on the online system using the "from source" installation instructions.
2. Get the prereqs for all tests so you can copy as many as possible to the offline system. Use Invoke-AtomicTest All -GetPrereqs (preferably with AV disabled). You can skip\cancel any of the application installs because those won't copy over to the offline system.
3. Copy the following directories from the online system to the offline system:

• C:\AtomicRedTeam folder
• PowerShell powershell-yaml folder (from $HOME\Documents\PowerShell\Modules or $env:ProgramFiles\PowerShell\Modules)
• If you are using the non-default Syslog Execution logger you will need to grab a copy of the Posh-SYSLOG module in the same way you grabbed the powershell-yaml module.

Note: We are in the process of standardizing atomics that have external dependencies to download them into the AtomicRedTeam\ExternalPayloads folder. This has be completed for the Windows atomics but not the Linux\macOS atomics. In the latter case, you may need to grab several of the prereqs from the temp directory.

Note: It is recommended that you add an AV exclusion for the C:\AtomicRedTeam folder so that no files from the project are quarantined or deleted.

Steps to take from the offline system:

1. After copying the C:\AtomicRedTeam folder and the PowerShell module folder(s) from the online system to the offline system, dmke sure the file paths of the folders are the same on the offline system as the online. You should have a C:\AtomicRedTeam folder with three folders in it (atomics,ExternalPayloads, and invoke-atomicredteam). You should have a powershell-yaml folder at $HOME\Documents\PowerShell\Modules or $env:ProgramFiles\PowerShell\Modules

2. Import the Invoke-AtomicRedTeam module
3. From an administrative PowerShell prompt run Invoke-AtomicTest All -GetPrereqs which will set any configurations or install prerequisite software onto your offline system. For example, the Wireshark executable will have been downloaded as a prereq that you copied to the offline system but you still need to install it on the offline system.