Invoke-Atomic leaves the nest

Atomic Red Team is a collection of scripted cyber attacks that are designed to emulate adversary behaviors and threat techniques on an endpoint. After its initial commits landed on GitHub in October 2017, the project quickly emerged as an effective tool for testing detection coverage and validating security controls and configurations. However, for the first year of Atomic Red Team’s life, testing was a labor-intensive and largely manual process.

Recognizing that security professionals and enthusiasts needed an easier way to run atomic tests, Atomic Red Team contributors started developing a PowerShell framework for executing tests in September 2018, naming it “Invoke-AtomicRedTeam.” In doing so, they vastly simplified the process for verifying that your security tooling is actually working and learning what “malicious” looks like.

In the year-and-a-half that followed the release of Invoke-Atomic, Carrie Roberts, Matt Graeber, and Tony Lambert joined Michael Haag as maintainers of the project, and what started as a framework for test execution has become a lot more than that.

In February 2020, we decided to make Invoke-Atomic its own open source project. In spirit, Invoke-Atomic is still very much a part of Atomic Red Team, but, in the interest of making it easier for the community to contribute to its continued evolution, we decided that the two projects should be functionally separate.

What’s new with Invoke-Atomic?

As we said, Invoke-Atomic has grown into much more than the PowerShell-based execution framework that first emerged in 2018, so we want to celebrate the re-launch of Invoke-Atomic by highlighting a few new features that we find particularly interesting and useful.

Cross platform support

Invoke-Atomic has always worked on Windows, but recent improvements to the framework mean that it will also work in macOS and Linux systems. That said, if you want to test on macOS or Linux, you’ll have to install PowerShell Core first.

New-Atomic

Historically, if you wanted to create a new atomic test, you had to manually write out the entire YAML file. This was a serviceable method for generating new tests, but it was also highly repetitive—and error prone.

The New-Atomic feature lends some automation to the process and removes some of the drudgery of test creation by pre-populating much of the YAML file with contents that are largely static across tests. In addition to streamlining new test creation, contributors can use New-Atomic to generate new Atomic techniques, dependencies, and arguments.

Install execution framework only

One of the core benefits of divorcing Invoke-Atomic from the broader Atomic Red Team project is that you can now install just the execution framework. This means that you don’t need to locally install every atomic test on your machine, and, therefore, you won’t need to install the many hundreds of Atomic Red Team files that can and will (and probably should) trigger alerts from your antivirus and other prevention and detection controls.

IEX (New-Object Net.WebClient).DownloadString('https://raw.githubusercontent.com/redcanaryco/invoke-atomicredteam/master/install-atomicredteam.ps1')
Install-AtomicRedTeam

CheckPrereqs/GetPrereqs

Many atomic tests require the installation of certain third-party software in order to work. We call these “prerequisites.” In the past, testers would have to look for prerequisites in each test file and then install any third-party tools manually.

Now, Invoke-Atomic supports the ability to check if the system you’re running a test on has the necessary prerequisites installed. If it doesn’t, then you can run the GetPrereqs command to actually install any requisite third-party tooling.

For example, one of the atomic tests for Data Destruction (T1485) emulates an adversary overwriting system files with a Sysinternals application called SDelete (Secure Delete). In order to execute that test, the system must have the application installed, so CheckPrereq checks if it’s present and GetPrereq installs it if it isn’t.

In this short video, we attempt to run an atomic test that emulates an adversary using ProcDump to dump the memory of lsass.exe. The test fails because ProcDump is not installed in the test environment. Running the -CheckPrereqs command confirms the reason for this test failure. We then run the -GetPrereqs command, which installs ProcDump. Finally, we run the test again, and it executes properly.

Execute atomic tests (remote)

Atomic Red Team testing has applied most readily to local testing. You install security tools on a machine you have access to—virtual or otherwise—and you execute some tests to see if everything is working as advertised or expected. This is useful for validating assumptions about telemetry, ensuring things are configured correctly, or learning about threats in the perfect laboratory environment that you instrumented yourself.

Unfortunately, adversaries don’t target perfect laboratory environments. They target employee workstations and active servers, so, ideally, you want to be able to run tests on different machines (and different kinds of machines) across your environment.

Of course, it’s always been possible to execute tests remotely, but doing so has been a manual, ad hoc process. Invoke-Atomic now includes a feature that leverages PowerShell Remoting sessions and allows anyone to remotely execute tests from one machine to another.

Cleanup

When you execute certain atomic tests, they install temporary files or other artifacts on the system you’re testing. It’s possible that file or configuration changes could leave machines in a less desirable or even less secure state. As such, many tests include clean-up commands that work to revert a machine to its pre-test state.

This video shows the execution of an atomic test that emulates an adversary using the Windows registry to dump security account manager (SAM), cached credentials, and Local Security Authority (LSA) secrets. After successful execution, we show that certain artifacts remained on the system. We then run the -Cleanup command and check for the artifacts again, but they are now gone.

Other noteworthy improvements

Another new feature allows testers to configure timeouts for atomics that don’t immediately return, so that a scripted test execution won’t wait indefinitely for something like user input. Invoke-Atomic will also automatically write execution details to a CSV so that you can readily compare your test results to your detection logs. It’s also much easier now to enhance atomic tests with custom arguments at run-time by using the -PromptForInputArgs parameter—or this process can be used to execute unattended tests by using the -InputArgs parameter.

Conclusion

These are just a handful of new features associated with Invoke-Atomic. The Atomic Red Team maintainers have emphasized improving the execution framework in recent months, and various community members have been contributing as well.

We’ve got big plans for improving Atomic Red Team and Invoke-Atomic and growing the open source communities around them, so expect to see a bevy of new and interesting features added to the frameworks in the coming weeks and months.

Beyond that, we’re working on generating a ton of interactive and educational content for Invoke-Atomic and Atomic Red Team, so please follow the Red Canary blog and Twitter for this and other useful security resources. You can also bookmark Invoke-Atomic resources and Atomic Red Team resources to find our newest and most popular articles and videos.

If you’d like to join the Atomic Red Team or Invoke-Atomic community, the good news is that they hang out in the same Slack channel!  If you’d like to contribute, you can learn more about that process here.