Quick Start Guide

This guide describes how to import the module, inspect atomic tests, satisfy system dependencies, execute a test, and clean up the system afterwards.

Step 1: Import the Module

Before running any commands, import the framework module into your current PowerShell session. If you installed it to the default directory, use:

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

Note: Replace C:\AtomicRedTeam with $HOME/AtomicRedTeam if running on Linux or macOS. See the Installation Guide for configuration requirements.

Step 2: Listing and Inspecting Tests

We will use Technique T1003 (OS Credential Dumping) as an example. First, view a brief listing of the tests defined under this technique:

Invoke-AtomicTest T1003 -ShowDetailsBrief

This will output a summary list of the tests associated with the technique:

Path to atomics: C:\AtomicRedTeam\atomics

T1003 OS Credential Dumping
  1. Registry dump of SAM, SYSTEM, and SECURITY hives
  2. Dump LSASS with procdump
  3. Dump LSASS with comsvcs.dll

To view in-depth details of each test, including the exact command execution payloads, prerequisites, and cleanup instructions, run:

Invoke-AtomicTest T1003 -ShowDetails

This displays the complete metadata structure of the technique including supported platforms, executor environments, and default values for input arguments.

Step 3: Run Prerequisite Checks

Atomic tests often require administrative access or specific tools (such as Sysinternals binaries, compiler tools, or text configurations) to run correctly. Run a check to verify if the machine satisfies the requirements for a specific test number (e.g., test #2):

Invoke-AtomicTest T1003 -TestNumbers 2 -CheckPrereqs

If the check reports missing prerequisites, attempt to automatically retrieve or configure them:

Invoke-AtomicTest T1003 -TestNumbers 2 -GetPrereqs

Note: Running -GetPrereqs may download third-party utilities from external sources. Inspect the source YAML files beforehand when operating in a restricted laboratory environment.

Step 4: Execute the Test

Run the test commands on your host system. Execution outputs and standard error responses will display in your console:

Invoke-AtomicTest T1003 -TestNumbers 2

The framework resolves any dynamic parameters and executes the underlying payload in the designated shell context (e.g., cmd, PowerShell, or bash).

Step 5: Clean Up System State

After executing an atomic test, wipe generated files, processes, or registry configurations from the host using the built-in cleanup parameter:

Invoke-AtomicTest T1003 -TestNumbers 2 -Cleanup

Practical Scenario

Here is a common workflow sequence when testing local scheduling mechanisms via T1053.005 (Scheduled Task):

# List tasks to identify relevant tests
Invoke-AtomicTest T1053.005 -ShowDetailsBrief

# Ensure dependencies are met
Invoke-AtomicTest T1053.005 -TestNumbers 1 -CheckPrereqs
Invoke-AtomicTest T1053.005 -TestNumbers 1 -GetPrereqs

# Execute test and generate telemetry
Invoke-AtomicTest T1053.005 -TestNumbers 1

# Revert system configurations
Invoke-AtomicTest T1053.005 -TestNumbers 1 -Cleanup

For more advanced runtime flags, such as targeting specific parameters or using remote targets, proceed to the Usage Guide.