A python package to execute Atomic tests
Project description
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
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.