Skip Navigation
Get a Demo
 
 
 
 
 
 
 
 
 
Resources Blog Testing and validation

Introducing Atomic Operator

Atomic Operator is the last cross-platform Atomic Red Team execution framework you’ll ever need.

Josh Rickard
Originally published . Last modified .

One of the major benefits of Atomic Red Team is that it enables security teams to understand how adversaries leverage MITRE® ATT&CK techniques in the real world, and I’ve been a big fan for years. To me, Atomic Red Team is more than a repository of tests (aka atomics), it’s also a knowledge base, training tool, and more.

Each atomic in the library simulates a known adversary behavior associated with a given technique. Each of these tests are meant to help security professionals understand how a technique works (in other words, what malicious looks like) and enable them to test their defensive controls.

Execution frameworks, new and old

Invoke-Atomic has been the de facto execution framework that many security teams use to test their security controls. In fact, many years ago I made what I believe was a significant contribution to the PowerShell-based execution framework. Invoke-Atomic is now maintained by some extremely talented developers, and I’ve continued to use it. However, as my development focus has shifted towards Python on a day-to-day basis, I’ve increasingly found myself wanting a Python-based execution framework—and so too has the rest of the Atomic Red Team community.

There was a prototype of a Python execution framework in the Atomic Red Team repository, until it was archived a little over a year ago. Ultimately, this framework was never really maintained by the Atomic Red Team community. Since this execution framework lacked support and features, I decided I would tackle the challenge of creating an execution framework in Python to help me test defensive controls across multiple operating systems.

When I started building this tool, I had a few things in mind that I wanted it to do. It needed to be able to:

  • execute atomics on any operating system
  • run those tests remotely against any operating system
  • run as both a command-line utility and a importable Python package
  • automate testing via a configuration file of some sort

atomic-operator

With these requirements in mind, I got to work. Now, four months later Swimlane and I are proud to announce the release of a new open-source project called atomic-operator. atomic-operator is a simple tool (run via command line or importable package) that helps security professionals test their defensive controls by running atomic tests locally or remotely across multiple operating systems.

By utilizing Python, atomic-operator is at home on macOS, *nix systems, and Windows as well. Since many security professionals are comfortable with Python 3 (3.6 >=), you get all the advantages of an execution framework in your preferred language.

Atomic Operator execution framework for Atomic Red Team

True to the requirements listed above, atomic-operator’s main features include:

  • local and remote execution of tests on Windows, macOS, and Linux systems
  •  atomic testing against AWS-hosted environments
  • optional prompting for input arguments
  • downloading the Atomic Red Team repository
  • test automation via a configuration file
  • test administration via a command-line utility and an importable Python package
  • much more!

How do I use this thing?!

To get started, you can install atomic-operator via PyPi by running pip install atomic-operator in your command shell. NOTE: You may need to modify your Python installation by ensuring that Python is in your environmental system path.

Alternatively, you can also clone the repository directly by executing the following commands in a command shell (assuming you have git installed):

# You must have git installed to clone repositories
git clone https://github.com/swimlane/atomic-operator.git
cd atomic-operator
python setup.py install

I highly recommend that you read atomic-operator’s documentation and check out its GitHub repository.

Once you have atomic-operator installed, you’ll want to ensure you have a local copy of the Atomic Red Team repository containing the atomics directory. If you do not have this on your local system, then you can run atomic-operator get_atomics in your favorite shell to download the repository.

If you already have the atomic-red-team repository on your system, then you can provide a path to that repo when you use the run command—more on that in a bit.

Besides the method above, there’s only one other direct interface and that is run. This interface is how you will run atomics locally or remotely. You can checkout the help by typing:

atomic-operator run -- --help
# be mindful of the double -- before --help

There are many parameters available when using the run command. Below is a simple list of the available options, but you can find more information about each one on the Atomic Operator homepage.

Parameter nameTypeDefaultDescription
Parameter name:

techniques

Type:

list

Default:

all

Description :

one or more defined techniques by attack_technique ID

Parameter name:

test_guids

Type:

list

Default:

none

Description :

one or more atomic test GUIDs

Parameter name:

atomics_path

Type:

str

Default:

os.getcwd()

Description :

The path of atomic tests

Parameter name:

check_prereqs

Type:

bool

Default:

false

Description :

whether or not to check for prereq dependencies (prereq_comand)

Parameter name:

get_prereqs

Type:

bool

Default:

false

Description :

whether or not you want to retrieve prerequisites

Parameter name:

cleanup

Type:

bool

Default:

false

Description :

whether or not you want to run cleanup command(s)

Parameter name:

copy_source_files

Type:

bool

Default:

false

Description :

whether or not you want to copy any related source (src, bin, etc.) files to a remote host

Parameter name:

command_timeout

Type:

int

Default:

true

Description :

time duration for each command before timeout

Parameter name:

debug

Type:

bool

Default:

20

Description :

whether or not you want to output details about tests being run

Parameter name:

prompt_for_input_args

Type:

bool

Default:

false

Description :

whether you want to prompt for input arguments for each test

Parameter name:

return_atomics

Type:

bool

Default:

false

Description :

whether or not you want to return atomics instead of running them

Parameter name:

config_file

Type:

str

Default:

false

Description :

a path to a config_file, which is used to automate atomic-operator in environments

Parameter name:

hosts

Type:

list

Default:

none

Description :

a list of one or more remote hosts to run a test on

Parameter name:

username

Type:

str

Default:

none

Description :

username for authentication of remote connections

Parameter name:

password

Type:

str

Default:

none

Description :

password for authentication of remote connections

Parameter name:

ssh_key_path

Type:

str

Default:

none

Description :

a path to a SSH Key for authentication of remote connections

 

Parameter name:

private_key_string

Type:

str

Default:

none

Description :

a private SSH key string used for authentication of remote connections

Parameter name:

verify_ssl

Type:

bool

Default:

false

Description :

whether or not to verify SSL when connecting over RDP (Windows)

Parameter name:

ssh_port

Type:

int

Default:

22

Description :

SSH port for authentication of remote connections

Parameter name:

ssh_timeout

Type:

int

Default:

5

Description :

SSH timeout for authentication of remote connections.

Parameter name:

**kwargs

Type:

dict

Default:

none

Description :

If additional flags are passed into the run command, then we will attempt to match them with defined inputs within atomic tests and replace their value with the provided value

By way of demonstration, you can paste the following command into your terminal and run it. It will run all relevant atomics associated with T1016: System Network Configuration Discovery on your local system. Note: As you’ll see in the gif below, we ran this test on a Mac, so atomic-operator skips all non macOS tests.

atomic-operator run --techniques "T1016"

And here’s how you would run a specific atomic test remotely on a host:

atomic-operator run --test_guids 'dfb50072-e45a-4c75-a17e-a484809c8553' --hosts '192.168.10.10' --username 'root' --password ‘password' --get_prereqs --check_prereqs --copy_source_files

If you want to use atomic-operator to run specific tests on specific hosts, then you can do so by passing in a configuration file using the --config_file parameter. Within this configuration file you can define which tests to run, specify optional input arguments (and their values), and provide one or more inventory objects with the correct credentials to those hosts. The details about the configuration file can be found here.

Dive in!

When I was creating atomic-operator, I wanted a framework that was flexible enough to fit most of my needs, and I hope that it will meet yours as well. Atomic-operator is open source, so, if it doesn’t meet your needs, you can contribute to the project. Otherwise, if you have any questions or issues, please feel free to create an issue in the repository. Additionally, you can reach out to me on the Atomic Red Team Slack at @MSAdministrator or on Twitter.

 

Emu-lation: Validating detections for SocGholish with Atomic Red Team

 

Emu-lation: Validating detection for Gootloader with Atomic Red Team

 

Safely validate executable file attributes with Atomic Test Harnesses

 

Find security bugs in web application routes with route-detect

Subscribe to our blog

 
 
Back to Top