Automated Runner & Scheduling

The Automated Runner framework allows continuous, hands-off execution of a scheduled queue of atomic tests. This allows testing multiple attack methods sequentially across reboots, with the option to isolate test runs using dynamic computer renaming.

Architecture and Workflow

  1. Schedule Generation: The runner parses active YAML techniques into a flat inventory saved in AtomicRunnerSchedule.csv.
  2. Isolating Environments via Host Renaming: To prevent test crossover artifacts or execution locks, the runner can rename the test system hostname to <basehostname>-<test_guid> and reboot.
  3. Post-Reboot Bootstrap: On system boot, a persistence mechanism (Service, Scheduled Task, or Cronjob) fires up the kickoff runner. The runner reads the local hostname, extracts the target test GUID, runs the matching scheduled atomic test, cleans up, renames the computer to the next scheduled test GUID, and reboots again.
[System Startup] -> [Read hostname for test GUID] -> [Run Test] -> [Wait / Cleanup] -> [Rename Host to Next GUID] -> [Reboot]

Setting Up the Runner

To set up execution infrastructure on your target platform, use Invoke-SetupAtomicRunner:

Invoke-SetupAtomicRunner

This executes several provisioning steps:

  1. Validates administrator privileges.
  2. Checks that the base hostname length is 15 characters or less (to prevent Windows ComputerName truncation errors).
  3. Automatically configures local persistence:
    • Windows (Service Mode - Default): Installs a compiled C# Windows Service (AtomicRunnerService.ps1) pointing to the local Powershell installation.
    • Windows (Scheduled Task Mode): Passes the -asScheduledtask flag to register a Task Scheduler entry named KickOff-AtomicRunner configured to launch on boot.
    • macOS/Linux: Configures a system crontab entry using @reboot running under root.
  4. Sets up PowerShell profile statements to auto-import the module in future sessions.
  5. Creates a fresh CSV schedule file if one does not exist.

Managing the Test Schedule

Use scheduling cmdlets to build and update the active queue:

Generate a New Schedule

Invoke-GenerateNewSchedule

This creates the CSV schedule file defined by $artConfig.scheduleFile (defaults to $HOME/AtomicRunner/AtomicRunnerSchedule.csv). The CSV lists all parsed atomic tests from your public and private directories. By default, the enabled column is marked False:

"Order","Technique","TestName","auto_generated_guid","supported_platforms","TimeoutSeconds","InputArgs","AtomicsFolder","enabled","notes"
,"T1003.001","LSASS Memory Dump","6f26cf94-4d8b-49ea-b97e-131758df634f","windows","120","","Public","False",

To schedule a test for execution, edit the CSV file and change the enabled column value to True.

Refreshing an Existing Schedule

If you pull new atomic test revisions from upstream repositories, run a refresh to import new test cases while maintaining existing configurations and column modifications:

Invoke-RefreshExistingSchedule

Running the Queue

Once your schedule contains enabled items, start automated execution with the primary runner function:

Invoke-AtomicRunner

To manually inspect, verify prerequisites, or run cleanup commands for all scheduled items sequentially without host renaming, pass the corresponding parameters:

# Run prerequisite validations for all enabled tests
Invoke-AtomicRunner -CheckPrereqs

# Satisfy dependencies for all enabled tests
Invoke-AtomicRunner -GetPrereqs

# Run cleanup commands for all enabled tests
Invoke-AtomicRunner -Cleanup

Common Pitfalls & Best Practices

  • Domain Disconnects: Hostname renaming can disrupt Active Directory domain trusts. Utilize renaming features only on workgroup machines or in standalone virtualization networks.
  • Hang Hazards: If a test hangs or presents a user prompt, the runner schedule will halt. Verify timeout variables are set or execute tests with appropriate limits.
  • Stale Files: If cleanup fails during an automated run, subsequent tests may be affected. Periodically clear the temporary folders or run a baseline reset between automation iterations.

For more details on output options, see Execution Logging. To return to global path variables, review Configuration.