[][license]

atomic-operator

This python package is used to execute Atomic Red Team tests (Atomics) across multiple operating system environments.

(What's new?)

Why?

atomic-operator enables security professionals to test their detection and defensive capabilities against prescribed techniques defined within atomic-red-team. By utilizing a testing framework such as atomic-operator, you can identify both your defensive capabilities as well as gaps in defensive coverage.

Additionally, atomic-operator can be used in many other situations like:

• Generating alerts to test products
• Testing EDR and other security tools
• Identifying way to perform defensive evasion from an adversary perspective
• Plus more.

Features

• Support local and remote execution of Atomic Red Teams tests on Windows, macOS, and Linux systems
• Supports running atomic-tests against iaas:aws
• Can prompt for input arguments but not required
• Assist with downloading the atomic-red-team repository
• Can be automated further based on a configuration file
• A command-line and importable Python package
• Select specific tests when one or more techniques are specified
• Search across all atomics for that perfect test
• Pass input_arguments as input for tests via command line
• Plus more

Getting Started

atomic-operator is a Python-only package hosted on PyPi and works with Python 3.6 and greater.

If you are wanting a PowerShell version, please checkout Invoke-AtomicRedTeam.

pip install atomic-operator

The next steps will guide you through setting up and running atomic-operator.

• Get Atomics Install / clone Atomic Red Team repository
• atomic-operator Understand the options availble in atomic-operator
• Running Test on Command Line or Running Tests within a Script
• Running Tests via Configuration File

Installation

You can install atomic-operator on OS X, Linux, or Windows. You can also install it directly from the source. To install, see the commands under the relevant operating system heading, below.

Prerequisites

The following libraries are required and installed by atomic-operator:

pyyaml==5.4.1
fire==0.4.0
requests==2.26.0
attrs==21.2.0
pick==1.2.0

macOS, Linux and Windows:

pip install atomic-operator

macOS using M1 processor

git clone https://github.com/swimlane/atomic-operator.git
cd atomic-operator

# Satisfy ModuleNotFoundError: No module named 'setuptools_rust'
brew install rust
pip3 install --upgrade pip
pip3 install setuptools_rust

# Back to our regularly scheduled programming . . .  
pip install -r requirements.txt
python setup.py install

Installing from source

git clone https://github.com/swimlane/atomic-operator.git
cd atomic-operator
pip install -r requirements.txt
python setup.py install

Usage example (command line)

You can run atomic-operator from the command line or within your own Python scripts. To use atomic-operator at the command line simply enter the following in your terminal:

atomic-operator --help
atomic-operator run -- --help

Please note that to see details about the run command run atomic-operator run -- --help and NOT atomic-operator run --help

Retrieving Atomic Tests

In order to use atomic-operator you must have one or more atomic-red-team tests (Atomics) on your local system. atomic-operator provides you with the ability to download the Atomic Red Team repository. You can do so by running the following at the command line:

atomic-operator get_atomics 
# You can specify the destination directory by using the --destination flag
atomic-operator get_atomics --destination "/tmp/some_directory"

Running Tests Locally

In order to run a test you must provide some additional properties (and options if desired). The main method to run tests is named run.

# This will run ALL tests compatiable with your local operating system
atomic-operator run --atomics-path "/tmp/some_directory/redcanaryco-atomic-red-team-3700624"

You can select individual tests when you provide one or more specific techniques. For example running the following on the command line:

atomic-operator run --techniques T1564.001 --select_tests

Will prompt the user with a selection list of tests associated with that technique. A user can select one or more tests by using the space bar to highlight the desired test:

 Select Test(s) for Technique T1564.001 (Hide Artifacts: Hidden Files and Directories)

 * Create a hidden file in a hidden directory (61a782e5-9a19-40b5-8ba4-69a4b9f3d7be)
   Mac Hidden file (cddb9098-3b47-4e01-9d3b-6f5f323288a9)
   Create Windows System File with Attrib (f70974c8-c094-4574-b542-2c545af95a32)
   Create Windows Hidden File with Attrib (dadb792e-4358-4d8d-9207-b771faa0daa5)
   Hidden files (3b7015f2-3144-4205-b799-b05580621379)
   Hide a Directory (b115ecaf-3b24-4ed2-aefe-2fcb9db913d3)
   Show all hidden files (9a1ec7da-b892-449f-ad68-67066d04380c)

The following will allow you to provide custom input arguments for tests. You do this providing a dictionary of keys and values as a dictionary to the input_arguments parameter on the run method.

atomic-operator run --techniques T1564.001 --input_arguments '{"project-id": "some_value", "another_key": "another value"}'
# Please include single quotes around the input_arguments value.

Running Tests Remotely

In order to run a test remotely you must provide some additional properties (and options if desired). The main method to run tests is named run.

# This will run ALL tests compatiable with your local operating system
atomic-operator run --atomics-path "/tmp/some_directory/redcanaryco-atomic-red-team-3700624" --hosts "10.32.1.0" --username "my_username" --password "my_password"

When running commands remotely against Windows hosts you may need to configure PSRemoting. See details here: Windows Remoting

Additional parameters