The Atomic Runner functionality allows you to run a configurable list of atomic tests unattended in a way that aids prevention and detection reporting. The scripts are designed to run all the tests you have listed in the CSV schedule once per week by default. Before it runs each atomic test it appends the atomic test GUID to the end of the computer hostname. This makes it easier to determine which detections fired from which atomics because the hostname in the detection will include the GUID of the atomic test that was running at the time. The cleanup commands are run after atomic test execution as well.

This script works for Windows, Linux and macOS. You need to have PowerShell Core installed on Linux/macOS to use these scripts

Setup and Configuration

Install Atomic Red Team and Invoke-AtomicRedTeam

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

Note (Windows Only): Your Local Security Policy (Security Settings -> Local Polices -> Security Option) "Network Access: Do not allow storage of passwords and credentials for network authentication" must be disabled on your Atomic Runner to allow the scheduled task to be created.

Set custom config using privateConfig.ps1

There is a config file called config.ps1 in the <installFolder>\Invoke-AtomicRedTeam\Public folder. You can optionally modify any of the default values in this config file by creating a file called privateConfig.ps1 in the <installFolder>.

Table of default values:

Example privateConfig.ps1

$artConfig | Add-Member -Force -NotePropertyMembers @{
  PathToPrivateAtomics = "C:\MyPrivateAtomics\atomics"
  scheduleTimeSpan = New-TimeSpan -Days 1
  verbose = $true
  LoggingModule = "WinEvent-ExecutionLogger"
}

Note: You must start a new PowerShell window for any changes to the privateConfig file to take effect.

Run Invoke-SetupAtomicRunner

# Run Invoke-SetupAtomicRunner as the runner user (from admin prompt)
Invoke-SetupAtomicRunner

Note: On Windows, you will be prompted to enter the credentials of the user that will be running the atomics.

The setup script does the following:

1. If you configured a group managed service account (gMSA) for renaming the computer, a JEA endpoint will be created for renaming the computer using the gMSA account.
2. Creates a scheduled task called KickOff-AtomicRunner to keep the Runner running after a restart (or a cron job on Linux/macOS)
3. Adds an Import-Module statement to your PowerShell profile to load Invoke-AtomicRedTeam.psd1 automatically
4. Installs the Posh-SYSLOG module it is missing and you are configured to use it.
5. Creates a CSV schedule file listing all of the atomics in your atomics folders (public and private). All atomics will be disabled by default.
6. Runs the get_prereqs commands for all atomic tests that are enabled (active) on the schedule.

Enable atomic tests on the schedule file

Edit the schedule file to enable some atomics to run (these will all run every X minutes as calculated using the scheduleTimeSpan and the number of atomic tests enabled on your schedule). By default, the schedule will be located at <user-home-dir>\AtomicRunner\AtomcRunnerSchedule.csv

Example AtomicRunnerSchedule.csv files are found here (opens in a new tab).

Run Invoke-SetupAtomicRunner (again)

Run Invoke-SetupAtomicRunner (again) to get any prereqs for tests that you enabled on the schedule.

Restart the computer to kickoff the AtomicRunner process

The KickOff-AtomicRunner scheduled task

The KickOff-AtomicRunner scheduled task (or cronjob on Linux/macOS) calls the Invoke-AtomicRunner function after the computer restarts. It runs 1 minutes after reboot (with retries at 2,4,8,16,32 and 64 minutes if needed - Windows only). The KickOff-AtomicRunner script also handles log rotation for the Runner scripts.

The Invoke-AtomicRunner function

The Invoke-AtomicRunner function does the following:

1. Parses the Atomic GUID from the end of the computer hostname to know which atomic test it should run. If no GUID is found, it assumes it should run the first atomic test enabled on the schedule
2. Executes the atomic test specified by the GUID
3. Sleeps for an amount of time calculated from the scheduleTimeSpan and the number of atomic tests enabled on the schedule
4. Runs the cleanup commands for the atomic
5. Renames the computer to include the GUID of the next enabled test on the schedule and then reboots the computer

Runner logs

Additional logs are added to the AtomicRunner-logs folder in the home directory of the current user. Set the verbose and debug variables to $true in your privateConfi.ps1 file for maximum logging.

Refresh the schedule

As new atomics are added, removed, or edited in the Atomic Red team library, you may want to refresh your schedule. Refreshing the schedule will update the Atomic test name, technique and supported platforms for each test on the schedule, remove entries for atomic tests that have been removed, and add any new tests that aren't already on your schedule. Any new tests added to the schedule will be disabled by default, change the enabled value to True if you want it to be active.

# This will refresh the CSV schedule found in the user's home directory at AtomicRunner\AtomicRunnerSchedule.csv
Invoke-RefreshExistingSchedule

Stop the runner

A simple way to stop the atomic runner from it's continuous execution of atomics and rebooting you can simply add txt file called "stop" in the AtomicRunner folder. You can find the AtomicRunner folder in the basePath defined above, which is the current user's profile by default.