Revoke-Obfuscation - PowerShell Obfuscation Detection Framework

Installation
The source code for Revoke-Obfuscation is hosted at Github, and you may download, fork and review it from this repository (https://github.com/danielbohannon/Revoke-Obfuscation). Please report issues or feature requests through Github's bug tracker associated with this project.
To install (from Github):

Import-Module .\Revoke-Obfuscation.psd1

The source code can also be installed directly from the PowerShell Gallery via the following commands:
To install (from PowerShell Gallery):

Install-Module Revoke-Obfuscation
Import-Module Revoke-Obfuscation

Usage
Revoke-Obfuscation will provide a detailed tutorial as well as a few other fun surprises. But if you are not into the lulz then you can simply run Get-Help Measure-RvoObfuscation to see usage syntax or just continue reading.
There are two primary functions used in this framework:

• Get-RvoScriptBlock -- reassembles scripts from EID 4104 script block logs
• Measure-RvoObfuscation -- measures input script(s) and returns obfuscation score

If you need to reassemble and extract script block logs from PowerShell Operational logs then Get-RvoScriptBlock is your function of choice. It automatically returns only unique script blocks and excludes certain default script block values deemed not malicious. This can be overridden with the -Deep switch.

• Get-RvoScriptBlock -Path 'C:\Windows\System32\Winevt\Logs\Microsoft-Windows-PowerShell%4Operational.evtx' -Verbose
• Get-ChildItem .\Demo\demo.evtx | Get-RvoScriptBlock -Verbose
• Get-WinEvent -LogName Microsoft-Windows-PowerShell/Operational | Get-RvoScriptBlock -Verbose

Get-RvoScriptBlock also supports MIR/HX audit results as well as PowerShell Operational logs retrieved via Matt Graeber's (@mattifestation) CimSweep project (https://github.com/PowerShellMafia/CimSweep). For CimSweep there is a minor registry tweak required to trick WMI into querying a non-classic event log. Details can be found in the NOTES section of Get-RvoScriptBlock.

• Get-ChildItem C:\MirOrHxAuditFiles\*_w32eventlogs.xml | Get-RvoScriptBlock -Verbose
• Get-CSEventLogEntry -LogName Microsoft-Windows-PowerShell/Operational | Get-RvoScriptBlock

A full example against test data recorded in demo.evtx can be found below:

$obfResults = Get-WinEvent -Path .\Demo\demo.evtx | Get-RvoScriptBlock | Measure-RvoObfuscation -OutputToDisk -Verbose

A full example against local and remotely hosted test scripts can be found below:

• Measure-RvoObfuscation -Url 'http://bit.ly/DBOdemo1' -Verbose -OutputToDisk
• Get-Content .\Demo\DBOdemo*.ps1 | Measure-RvoObfuscation -Verbose -OutputToDisk
• Get-ChildItem .\Demo\DBOdemo*.ps1 | Measure-RvoObfuscation -Verbose -OutputToDisk

The -OutputToDisk switch will automatically output all obfuscated scripts to .\Results\Obfuscated. Regardless, all results will be returned as PSCustomObjects containing the script content along with metadata like an obfuscation score, measurement time, whitelisting result, all extracted script features, etc.
Three whitelisting options exist in two locations in Revoke-Obfuscation:

1. On Disk (automatically applied if present):
   1. .\Whitelist\Scripts_To_Whitelist\ -- All scripts placed in this directory will be hashed and any identical scripts will be whitelisted. This whitelisting method is preferred above the next two options.
   2. .\Whitelist\Strings_To_Whitelist.txt -- A script containing ANY of the strings in this file will be whitelisted. Syntax: Rule_Name,string_to_whitelist
   3. .\Whitelist\Regex_To_Whitelist.txt -- A script containing ANY of the regular expressions in this file will be whitelisted. Syntax: Rule_Name,regex_to_whitelist
2. Arguments for Measure-RvoObfuscation (applied in addition to above whitelisting options):
   1. -WhitelistFile -- -WhitelistFile .\files\*.ps1,.\more_files\*.ps1,.\one_more_file.ps1
   2. -WhitelistContent -- -WhitelistContent 'string 1 to whitelist','string 2 to whitelist'
   3. -WhitelistRegex -- -WhitelistRegex 'regex 1 to whitelist','regex 2 to whitelist'

If interested in creating your own set of training data and generating a weighted vector for the Measure-Vector function, then ModelTrainer.cs/ModelTrainer.exe can be executed against a labeled data set. The following command will extract feature vectors from all input scripts and aggregate them into a single CSV used in this training phase:

Get-ChildItem .\*.ps1 | ForEach-Object { [PSCustomObject](Get-RvoFeatureVector -Path $_.FullName) | Export-Csv .\all_features.csv -Append }

Lastly, if looking for a platform for creating indicators (IOCs) that harness the power of PowerShell's AST (Abstract Syntax Tree) -- which we would highly recommend for identifying malicious PowerShell activity that is NOT obfuscated -- then PS Script Analyzer is an excellent framework designed to handle such tasks.

Release Notes
v1.0 - 2017-07-27 Black Hat USA & 2017-07-30 DEF CON: PUBLIC Release of Revoke-Obfuscation.