The AtomicTestHarnesses PowerShell module contains a suite of tools for simulating attack techniques. It is designed to be used on its own or as a dependency for Atomic Red Team tests. AtomicTestHarnesses is designed to run on PowerShell version 5 and above.
Have you ever been asked the question and been held accountable to answer the following? "Do we detect attack technique X?" If so, you may be familiar with the initial level of discomfort involved in not knowing how to confidently answer that question. In order to tackle such a potentially broadly-scoped question, at Red Canary, one of our first questions will be, "can we see the technique in the first place independent of benign, suspicious, or malicious behaviors?" In order to "see" techniques, one would ideally have a handle on as many variants of a technique as possible and to then build test code that can exercise all those variants in a repeatable and modular fashion. Implementation of all known technique variations in an abstracted and repeatable fashion is the niche that AtomicTestHarnesses aims to fill. If you can observe all known technique variations, then you've laid a foundation to detect behaviors that employ a technique in a fashion that is resilient to evasion.
AtomicTestHarnesses is no different than any other PowerShell module. It can be installed from the PowerShell Gallery, as an auto-loaded module, or it can be manually imported.
AtomicTestHarnesses is available in the PowerShell Gallery. Installation from the PowerShell Gallery is the most straightforward installation method. Run the following:
Install-Module -Name AtomicTestHarnesses -Scope CurrentUserFor manual installation from GitHub, you can follow these steps. Installation via Install-Module handles these steps that follow.
To support auto-loading of the AtomicTestHarnesses module, the AtomicTestHarnesses folder must reside in a module directory. There are multiple module directories by default, each with their own scope, each one present in the %PSModulePath% environment variable. You can view the existing module directories with the following PowerShell code:
(Get-Item Env:\PSModulePath).Value.Split(';')For example, if you wanted to install the module for all users, you would copy the AtomicTestHarnesses root directory to %ProgramFiles%\WindowsPowerShell\Modules
Upon copying the AtomicTestHarnesses root directory to the desired module path, you can begin using the exported functions right away without having to call Import-Module.
Rather than placing the AtomicTestHarnesses root directory in a module path, it can be directly imported regardless of where it resides by calling Import-Module on the module PSD1 file. Example:
Import-Module C:\Users\Test\Desktop\AtomicTestHarnesses\AtomicTestHarnesses.psd1The -SkipPublisherCheck and -Force option is typically required for machines that only have v3.4.0 of Pester installed. That particular version of the module was signed by Microsoft to be shipped in-box, which is not the case for later versions which are community maintained and signed with a different certificate. Attempting to install the module without that option may fail.
Upon the AtomicTestHarnesses module being loaded, to get a sense of what functionality is exposed, you can run the following command:
Get-Command -Module AtomicTestHarnessesYou can then read the help documentation for each individual function with Get-Help:
Get-Help -Name Invoke-ATHHTMLApplication -FullIf AtomicTestHarnesses is downloaded as a Zip file you may get warnings prior to importing the module indicating that it was downloaded from the internet and may not be trustworthy. To unmark the module as having been downloaded from the internet, run the following:
Get-ChildItem -Path Path\To\AtomicTestHarnesses -Recurse | Unblock-FileAtomicTestHarnesses includes a suite of Pester tests that defenders can use to maximize their detection coverage by ensuring that they can, at a minimum, observe all established variants of a target attack technique.
The included Pester tests require Pester v5+.
Get-Module -ListAvailable -Name PesterIf you do not have Pester v5+, you will need to update it.
Install-Module -Name Pester -MinimumVersion 5.0.0 -Scope CurrentUserThe -SkipPublisherCheck and -Force option is typically required for machines that only have v3.4.0 of Pester installed. That particular version of the module was signed by Microsoft to be shipped in-box, which is not the case for later versions which are community maintained and signed with a different certificate. Attempting to install the module without that option may fail.
Specific groups of tests can be run rather than running all available tests. The following tags are exposed:
Module- Module-wide tests designed to ensure consistency across all exported functions.Unit- Unit tests for exported functionsTechnique- Tests that exercise specific attack technique functionalityT1055- Process InjectionT1055.002- Process Injection: Portable Executable InjectionT1059.001- Command and Scripting Interpreter: PowerShellT1127.001- Trusted Developer Utilities Proxy Execution: MSBuildT1134.004- Access Token Manipulation: Parent PID SpoofingT1218.001- Signed Binary Proxy Execution: Compiled HTML FileT1218- Signed Binary Proxy ExecutionT1218.005- Signed Binary Proxy Execution: MshtaT1574.012- Hijack Execution Flow: COR_PROFILER
To run AtomicTestHarnesses Pester tests, first cd into the AtomicTestHarnesses directory.
Execute module-wide consistency tests:
Invoke-Pester -Output Detailed -TagFilter ModuleRunning a suite of tests for one of the support MITRE ATT&CK Technique IDs:
Invoke-Pester -Output Detailed -TagFilter T1134.004Retrieving object output from passed tests:
$TestResults = Invoke-Pester -Output Detailed -TagFilter T1134.004 -PassThru
# These results are what you would likely want to submit to the next stage in your test pipeline.
$TestResults.Passed.StandardOutputNote: all Technique-tagged tests must output function object output so that returned objects can be programmatically retrieved.
Red Canary very much values community contributions! Currently, we are only able to consider pull requests for bug fixes. We are currently unable to accept pull requests for new test harness code until we feel a little more confident that we've educated the community on our design/implementation process. Thank you for your interest and time!