atomic-red-team/atomic_red_team/spec.yaml

#
# 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, sh, bash, powershell, manual, aws, az, gcloud, kubectl
  #
  #       Each of the above requires the "command" option that is a multi-line script that will be preprocessed and
  #       then executed by cmd.exe, powershell.exe, sh or bash respectively
  #
  #       Example:
  #         name: command_prompt
  #         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!"