Word Default Template Persistence - Part 3

Contributing to Atomic Red Team

This is the final post of a 3 part series:

• Part 1 focuses on the overall concept and walks through the basic scenario manually.

• Part 2 covers the automation process via PowerShell.

• Part 3 details the process to get the test properly formatted and submitted as a Pull Request to the Atomic Red Team Master Repo.

Setting the Stage

First off, feel free to read both Part 1 and Part 2 to find out the backstory and walk through the whole concept.

Quick recap: I set out to contribute an Atomic Test to Atomic Red Team and landed on T1137.001 - Office Application Startup: Office Template Macros. Once I completed the two separate PowerShell scripts (one to carry out the test, one to perform the Cleanup Actions), I made sure to test them on two different platforms: Windows 11 w/ Office 365 and Windows 10 w/ Office 2016.

Test Formatting

Note: The general process I’m about to walkthrough is covered in this YouTube video and in the official Atomic Red Team Contributing page on Github.

Atomic Tests for Atomic Red Team are defined within YAML files - each Technique has its own Directory, its own YAML file, and its own Markdown file (the .md/Markdown file is auto-generated).

For example: the YAML file for the Technique covered in this blog series is “T1137.001.yaml” and is contained in the directory “atomics/T1137.001”.

You have the option of creating the YAML files via the Atomic GUI or manually by referencing this template. I chose the latter option to make sure I understood how to properly format each section. The majority of the sections are pretty straightforward (Attack Technique, Display Name, etc.), however, it’s important to note that you can have multiple atomic tests within each YAML file. Reference this example that contains three Atomic Tests within it.

The core of the Atomic Test I created consists of the following sections:

Name of the test

   name: 

A GUID that gets auto-generated

   auto_generated_guid: 

A brief description of the test

   description:

Notes which platforms are supported (Windows, MacOS, etc.)

   supported_platforms:

Any dependencies that need to be checked before the test can be ran should be included. In this case, the test only works if Microsoft Word is installed. Therefore, I included a quick test to check if Word exists on the system to be tested:

Note how the given commands will be executed (CMD, PowerShell, etc.); if elevation is required; and what commands to be executed. In this case, I was able to virtually copy and paste the whole first script into the “command” section:

  executor:
    name: powershell
    elevation_required: true
    command: |

Lastly, it is recommended to include commands that will ‘undo’ any changes made throughout the execution of the test. In this case, I was also able to virtually copy and paste the whole second script into the “cleanup_command” section:

    cleanup_command: |    

Navigate here to see the complete YAML file created for this technique.

Submitting the Atomic Test

Once the YAML file is ready, it’s time to submit the test to be reviewed and potentially added. New Atomic Tests are submitted via Pull Requests to the official repository. You are able to use Git via the command line to submit the changes or use the Github Web Interface (which is easier for beginners). The latter scenario will be covered here.

First, we need to fork the official repository to make our own copy - this way any changes we make will not be sent to the official repo until we’re ready. Just navigate to the official repo and select “Fork”.

Now we can navigate to our copied repo and go to the “atomics” directory where all of the Atomic Tests are located. (Notice I’m working in my own copied repo - DefenderDaniel / atomic-red-team)

Next, we need to create the directory and YAML file specific to this new test. For this demo, I’m going to create dummy examples T1137.demo / T1137.demo.yaml

We need to select Add file>Create new file.

In the section that says “Name your file…”, first enter the name of the new directory and then a ‘/’. In this example it is T1137.demo/

Then enter the name of the YAML file. In this example it is T1137.demo.yaml

Then enter/paste the properly formatted file contents. When done, select Commit changes.

At the next pop-up you can leave the defaults and select Commit changes again.

At this point, we have completed our changes and are now ready to submit the Pull Request to the official repo.

Select Contribute>Open pull request

You’ll be presented with a new page, if everything looks good then select Create pull request

Fill out the Pull Request with the required information. Feel free to reference the actual Pull Request I submitted here.

Once submitted, the request will go through a few automated checks and then through designated reviewers to ensure the proper formatting is followed and that it meets the necessary requirements.

After the reviewers determine it meets all the criteria, they will approve the Pull Request and merge it into the official repo. One perk, all first time contributors with an approved Pull Request can request a free T-Shirt 😊

Conclusion

Overall, the process was not overly complicated and pretty easy to figure out. I recommend anyone interested to give it a try.

This concludes this particular series, however, I do intend to contribute more Atomic Tests in the future. If anyone decides to try this out themselves, let me know in the comments.