atomic-operator 0.0.6

A python package to execute Atomic tests

atomic-operator

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

Current Version: v0.0.1 (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 execution of Atomic Red Teams tests on Windows, macOS, and Linux systems
• Can prompt for input arguments but not required
• Assist with downloading the atomic-red-team repository
• Running tests can be automated further based on a configuration file

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

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.3.1
requests==2.26.0
attrs==21.2.0

macOS, Linux and Windows:

pip install atomic-operator

Installing from source

git clone https://github.com/swimlane/atomic-operator.git
cd atomic-operator
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
# or
atomic-operator --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

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"

Additional parameters

You can see additional parameters by running the following command:

atomic-operator run -- --help

You should see a similar output to the following:

NAME
    atomic-operator run - The main method in which we run Atomic Red Team tests.

SYNOPSIS
    atomic-operator run <flags>

DESCRIPTION
    config_file definition:
        atomic-operator's run method can be supplied with a path to a configuration file (config_file) which defines 
        specific tests and/or values for input parameters to facilitate automation of said tests.
        An example of this config_file can be seen below:

            atomic_tests:
              - guid: f7e6ec05-c19e-4a80-a7e7-241027992fdb
                input_arguments:
                  output_file:
                    value: custom_output.txt
                  input_file:
                    value: custom_input.txt
              - guid: 3ff64f0b-3af2-3866-339d-38d9791407c3
                input_arguments:
                  second_arg:
                    value: SWAPPPED argument
              - guid: 32f90516-4bc9-43bd-b18d-2cbe0b7ca9b2

FLAGS
    --techniques=TECHNIQUES
        One or more defined techniques by attack_technique ID. Defaults to 'All'.
    --test_guids=TEST_GUIDS
        One or more Atomic test GUIDs. Defaults to None.
    --atomics_path=ATOMICS_PATH
        The path of Atomic tests. Defaults to os.getcwd().
    --check_dependencies=CHECK_DEPENDENCIES
        Whether or not to check for dependencies. Defaults to False.
    --get_prereqs=GET_PREREQS
        Whether or not you want to retrieve prerequisites. Defaults to False.
    --cleanup=CLEANUP
        Whether or not you want to run cleanup command(s). Defaults to False.
    --command_timeout=COMMAND_TIMEOUT
        Timeout duration for each command. Defaults to 20.
    --show_details=SHOW_DETAILS
        Whether or not you want to output details about tests being ran. Defaults to False.
    --prompt_for_input_args=PROMPT_FOR_INPUT_ARGS
        Whether you want to prompt for input arguments for each test. Defaults to False.
    --config_file=CONFIG_FILE
        A path to a conifg_file which is used to automate atomic-operator in environments. Default to None.
    Additional flags are accepted.
        If provided, keys matching inputs for a test will be replaced. Default is None.

Running atomic-operator using a config_file

In addition to the ability to pass in parameters with atomic-operator you can also pass in a path to a config_file that contains all the atomic tests and their potential inputs. You can see an example of this config_file here:

atomic_tests:
  - guid: f7e6ec05-c19e-4a80-a7e7-241027992fdb
    input_arguments:
      output_file:
        value: custom_output.txt
      input_file:
        value: custom_input.txt
  - guid: 3ff64f0b-3af2-3866-339d-38d9791407c3
    input_arguments:
        second_arg:
          value: SWAPPPED argument
  - guid: 32f90516-4bc9-43bd-b18d-2cbe0b7ca9b2

Usage example (scripts)

To use atomic-operator you must instantiate an AtomicOperator object.

from atomic_operator import AtomicOperator

operator = AtomicOperator()

# This will download a local copy of the atomic-red-team repository

print(operator.get_atomics('/tmp/some_directory'))

# this will run tests on your local system
operator.run(
    technique: str='All', 
    atomics_path=os.getcwd(), 
    check_dependencies=False, 
    get_prereqs=False, 
    cleanup=False, 
    command_timeout=20, 
    show_details=False,
    prompt_for_input_args=False,
    **kwargs
)

Getting Help

Please create an issue if you have questions or run into any issues.

Built With

• carcass - Python packaging template

Contributing

Please read CONTRIBUTING.md for details on our code of conduct, and the process for submitting pull requests to us.

Versioning

We use SemVer for versioning.

Authors

• Josh Rickard - Initial work - MSAdministrator

See also the list of contributors who participated in this project.

License

This project is licensed under the MIT License - see the LICENSE file for details