Introduction to PSAmsi

PSAmsi is a tool for auditing and defeating AMSI signatures.

This is a brief introductory guide to how PSAmsi is organized and how to use it.

Core Functions

PSAmsi's core functions are:

• Start-PSAmsiClient and Start-PSAmsiServer - A standalone client/server architecture for sending many scripts from a PSAmsiServer to be scanned on the PSAmsiClient, and exfiltrating the results back to the PSAmsiServer.
• Invoke-PSAmsiScan - A single function that wraps Get-MinimallyObfuscated and Find-AmsiSignatures to allow you to conduct AMSI scans, find AMSI signatures, and/or get a minimally obfuscated copy of the script.
• Get-MinimallyObfuscated - Returns a minimally obfuscated copy of a given PowerShell script that will defeat AMSI signatures as well as obfuscation detection.
• Find-AmsiSignatures - Finds the AMSI signatures flagged as malicious by the AMSI AntiMalware Provider within a given PowerShell script.

PSAmsiScanner

The keys pieces of PSAmsi that accomplish the functionality described above are the [PSAmsiScanner] and [PowerShellObfuscator] classes. However, these classes are useful in their own right and can be used outside the context of the functions described above.

[PSAmsiScanner] - A class for conducting AMSI scans. Calls the functions exported from the AMSI.dll in memory using PSReflect (written by Matt Graeber).

[PSAmsiScanner] Functions:

• PSAmsiScanner() - Constructor - Create a [PSAmsiScanner] with [PSAmsiScanner]::new().
• GetPSAmsiScanResult() - Conduct an AMSI scan of a given script and get the boolean result.
• ResetPSAmsiScanCache() - Resets the [PSAmsiScanner]'s ScanCache, leading to fresh AMSI scan results.

PowerShell Cmdlets:

• New-PSAmsiScanner - A PowerShell cmdlet that creates a [PSAmsiScanner].
• Get-PSAmsiScanResult - A PowerShell cmdlet that uses [PSAmsiScanner] functions to conduct an AMSI scan of a given script and get the boolean result.
• Reset-PSAmsiScannerCache - A PowerShell cmdlet that uses [PSAmsiScanner] functions to reset the ScanCache, leading to fresh AMSI scan results.

Read more about conducting AMSI scans here.

PowerShellObfuscator

[PowerShellObfuscator] - A PowerShell Obfuscator that uses Invoke-Obfuscation (written by Daniel Bohannon) to minimally obfuscate PowerShell scripts to defeat AMSI signatures and obfuscation detection.

[PowerShellObfuscator] Functions:

• PowerShellObfuscator() - Constructor - Create a [PowerShellObfusator] with [PowerShellObfuscator]::new().
• GetMinimallyObfuscated() - Returns a minimally obfuscated copy of a given script that will defeat AMSI signatures as well as obfuscation.

PowerShell Cmdlets:

• New-PowerShellObfuscator - A PowerShell cmdlet that creates a [PowerShellObfuscator].
• Get-MinimallyObfuscated - A PowerShell cmdlet that returns a minimally obfuscated copy of a given script that will defeat AMSI signatures as well as obfuscation detection.

Read more about using obfuscation to defeat AMSI signatures here.

Utility Functions

Other useful functions:

• Test-ContainsAmsiSignatures - Checks if a given script contains any AMSI signatures. Stops after finding one, much faster than a full Find-AmsiSignatures.

• Find-AmsiAstSignatures - Finds the Asts within a script that are detected as malicious by the AMSI. This is used by Find-AmsiSignatures.

• Test-ContainsAmsiAstSignatures - Checks if a given script contains any AMSI Ast signatures. Stops after finding one, much faster than a full Find-AmsiAstSignatures.

• Find-AmsiPSTokenSignatures - Finds the PSTokens within a script that are detected as malicious by the AMSI. This is used by Find-AmsiSignatures.

• Test-ContainsAmsiPSTokenSignatures - Checks if a given script contains any AMSI PSToken signatures. Stops after finding one, much faster than a full Find-AmsiPSTokenSignatures.

• Get-Ast - Utility function that returns the root Ast of a given script.

• Get-PSTokens - Utility function that returns the PSTokens that comprise a given script.

Common Parameters

All functions that accept a Script as input can accept any one of the following parameters:

• -ScriptString - Specifies the string containing the Script to be passed to the function.
• -ScriptBlock - Specifies the ScriptBlock containing the Script to be passed to the function.
• -ScriptPath - Specifies a file Path containing the Script to be passed to the function.
• -ScriptUri - Specifies an HTTP(S) URI of the Script to be passed to the function.

The following functions accept these parameters: Start-PSAmsiServer, Invoke-PSAmsiScan, PSAmsiScanner.GetPSAmsiScanResult(), Get-PSAmsiScanResult, PowerShellObfuscator.GetMinimallyObfuscated(), Get-MinimallyObfuscated, Find-AmsiSignatures, Test-ContainsAmsiSignatures, Find-AmsiAstSignatures, Test-ContainsAmsiAstSignatures, Find-AmsiPSTokenSignatures, Test-ContainsAmsiPSTokenSignatures, Get-Ast, and Get-PSTokens.

All functions that will lead to AMSI scans being conducted accept a -PSAmsiScanner parameter. This allows for re-use of a PSAmsiScanner function for customized behavior. If the -PSAmsiScanner parameter is not provided, a new [PSAmsiScanner] is created.

The following functions accept the -PSAmsiScanner parameter: Start-PSAmsiClient, Invoke-PSAmsiScan, Get-PSAmsiScanResult, Get-MinimallyObfuscated, Find-AmsiSignatures, Test-ContainsAmsiSignatures, Find-AmsiAstSignatures, Test-ContainsAmsiAstSignatures, Find-AmsiPSTokenSignatures, and Test-ContainsAmsiPSTokenSignatures.