diff --git a/docs/invoke-atomic-red-team.md b/docs/invoke-atomic-red-team.md new file mode 100644 index 00000000..4947a496 --- /dev/null +++ b/docs/invoke-atomic-red-team.md @@ -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 +``` diff --git a/execution-frameworks/Invoke-AtomicRedTeam/Invoke-AtomicRedTeam/Public/Invoke-AllAtomicTests.ps1 b/execution-frameworks/Invoke-AtomicRedTeam/Invoke-AtomicRedTeam/Public/Invoke-AllAtomicTests.ps1 new file mode 100644 index 00000000..e2fdbf6e --- /dev/null +++ b/execution-frameworks/Invoke-AtomicRedTeam/Invoke-AtomicRedTeam/Public/Invoke-AllAtomicTests.ps1 @@ -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 + } + + + +} diff --git a/execution-frameworks/Invoke-AtomicRedTeam/README.md b/execution-frameworks/Invoke-AtomicRedTeam/README.md index 0056f3e2..ad773ae4 100644 --- a/execution-frameworks/Invoke-AtomicRedTeam/README.md +++ b/execution-frameworks/Invoke-AtomicRedTeam/README.md @@ -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 } -```