Programmatic Test Authoring

Rather than manually drafting complex, error-prone YAML documents, Invoke-AtomicRedTeam provides functions to generate and serialize valid Atomic Red Team test configurations programmatically.

Core Generator Pipeline

The authoring suite uses the object schemas declared in Private/AtomicClassSchema.ps1 to construct, validate, and convert PowerShell instances into standardized YAML documents.

[New-AtomicTestInputArgument] -
                              |-> [New-AtomicTest] -> [New-AtomicTechnique] -> [ConvertTo-Yaml]
[New-AtomicTestDependency] ----

Generation Script Example

The following script creates a complete multi-test technique declaration for T1118 (InstallUtil), enforces argument validation, registers execution commands, and writes the output file:

# 1. Define reusable input arguments
$inputArg1 = New-AtomicTestInputArgument `
    -Name "filename" `
    -Description "Target location of the compiled test payload DLL" `
    -Type "Path" `
    -Default "PathToAtomicsFolder\T1118\src\T1118.dll"

$inputArg2 = New-AtomicTestInputArgument `
    -Name "source_code" `
    -Description "Target location of the C# source code template" `
    -Type "Path" `
    -Default "PathToAtomicsFolder\T1118\src\T1118.cs"

# 2. Define dependencies
$dependency1 = New-AtomicTestDependency `
    -Description "The C# compiler csc.exe must exist on the system" `
    -PrereqCommand "where csc.exe" `
    -GetPrereqCommand "Write-Host 'Install the .NET Framework developer pack to obtain csc.exe'"

# 3. Assemble automated test case #1 (Uninstall call execution)
$test1 = New-AtomicTest `
    -Name "InstallUtil Uninstall Method Call Execution" `
    -Description "Compiles and executes assembly uninstallation payloads via InstallUtil.exe" `
    -SupportedPlatforms "Windows" `
    -InputArguments @($inputArg1, $inputArg2) `
    -ExecutorType "CommandPrompt" `
    -ExecutorCommand @'
C:\Windows\Microsoft.NET\Framework\v4.0.30319\csc.exe /target:library /out:#{filename} #{source_code}
C:\Windows\Microsoft.NET\Framework\v4.0.30319\InstallUtil.exe /logfile= /LogToConsole=false /U #{filename}
'@ `
    -ExecutorCleanupCommand "del #{filename}" `
    -Dependencies @($dependency1)

# 4. Assemble automated test case #2 (Help property call execution)
$test2 = New-AtomicTest `
    -Name "InstallUtil Help Flag Inquiry" `
    -Description "Queries installer help parameters to trigger core initialization steps" `
    -SupportedPlatforms "Windows" `
    -InputArguments @($inputArg1, $inputArg2) `
    -ExecutorType "CommandPrompt" `
    -ExecutorCommand @'
C:\Windows\Microsoft.NET\Framework\v4.0.30319\csc.exe /target:library /out:#{filename} #{source_code}
C:\Windows\Microsoft.NET\Framework\v4.0.30319\InstallUtil.exe /? #{filename}
'@ `
    -ExecutorCleanupCommand "del #{filename}" `
    -Dependencies @($dependency1)

# 5. Package into an Atomic Technique collection
$technique = New-AtomicTechnique `
    -AttackTechnique "T1118" `
    -DisplayName "InstallUtil" `
    -AtomicTests @($test1, $test2)

# 6. Serialize the technique object directly into YAML
$technique | ConvertTo-Yaml | Out-File "C:\AtomicRedTeam\atomics\T1118\T1118.yaml"

Key Validation Rules Handled Automatically

• Naming Conventions: Names are converted to lowercase. The engine warns if AttackTechnique values do not match the expected TNNNN pattern.
• Input Parameter Matching: Validates that all variables referenced as # {argument_name} within commands are defined in the InputArguments list. It also warns if an input variable is declared but never used inside the executor strings.
• Executor Constraints: Restricts parameters to supported platforms (Windows, macOS, Linux) and executor types (command_prompt, sh, bash, powershell).

Developer Guidelines

• Atomic Scope: Design each test to carry out a single discrete action. Complex multi-stage actions are harder to troubleshoot and log accurately.
• Explicit Cleanup: Ensure every registry modify, file write, or process generation is paired with an explicit cleanup command to avoid leaving test artifacts behind.
• Validate YAML Syntax: Run the schema verification tools on your newly authored YAML configurations before submitting them to the community definitions folders.

To view parameter types and method signatures of the creation cmdlets, see the API Reference. To contribute your tests back to the project, review the Contributing & Development guidelines.