ART - Getting Started Made Easy (#459)

* New Guide + Execution Script Commit of new script and guide! * Updated ReadMe Updated Readme with new instructions * Fixed typos Typo gone and ready!
2019-02-14 14:13:13 -07:00
parent 60bc6fd9e1
commit 7e34cbe7df
3 changed files with 249 additions and 15 deletions
@@ -0,0 +1,126 @@
+---
+layout: default
+---
+
+# Getting Started - PowerShell Invoke-AtomicRedTeam
+
+1. [Install Atomic Red Team](#install-atomic-red-team)
+2. [Generate Tests](#generate-tests)
+3. [Execute Tests](#execute-tests)
+4. [Other Examples](#Other-Examples)   
+
+## Install Atomic Red Team
+
+* Be sure to get permission and necessary approval before conducting test's. 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. It is best to have AV turned off.
+
+We made installing Atomic Red Team extremely easy.
+
+Once the environment is ready, run the following PowerShell one liner as Administrator:
+
+`powershell.exe "IEX (New-Object Net.WebClient).DownloadString('http://psinstall.AtomicRedTeam.com')"`
+
+[Source](https://raw.githubusercontent.com/redcanaryco/atomic-red-team/master/execution-frameworks/Invoke-AtomicRedTeam/install-AtomicRedTeam.ps1)
+
+By default, it will download and install Atomic Red Team to `c:\tools\`
+
+Running the [install script](https://raw.githubusercontent.com/redcanaryco/atomic-red-team/master/execution-frameworks/Invoke-AtomicRedTeam/install-AtomicRedTeam.ps1) locally provides three parameters:
+
+InstallPath
+- Where ART is to be installed
+
+    `install-AtomicRedTeam.ps1 --InstallPath c:\tools\`
+
+DownloadPath
+- Where ART is to be downloaded
+
+    `install-AtomicRedTeam.ps1 --DownloadPath c:\tools\`
+
+Verbose
+- Verbose output during installation
+
+    `install-AtomicRedTeam.ps1 --verbose`
+
+### Manual Installation
+
+To manually install Invoke-AtomicRedTeam:
+
+`set-executionpolicy Unrestricted`
+
+[PowerShell-Yaml](https://github.com/cloudbase/powershell-yaml) is required to parse Atomic yaml files:
+
+`Install-Module -Name powershell-yaml`
+
+`Import-Module .\Invoke-AtomicRedTeam.psm1`
+
+## Generate Tests
+
+This process generates all Atomic tests and allows for easy copy and paste execution.
+Note: you may need to change the path.
+
+    Invoke-AllAtomicTests -GenerateOnly
+
+### Execute All Tests
+
+Execute all Atomic tests:
+
+    Invoke-AllAtomicTests
+
+### Execute All Tests - Specific Directory
+
+Specify a path to atomics folder, example C:\AtomicRedTeam\atomics
+
+    Invoke-AllAtomicTests -path C:\AtomicRedTeam\atomics
+
+### Execute a Single test
+
+    $T1117 = Get-AtomicTechnique -Path ..\..\atomics\T1117\T1117.yaml
+    Invoke-AtomicTest $T1117
+
+## Other Examples
+
+If you would like output when running tests using the following:
+
+#### Informational Stream
+
+```powershell
+Invoke-AtomicTest $T1117 -InformationAction Continue
+```
+
+#### Verbose Stream
+
+```powershell
+Invoke-AtomicTest $T1117 -Verbose
+```
+
+#### Debug Stream
+
+```powershell
+Invoke-AtomicTest $T1117 -Debug
+```
+
+#### WhatIf
+
+If you would like to see what would happen without running the test
+
+```powershell
+Invoke-AtomicTest $T1117 -WhatIf
+```
+
+#### Confirm
+
+To run all tests without confirming them run using the Confirm switch to false
+
+```powershell
+Invoke-AtomicTest $T1117 -Confirm:$false
+```
+
+Or you can set your `$ConfirmPreference` to 'Medium'
+
+```powershell
+$ConfirmPreference = 'Medium'
+Invoke-AtomicTest $T1117
+```
@@ -0,0 +1,78 @@
+<#
+.SYNOPSIS
+    Invokes all Atomic test(s)
+.DESCRIPTION
+    Invokes all Atomic tests(s).  Optionally, you can specify if you want to generate all Atomic test(s) only.
+.EXAMPLE Invokes Atomic Test
+    PS/> Invoke-AllAtomicTests
+	PS/> Invoke-AllAtomicTests -Force
+.EXAMPLE Generate All Atomic Tests
+    PS/> Invoke-AllAtomicTests -GenerateOnly
+.PARAMETER Path
+	Path to atomics folder, example C:\AtomicRedTeam\atomics
+.PARAMETER GenerateOnly
+    Generate tests only do not execute. Writes test commands to STDOUT
+.PARAMETER Force
+    Override safety handler. Normally this will prompt you to confirm all tests. This will override that.
+.NOTES
+    Create Atomic Tests from yaml files described in Atomic Red Team. https://github.com/redcanaryco/atomic-red-team
+.LINK
+    Github repo: https://github.com/redcanaryco/atomic-red-team
+#>
+function Invoke-AllAtomicTests {
+    [CmdletBinding(DefaultParameterSetName = 'technique',
+        SupportsShouldProcess = $true,
+        PositionalBinding = $false,
+        ConfirmImpact = 'Medium')]
+    Param(
+        [Parameter(Mandatory = $true,
+            Position = 0,
+            ValueFromPipelineByPropertyName = $true,
+            ParameterSetName = 'technique')]
+        [ValidateNotNullOrEmpty()]
+        [System.String]
+        $Path,
+
+        [Parameter(Mandatory = $false,
+            Position = 1,
+            ValueFromPipelineByPropertyName = $true,
+            ParameterSetName = 'technique')]
+        [switch]
+        $GenerateOnly,
+
+		[switch]
+		$Force
+    )
+	$InformationPreference = 'Continue'
+
+	function Invoke-AllTests()
+	{
+
+		[System.Collections.HashTable]$AllAtomicTests = @{}
+		$AtomicFilePath = $Path
+		Get-ChildItem $AtomicFilePath -Recurse -Filter *.yaml -File | ForEach-Object {
+		$currentTechnique = [System.IO.Path]::GetFileNameWithoutExtension($_.FullName)
+		$parsedYaml = (ConvertFrom-Yaml (Get-Content $_.FullName -Raw ))
+		$AllAtomicTests.Add($currentTechnique, $parsedYaml);
+		}
+		if($GenerateOnly)
+		{
+			$AllAtomicTests.GetEnumerator() | Foreach-Object { Invoke-AtomicTest $_.Value -GenerateOnly }
+
+		}
+		else
+		{
+			$AllAtomicTests.GetEnumerator() | Foreach-Object { Invoke-AtomicTest $_.Value }
+		}
+
+	}
+
+	if ( $Force -or $psCmdlet.ShouldContinue( 'Do you wish to execute all tests?',
+                 "Highway to the danger zone, Executing All Atomic Tests!" ) )
+	{
+		Invoke-AllTests
+	}
+
+
+
+}
@@ -4,7 +4,30 @@

 ### Install Atomic Red Team

-Get started quickly with our simple Powershell [script](install-atomicredteam.ps1).
+Get started with our simple install script:
+
+`powershell.exe "IEX (New-Object Net.WebClient).DownloadString('http://psinstall.AtomicRedTeam.com')"`
+
+[Source](https://raw.githubusercontent.com/redcanaryco/atomic-red-team/master/execution-frameworks/Invoke-AtomicRedTeam/install-AtomicRedTeam.ps1)
+
+By default, it will download and install Atomic Red Team to `c:\tools\`
+
+Running the [install script](https://raw.githubusercontent.com/redcanaryco/atomic-red-team/master/execution-frameworks/Invoke-AtomicRedTeam/install-AtomicRedTeam.ps1) locally provides three parameters:
+
+InstallPath
+- Where ART is to be installed
+
+    `install-AtomicRedTeam.ps1 --InstallPath c:\tools\`
+
+DownloadPath
+- Where ART is to be downloaded
+
+    `install-AtomicRedTeam.ps1 --DownloadPath c:\tools\`
+
+Verbose
+- Verbose output during installation
+
+    `install-AtomicRedTeam.ps1 --verbose`

 ### Manual

@@ -20,7 +43,27 @@ Get started quickly with our simple Powershell [script](install-atomicredteam.ps

 ## Getting Started

-### Execute a Single Test
+### Generate Tests
+
+This process generates all Atomic tests and allows for easy copy and paste execution.
+Note: you may need to change the path.
+
+    Invoke-AllAtomicTests -GenerateOnly
+
+#### Execute All Tests
+
+Execute all Atomic tests:
+
+    Invoke-AllAtomicTests
+
+#### Execute All Tests - Specific Directory
+
+Specify a path to atomics folder, example C:\AtomicRedTeam\atomics
+
+    Invoke-AllAtomicTests -path C:\AtomicRedTeam\atomics
+
+
+#### Execute a Single Test

 ```powershell
 $T1117 = Get-AtomicTechnique -Path ..\..\atomics\T1117\T1117.yaml
@@ -71,16 +114,3 @@ Or you can set your `$ConfirmPreference` to 'Medium'
 $ConfirmPreference = 'Medium'
 Invoke-AtomicTest $T1117
 ```
-
-## Generate All Tests
-
-```powershell
-[System.Collections.HashTable]$AllAtomicTests = @{}
-$AtomicFilePath = 'C:\AtomicRedTeam\atomics\'  
-Get-ChildItem $AtomicFilePath -Recurse -Filter *.yaml -File | ForEach-Object {
-    $currentTechnique = [System.IO.Path]::GetFileNameWithoutExtension($_.FullName)  
-    $parsedYaml = (ConvertFrom-Yaml (Get-Content $_.FullName -Raw ))
-    $AllAtomicTests.Add($currentTechnique, $parsedYaml);
-}
-$AllAtomicTests.GetEnumerator() | Foreach-Object { Invoke-AtomicTest $_.Value -GenerateOnly }
-```