# # This spec describes the format of Atomic Red Team atomic tests that are defined in YAML format. # # The directory structure is: # - These tests reside in the `atomics` directory # - One directory per ATT&CK technique, named "T1234" # - All the atomic tests for a technique in a file called "T1234.yaml" inside that directory # - Any payloads, supporting materials, etc for the atomic tests also live in that directory # # For example: # # atomic_red_team/ # atomic_red_team/atomics # atomic_red_team/atomics/T1234 # atomic_red_team/atomics/T1234/T1234.yaml <-- this is where all the atomic tests live # atomic_red_team/atomics/T1234/src/payload1.sct <-- a payload file needed by one of the T1234 atomics (human readable) # atomic_red_team/atomics/T1234/bin/payload2.dll <-- another payload file needed by one of the T1234 atomics (binary) # # In general, a set of atomic tests for a technique should never depend on payloads # or supporting files from other atomic directories. We want to keep things nice and close. # Use git symlinks if you really need to share files between techniques. # # Atomic tests should be fully automated whenever possible, requiring no continued interaction. # Include any needed options to execute the commands seamlessly, for example SysInternal's -accepteula option or any -q or -quiet modes. # # To validate your atomics, run `bin/validate_atomics.rb` --- attack_technique: TXXXX # (with a capital T, Example: 'T1123') display_name: Name of the technique as defined by ATT&CK. # Example: 'Audio Capture' # `atomic_tests` is an array of distinct test cases inside this technique. A test case should # include ALL of the information needed to run that test (ie, this is the "atomic" - you don't # distribute steps across different atomics) # Each of these tests is a YAML array element (starts with a `-`). atomic_tests: # # This is the first atomic test # - name: Short name of the test that titles how it tests the technique. # Example: "SourceRecorder via cmd.exe" auto_generated_guid: # This key and/or it's value will be added by the CI build after submitting a Pull Request description: | Long form description of the test. Markdown is supported so you can **bold** items, create - one list - two list - red list - [blue list](https://google.com) # supported platforms is an array of the OS/platforms this atomic test can be run upon. Values include: # - windows # - macos # - linux # - office-365 # - azure-ad # - google-workspace # - saas # - iaas # - containers # - iaas:gcp # - iaas:azure # - iaas:aws supported_platforms: - windows # inputs to the atomic test that are required to run the test (think of these like function arguments). # This is a hash where the key is the input name, value is a hash defining the input argument. input_arguments: # this is the first input argument, called "output_file" output_file: # Short description of the input argument description: xxxxx # data type of the input. Possible values could include: # - Path (a file path) # - Url (a URL) # - String # - Integer # - Float # - really anything else you'd like, but add it to this list type: Path # default value for this argument that will be used if one is not specifid default: test.wma # this is a example of a second argument malware_payload_url: description: xxxxx type: Url default: 0000:00:30 dependency_executor_name: powershell # (optional) The executor for the prereq commands, defaults to the same executor used by the attack commands dependencies: # (optional) # a list of dependies that must be met to successfully run this atomic - description: | TODO prereq_command: | # commands to check if prerequisites for running this test are met. For the "command_prompt" executor, if any command returns a non-zero exit code, the pre-requisites are not met. For the "powershell" executor, all commands are run as a script block and the script block must return 0 for success. TODO get_prereq_command: | # commands to meet this prerequisite or a message describing how to meet this prereq TODO #example of two dependencies dependencies: - description: | Sysmon executable must be available prereq_command: | where sysmon > nul get_prereq_command: | echo Automated installer not implemented yet, please install Sysmon manually - description: | Sysmon must be installed prereq_command: | sc query sysmon > nul get_prereq_command: | sysmon -i -accepteula # a list of executors that can execute the attack commands of this atomic test. There are almost always going to be one of these # per test, but there are cases where you may have multiple - for example, separate executors for `sh` # and `bash` when working on linux OSes. # Names of cloud/container specific runtimes can also be used, such as `aws`, `az`, `gcloud` and `kubectl`. executor: # the name of the executor describes the framework or application in which the test should be executed. # # Each of these executors will have options that the executor needs to run. Possible executors we've imagined # at this time and their required options include: # # - `command_prompt` : The Windows Command Prompt, aka cmd.exe # Requires the "command" option that is a multi-line script that will be preprocessed and # then executed by cmd.exe # # Example: # - name: command_prompt # command: | # echo "attack starting" # echo "running command 1: this is the value of the FOOBAR input_argument: #{FOOBAR}" # # - `powershell` : Powershell # Requires the "`command`" option that is a multi-line script that will be preprocessed and # then executed by cmd.exe # # Example: # - name: powershell # command: | # Write-Debug "attack starting" # Write-Debug "running command 1: this is the value of the FOOBAR input_argument: #{FOOBAR}" # # - `sh` : Linux's bourne shell # Requires the "`command`" option that is a multi-line script that will be preprocessed and # then executed by cmd.exe # # Example: # - name: sh # command: | # echo "attack starting" # echo "running command 1: this is the value of the FOOBAR input_argument: #{FOOBAR}" # # - `bash` : Linux's bourne again shell # Requires the "`command`" option that is a multi-line script that will be preprocessed and # then executed by cmd.exe # # Example: # - name: bash # command: | # echo "attack starting" # echo "running command 1: this is the value of the FOOBAR input_argument: #{FOOBAR}" # # - `manual` : a list of manual steps to run. This should only be used when required, for example when GUI steps are involved that # cannot be automated. # # Requires the `steps` option that tells the user what to do to invoke the test. This is a # multi-line list of instructions (also preprocessed) # # Example: # - name: manual # steps: | # 1. Navigate to [chrome://extensions](chrome://extensions) and # tick 'Developer Mode'. # # 2. Click 'Load unpacked extension...' and navigate to # [Browser_Extension](../T1176/) # # 3. Click the '#{FOOBAR}' button - you can interpolate here too! # - name: command_prompt elevation_required: true # indicates whether command must be run with admin privileges. #If the elevation_required attribute is not defined, the value is assumed to be false command: | SoundRecorder /FILE #{output_file} /DURATION #{duration_hms} cleanup_command: | # you can remove the cleanup_command section if there are no cleanup commands # # This is the second atomic test # - name: Echo to the screen description: | blah blah blah supported_platforms: - macos - linux # in this example we have no input arguments input_arguments: executor: - name: bash command: echo "Hello world!"