Usage Guide

The primary interface of the framework is the Invoke-AtomicTest cmdlet. This guide details target selections, parameter passing, and execution modes.

Selecting Targets

You can isolate techniques, specific test lists, names, or unique identifiers (GUIDs).

Running Specific Test Indices

If a technique has multiple tests, isolate execution to specific tests using the -TestNumbers parameter:

# Executes only test 1 and test 3
Invoke-AtomicTest T1059 -TestNumbers 1, 3

Filtering by Name or GUID

You can filter tests dynamically by name or using their auto-generated GUID definitions. This provides stability when writing automation scripts because test indexes can change when tests are added or removed upstream:

# Execute by Name match
Invoke-AtomicTest T1059 -TestNames "Powershell Spawning Cmd"

# Execute by GUID match
Invoke-AtomicTest T1059 -TestGuids "8f492621-18f8-432e-9532-b1d54d3e90bd"

Running All Available Tests

To run all tests across all techniques defined within your atomics folder, use the All parameter:

Invoke-AtomicTest All

Note: Running all tests can result in significant changes to host configuration. A warning prompt will ask for confirmation before executing unless the -Force flag is specified.

Customizing Test Arguments

Atomics declare input_arguments with default values inside their YAML files. You can modify these values during execution using a PowerShell hashtable passed to the -InputArgs parameter.

For example, if a test runs a binary from a default path, override that location to target a staging directory:

$customArgs = @{
    "output_file" = "C:\Windows\Temp\custom_telemetry.bin"
    "user_account" = "Administrator"
}

Invoke-AtomicTest T1003 -TestNumbers 1 -InputArgs $customArgs

Interactive Argument Prompting

If you are unsure of the variable options, run the cmdlet with -PromptForInputArgs to step through each setting in the terminal interface:

Invoke-AtomicTest T1003 -TestNumbers 1 -PromptForInputArgs

Execution Contexts & Orchestration

Interactive vs Non-Interactive Execution

By default, the process runner captures stdout and stderr to write files like art-out.txt and art-err.txt under the scratch directory, keeping the terminal display structured.

If a test requires manual input mid-execution (e.g., interactive command prompt prompts), execute with the -Interactive switch to let streams flow directly into the host shell:

Invoke-AtomicTest T1059 -TestNumbers 1 -Interactive

Timeouts

Avoid execution hanging indefinitely from a misconfigured test. Specify maximum runtime thresholds using the -TimeoutSeconds parameter (defaults to 120 seconds):

Invoke-AtomicTest T1003 -TimeoutSeconds 45

Remote Execution via PSSession

Run tests on remote endpoints by passing open PowerShell Remoting sessions to the -Session parameter. The module staging files, prerequisite steps, and execution command suites run on the target session host:

# Establish remoting context
$session = New-PSSession -ComputerName "target-endpoint.corp.local"

# Execute remote technique test
Invoke-AtomicTest T1053 -TestNumbers 2 -Session $session

# Tear down remoting context
Remove-PSSession $session

Ensure that WinRM is enabled on the target host and that you possess the necessary administrative permissions to run commands remotely.

Common Pitfalls

  • Elevation Errors: Many atomic tests attempt actions that require administrator or root privileges. If a test fails silently or returns an access denied error, confirm your shell elevation status.
  • Unresolved Placeholders: If custom input arguments are not supplied correctly, commands containing path parameters (like #{filename}) may fail to execute. Verify path variables exist before testing.
  • Missing Cleanup: Failing to run the -Cleanup step after testing can leave artifacts that flag administrative alerts or block subsequent test runs.

To view global configuration variables, refer to Configuration. To see how execution data is saved, consult Execution Logging.