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):
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:WindowsSystem32WinevtLogsMicrosoft-Windows-PowerShell%4Operational.evtx' -Verbose
Get-ChildItem .Demodemo.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-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 .Demodemo.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 .DemoDBOdemo*.ps1 | Measure-RvoObfuscation -Verbose -OutputToDisk
Get-ChildItem .DemoDBOdemo*.ps1 | Measure-RvoObfuscation -Verbose -OutputToDisk
-OutputToDisk switch will automatically output all obfuscated scripts to .ResultsObfuscated. 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:
- On Disk (automatically applied if present):
- .WhitelistScripts_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.
- .WhitelistStrings_To_Whitelist.txt — A script containing ANY of the strings in this file will be whitelisted. Syntax: Rule_Name,string_to_whitelist
- .WhitelistRegex_To_Whitelist.txt — A script containing ANY of the regular expressions in this file will be whitelisted. Syntax: Rule_Name,regex_to_whitelist
- Arguments for Measure-RvoObfuscation (applied in addition to above whitelisting options):
- -WhitelistFile —
- -WhitelistContent —
-WhitelistContent 'string 1 to whitelist','string 2 to whitelist'
- -WhitelistRegex —
-WhitelistRegex 'regex 1 to whitelist','regex 2 to whitelist'
- -WhitelistFile —
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)
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.
v1.0 – 2017-07-27 Black Hat USA & 2017-07-30 DEF CON: PUBLIC Release of Revoke-Obfuscation.