ISEScriptingGeek/Get-ASTScriptProfile.ps1 at master · forcefx2/ISEScriptingGeek

270 lines (202 loc) · 7.85 KB
#requires -version 3.0
#Get-ASTScriptProfile.ps1
Function Get-ASTProfile {
Profile a PowerShell script
.Description
This script will parse a PowerShell script using the AST to identify elements and any items that might be dangerous. The output is a text report which by default is turned into a help topic stored in your Windows PowerShell folder under Documents, although you can specify an alternate location.
The script takes the name of a script to profile. You can specify a ps1 or psm1 filename. Using the AST the script will prepare a text report showing you any script requirements, script parameters, commands and type names. You will see all commands used including those that can't be resolved as well as those that I thought might be considered potentially dangerous such as cmdlets that use the verbs Remove or Stop. 
Because some people might invoke methods from .NET classes directly I've also captured all typenames. Most of them will probably be related to parameters but as least you'll know what to look for. 
The report won't detail parameters from nested functions but you'll still see what commands they will use. The script uses Get-Command to identify commands which might entail loading a module. Most of the time this shouldn't be an issue but you still might want to profile the script in virtualized or test environment. 
Any unresolved command you see is either from a module that couldn't be loaded or it might be an internally defined command. Once you know what to look for you can open the script in your favorite editor and search for the mystery commands.
Note that if the script uses application names like Main or Control for function names, they might be misinterpreted. In that case, search the script for the name, ie "main". 
This version will only analyze files with an extension of .ps1, .psm1 or .txt.
.Parameter Path
The path to the script file. It should have an extension of .ps1, .psm1 or .bat.
.Parameter FilePath
The path for the report file. The default is your WindowsPowerShell folder. This paramter has aliases of fp and out.
PS C:\> c:\scripts\Get-ASTScriptProfile c:\download\UnknownScript.ps1 
This will analyze the script UnknownScript.ps1 and show the results in a help window. It will also create a text file in your Documents\WindowsPowerShell folder called UnknownScript.help.txt.
PS C:\> c:\scripts\Get-ASTScriptProfile c:\download\UnknownScript.ps1 -filepath c:\work
This command is the same as the first example except the help file will be created in C:\Work.
Version      : 3.0
Last Updated : October 29, 2014
Author       : Jeffery Hicks (http://twitter.com/jeffhicks)
Learn more about PowerShell:
http://jdhitsolutions.com/blog/essential-powershell-resources/
   ****************************************************************
   * DO NOT USE IN A PRODUCTION ENVIRONMENT UNTIL YOU HAVE TESTED *
   * THOROUGHLY IN A LAB ENVIRONMENT. USE AT YOUR OWN RISK.  IF   *
   * YOU DO NOT UNDERSTAND WHAT THIS SCRIPT DOES OR HOW IT WORKS, *
   * DO NOT USE IT OUTSIDE OF A SECURE, TEST SETTING.             *
   ****************************************************************
Get-Command
[cmdletbinding()]
[Parameter(Position=0,HelpMessage="Enter the path of a PowerShell script")]
[ValidateScript({Test-Path $_})]
[ValidatePattern( "\.(ps1|psm1|txt)$")]
[string]$Path=$(Read-Host "Enter the filename and path to a PowerShell script"),
[ValidateScript({Test-Path $_})]
[Alias("fp","out")]
[string]$FilePath = "$env:userprofile\Documents\WindowsPowerShell"
Write-Verbose "Starting $($myinvocation.MyCommand)"
#region setup profiling
#need to resolve full path and convert it
$Path = (Resolve-Path -Path $Path).Path | Convert-Path
Write-Verbose "Analyzing $Path"
Write-Verbose "Parsing File for AST"
New-Variable astTokens -force
New-Variable astErr -force
$AST = [System.Management.Automation.Language.Parser]::ParseFile($Path,[ref]$astTokens,[ref]$astErr)
#region generate AST data
#include PowerShell version information
Write-Verbose "PSVersionTable"
Write-Verbose ($PSversionTable | Out-String)
if ($ast.ScriptRequirements) {
    $requirements = ($ast.ScriptRequirements | Out-String).Trim()
    $requirements = "-->None detected"
if ($ast.ParamBlock.Parameters ) {
 write-verbose "Parameters detected"
 $foundParams = $(($ast.ParamBlock.Parameters | 
 Select Name,DefaultValue,StaticType,Attributes |
 Format-List | Out-String).Trim()
 $foundParams = "-->None detected. Parameters for nested commands not tested."
#define the report text
This is an analysis of a PowerShell script or module. Analysis will most likely NOT be 100% thorough. 
Write-Verbose "Getting requirements and parameters"
$report+=@"
REQUIREMENTS 
$requirements
$foundparams
Write-Verbose "Getting all command elements"
$commands = @()
$unresolved = @()
$genericCommands = $astTokens | 
where {$_.tokenflags -eq 'commandname' -AND $_.kind -eq 'generic'} 
$aliases = $astTokens | 
where {$_.tokenflags -eq 'commandname' -AND $_.kind -eq 'identifier'} 
Write-Verbose "Parsing commands"
foreach ($command in $genericCommands) {
       $commands+= Get-Command -Name $command.text -ErrorAction Stop
    Catch {
      $unresolved+= $command.Text
foreach ($command in $aliases) {
       $commands+= Get-Command -Name $command.text -erroraction Stop |
       foreach { 
         #get the resolved command
         Get-Command -Name $_.Definition  
    Catch {
        $unresolved+= $command.Text
Write-Verbose "All commands"
$report+=@"
ALL COMMANDS  
All possible PowerShell commands. This list may not be complete or even correct.
$(($Commands | Sort -Unique | Format-Table -autosize | Out-String).Trim())
Write-Verbose "Unresolved commands"
if ($unresolved) {
    $unresolvedText = $Unresolved | Sort -Unique | Format-Table -autosize | Out-String
    $unresolvedText = "-->None detected"
$report+=@"
UNRESOLVED    
These commands may be called from nested commands or unknown modules.
$unresolvedtext
Write-Verbose "Potentially dangerous commands"
#identify dangerous commands
$danger="Remove","Stop","Disconnect","Suspend","Block",
"Disable","Deny","Unpublish","Dismount","Reset","Resize",
"Rename","Redo","Lock","Hide","Clear"
$danger = $commands | where {$danger -contains $_.verb} | Sort Name | Get-Unique
if ($danger) {
    $dangercommands = $($danger | Format-Table -AutoSize | Out-String).Trim()
    $dangercommands = "-->None detected"
#get type names, some of which may come from parameters
Write-Verbose "Typenames"
$typetokens = $asttokens | where {$_.tokenflags -eq 'TypeName'}
if ($typetokens ) {
  $foundTypes = $typetokens | 
Sort @{expression={$_.text.toupper()}} -unique | 
Select -ExpandProperty Text | foreach { "[$_]"} | Out-String
    $foundTypes = "-->None detected"
$report+=@"
These are identified .NET type names that might be used as accelerators.
$foundTypes
$report+=@"
These are potentially dangerous commands.
$dangercommands
Write-Verbose "Display results"
#region create and display the result
#create a help topic file using the script basename
$basename = (Get-Item $Path).basename     
#stored in the Documents folder
$reportFile = Join-Path -Path $FilePath -ChildPath "ABOUT_$basename.help.txt"
Write-Verbose "Saving report to $reportFile"
#insert the Topic line so help recognizes it
about $basename profile
"@ |Out-File -FilePath $reportFile -Encoding ascii
#create the report
SHORT DESCRIPTION
Script Profile report for: $Path
"@ | Out-File -FilePath $reportFile -Encoding ascii -Append
LONG DESCRIPTION
"@  | Out-File -FilePath $reportFile -Encoding ascii -Append
#view the report with Notepad
Notepad $reportFile
Write-Verbose "Profiling complete."
} #end of function
Provide feedback

Saved searches

Use saved searches to filter your results more quickly

FilesExpand file tree

Get-ASTScriptProfile.ps1

Latest commit

History

Get-ASTScriptProfile.ps1

File metadata and controls
