{"id":555,"date":"2010-01-14T13:54:00","date_gmt":"2010-01-14T18:54:00","guid":{"rendered":"http:\/\/jdhitsolutions.com\/blog\/?p=555"},"modified":"2010-01-14T13:55:34","modified_gmt":"2010-01-14T18:55:34","slug":"profiling-a-script","status":"publish","type":"post","link":"https:\/\/jdhitsolutions.com\/blog\/powershell\/555\/profiling-a-script\/","title":{"rendered":"Profiling a Script"},"content":{"rendered":"

Last summer, Ed Wilson was looking for help with a small part of the book he was finishing up, Windows PowerShell 2.0 Best Practices<\/a>. The topic he was working on was, \u201cHow do I know this script is safe to run?\u201d Which is a great question and one with greater significance as more administrators come to PowerShell and are tempted to run scripts created elsewhere while not having perhaps all the experience and training to fully appreciate what might happen. I offered some comments on some things I would do. I also decided to write a script (trust me) that an administrator could run that would analyze a PowerShell script and produce a report, or profile, for that script.<\/p>\n

<\/p>\n

The version I provided for the book was supposed to be clearly marked as a work in progress.\u00a0 I\u2019ve worked with it on and off since then and it is still a work in progress, but I wanted to offer up the latest version for Ed\u2019s readers and for the PowerShell community.<\/p>\n

\n
\n
#REQUIRES -VERSION 2.0<\/span><\/pre>\n
<\/p>\n
<\/pre>\n
<\/p>\n
<#<\/span><\/pre>\n
<\/p>\n
.Synopsis<\/pre>\n
<\/p>\n
    This script<\/span> will analyze a PowerShell script<\/span> and create a script<\/span> profile.<\/pre>\n
<\/p>\n
.Description<\/pre>\n
<\/p>\n
    This script<\/span> analyze a given Powershell script<\/span> and prepare a script<\/span> profile.  Within this<\/pre>\n
<\/p>\n
    profile you will see what parameters are called in<\/span> the analyzed script<\/span>, where they are called,<\/pre>\n
<\/p>\n
    what PowerShell commands are executed, what functions are defined internally  and if<\/span> the script<\/span><\/pre>\n
<\/p>\n
    is digitally signed.<\/pre>\n
<\/p>\n
<\/pre>\n
<\/p>\n
    The output is written to the pipeline as a document so that you can save it to a file for<\/span> review.<\/pre>\n
<\/p>\n
    If you use the -code parameter, the scripts contents will be included in<\/span> the script<\/span> profile.<\/pre>\n
<\/p>\n
<\/pre>\n
<\/p>\n
    If the analyzed script<\/span> calls another script<\/span>, references another script<\/span> via dot sourcing, or loads<\/pre>\n
<\/p>\n
    additional modules and snapins those references will NOT be analyzed, although you should see the<\/pre>\n
<\/p>\n
    lines of code in<\/span> the script<\/span> profile so that you can analyze and review further.<\/pre>\n
<\/p>\n
.Parameter Script<\/pre>\n
<\/p>\n
    The path to the .ps1 script<\/span> file you want to profile.<\/pre>\n
<\/p>\n
.Parameter Code<\/pre>\n
<\/p>\n
    If specified, then the script<\/span>'s code will be displayed at the end of the profile.<\/span><\/pre>\n
<\/p>\n
.Example<\/pre>\n
<\/p>\n
    PS C:\\> c:\\scripts\\get-scriptprofile foo.ps1 | Out-file FooProfile.txt<\/pre>\n
<\/p>\n
    Save the basic script profile to a text file.<\/pre>\n
<\/p>\n
.Example<\/pre>\n
<\/p>\n
    PS C:\\> c:\\scripts\\get-scriptprofile foo.ps1 -code<\/pre>\n
<\/p>\n
    Display the script profile along with the code from foo.ps1<\/pre>\n
<\/p>\n
.Example<\/pre>\n
<\/p>\n
    PS C:\\scripts> dir test*.ps1 | .\\get-scriptprofile.ps1<\/pre>\n
<\/p>\n
    Build a script profile for every PowerShell script that begins with Test.<\/pre>\n
<\/p>\n
.Inputs<\/pre>\n
<\/p>\n
    Accepts strings as pipelined input<\/pre>\n
<\/p>\n
.Outputs<\/pre>\n
<\/p>\n
    [object]<\/pre>\n
<\/p>\n
.Link<\/pre>\n
<\/p>\n
   Get-Command<\/pre>\n
<\/p>\n
   Get-AuthenticodeSignature<\/pre>\n
<\/p>\n
   About_Functions<\/pre>\n
<\/p>\n
   About_Parameters<\/pre>\n
<\/p>\n
   About_Scripts<\/pre>\n
<\/p>\n
<\/pre>\n
<\/p>\n
.Notes<\/pre>\n
<\/p>\n
 NAME:      Get-ScriptProfile.ps1<\/pre>\n
<\/p>\n
 VERSION:   1.2<\/pre>\n
<\/p>\n
 AUTHOR:    Jeffery Hicks  http:\/\/jdhitsolutions.com\/blog<\/pre>\n
<\/p>\n
 LASTEDIT:  1\/14\/2010<\/pre>\n
<\/p>\n
<\/pre>\n
<\/p>\n
 THIS IS A WORK IN PROGRESS...ESPECIALLY WITH POWERSHELL V2.0 SCRIPTS<\/pre>\n
<\/p>\n
<\/pre>\n
<\/p>\n
 DISCLAIMER AND WARNING:<\/pre>\n
<\/p>\n
    THIS CODE AND INFORMATION ARE PROVIDED \"AS IS\" WITHOUT WARRANTY OF ANY<\/pre>\n
<\/p>\n
    KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE<\/pre>\n
<\/p>\n
    IMPLIED WARRANTIES OF MERCHANTABILITY AND\/OR FITNESS FOR A PARTICULAR PURPOSE.<\/pre>\n
<\/p>\n
    TEST THOROUGHLY IN A NON-PRODUCTION ENVIRONMENT. IF YOU DON'T KNOW WHAT THIS<\/pre>\n
<\/p>\n
    SCRIPT WILL DO...DO NOT RUN IT!<\/pre>\n
<\/p>\n
<\/pre>\n
<\/p>\n
 Microsoft PowerShell Source File -- Created with SAPIEN Technologies PrimalScript 2009<\/pre>\n
<\/p>\n
<\/pre>\n
<\/p>\n
#><\/span><\/pre>\n
<\/p>\n
<\/pre>\n
<\/p>\n
[CmdletBinding()]<\/pre>\n
<\/p>\n
<\/pre>\n
<\/p>\n
#define the parameters<\/span><\/pre>\n
<\/p>\n
Param (<\/pre>\n
<\/p>\n
    [Parameter(<\/pre>\n
<\/p>\n
     ValueFromPipeline=$True,<\/pre>\n
<\/p>\n
     Position=0,<\/pre>\n
<\/p>\n
     Mandatory=$True,<\/pre>\n
<\/p>\n
     HelpMessage=\"Enter a the path and name to a PowerShell script\"<\/span>)]<\/pre>\n
<\/p>\n
     [String[]]$script<\/span>,<\/pre>\n
<\/p>\n
<\/pre>\n
<\/p>\n
    [Parameter(<\/pre>\n
<\/p>\n
     Mandatory=$False,<\/pre>\n
<\/p>\n
     HelpMessage=\"Specify if you want to see the script's code.\"<\/span>)]<\/pre>\n
<\/p>\n
     [switch<\/span>]$code<\/pre>\n
<\/p>\n
     )<\/pre>\n
<\/p>\n
<\/pre>\n
<\/p>\n
<\/pre>\n
<\/p>\n
Begin {<\/pre>\n
<\/p>\n
<\/pre>\n
<\/p>\n
    $ErrorActionPreference=\"SilentlyContinue\"<\/span><\/pre>\n
<\/p>\n
<\/pre>\n
<\/p>\n
    #get command information for all current aliaes, functions, filters,cmdlets<\/span><\/pre>\n
<\/p>\n
    #and external scripts<\/span><\/pre>\n
<\/p>\n
<\/pre>\n
<\/p>\n
    $cmdHash=@{}<\/pre>\n
<\/p>\n
<\/pre>\n
<\/p>\n
    Get-Command -CommandType Alias,Function,Filter,ExternalScript,Cmdlet | foreach<\/span> {<\/pre>\n
<\/p>\n
      $cmdHash.add($_.name,$_.CommandType)<\/pre>\n
<\/p>\n
      }<\/pre>\n
<\/p>\n
<\/pre>\n
<\/p>\n
    #define some variables<\/span><\/pre>\n
<\/p>\n
    $Activity=\"Script Profiling\"<\/span><\/pre>\n
<\/p>\n
<\/pre>\n
<\/p>\n
} #end Begin Scriptblock<\/span><\/pre>\n
<\/p>\n
<\/pre>\n
<\/p>\n
Process {<\/pre>\n
<\/p>\n
    If (-Not (Test-Path $script<\/span>)) {<\/pre>\n
<\/p>\n
      Write-Warning \"Cannot find $script.\"<\/span><\/pre>\n
<\/p>\n
      return<\/span><\/pre>\n
<\/p>\n
    }<\/pre>\n
<\/p>\n
<\/pre>\n
<\/p>\n
    $fullname=(Get-Item $script<\/span>).Fullname<\/pre>\n
<\/p>\n
<\/pre>\n
<\/p>\n
    Write-Progress -Activity $Activity -Status \"Analyzing $script\"<\/span> -CurrentOperation \"Testing Signature\"<\/span> -PercentComplete 10<\/pre>\n
<\/p>\n
    write `n<\/pre>\n
<\/p>\n
    write $fullname.ToUpper()<\/pre>\n
<\/p>\n
    write (\"Digital Signature: {0}\"<\/span> -f (Get-AuthenticodeSignature $script<\/span>).status)<\/pre>\n
<\/p>\n
<\/pre>\n
<\/p>\n
    Write-Progress -Activity $Activity -Status \"Analyzing $script\"<\/span> -CurrentOperation \"Parsing content\"<\/span> -PercentComplete 20<\/pre>\n
<\/p>\n
<\/pre>\n
<\/p>\n
    $data=Get-Command $fullname<\/pre>\n
<\/p>\n
    $content=($data.scriptContents).Split(\"`n\"<\/span>)<\/pre>\n
<\/p>\n
<\/pre>\n
<\/p>\n
    #get any requires<\/span><\/pre>\n
<\/p>\n
    Write-Progress -Activity $Activity -Status \"Analyzing $script\"<\/span> -CurrentOperation \"Checking for requirements\"<\/span> -PercentComplete 30<\/pre>\n
<\/p>\n
<\/pre>\n
<\/p>\n
    write `n<\/pre>\n
<\/p>\n
    write \"`nRequires\"<\/span><\/pre>\n
<\/p>\n
    write \"--------\"<\/span><\/pre>\n
<\/p>\n
    $content | where {$_.ToLower() -match<\/span> \"requires -\"<\/span>} | foreach<\/span> {<\/pre>\n
<\/p>\n
     #parse the requirement and get everything to the left of the first dash<\/span><\/pre>\n
<\/p>\n
      $_.Substring($_.IndexOf(\"-\"<\/span>)+1).ToLower()<\/pre>\n
<\/p>\n
    } |select -unique<\/pre>\n
<\/p>\n
<\/pre>\n
<\/p>\n
    #strip out commented lines<\/span><\/pre>\n
<\/p>\n
    $content=$content | where {$_ -notmatch<\/span> \"^\\s*#\"<\/span>}<\/pre>\n
<\/p>\n
<\/pre>\n
<\/p>\n
    Write-Progress -Activity $Activity -Status \"Analyzing $script\"<\/span> -CurrentOperation \"Parsing Parameters\"<\/span> -PercentComplete 45<\/pre>\n
<\/p>\n
    write \"`nParameters\"<\/span><\/pre>\n
<\/p>\n
    write \"----------\"<\/span><\/pre>\n
<\/p>\n
<\/pre>\n
<\/p>\n
    $params=@()<\/pre>\n
<\/p>\n
    $data.parameters.values  | foreach<\/span> {<\/pre>\n
<\/p>\n
     $params+=$_.name<\/pre>\n
<\/p>\n
     $_ | select Name,ParameterType<\/pre>\n
<\/p>\n
     }<\/pre>\n
<\/p>\n
<\/pre>\n
<\/p>\n
    write \"`nParameter usage\"<\/span><\/pre>\n
<\/p>\n
    write \"---------------\"<\/span><\/pre>\n
<\/p>\n
    $content | foreach<\/span> {<\/pre>\n
<\/p>\n
     $line=$_<\/pre>\n
<\/p>\n
     $params | foreach<\/span> {<\/pre>\n
<\/p>\n
       if<\/span> ($_ -eq<\/span> \"?\"<\/span>) {<\/pre>\n
<\/p>\n
          $key=\"\\$_\"<\/span><\/pre>\n
<\/p>\n
          [regex]$r=\"$key\"<\/span><\/pre>\n
<\/p>\n
       }<\/pre>\n
<\/p>\n
       else<\/span> {<\/pre>\n
<\/p>\n
          $key=\"$_\"<\/span><\/pre>\n
<\/p>\n
         [regex]$r=\"\\b$key\\b\"<\/span><\/pre>\n
<\/p>\n
       }<\/pre>\n
<\/p>\n
       if<\/span> ($line -match<\/span> $r) {<\/pre>\n
<\/p>\n
         write $line.Trim()<\/pre>\n
<\/p>\n
       } #end if<\/span><\/pre>\n
<\/p>\n
     } #end foreach param<\/span><\/pre>\n
<\/p>\n
<\/pre>\n
<\/p>\n
     #select only unique lines to weed out<\/span><\/pre>\n
<\/p>\n
     #multiple matches for the same line<\/span><\/pre>\n
<\/p>\n
    } | select -Unique #end foreach line<\/span><\/pre>\n
<\/p>\n
<\/pre>\n
<\/p>\n
    Write-Progress -Activity $Activity -Status \"Analyzing $script\"<\/span> -CurrentOperation \"Parsing defined functions\"<\/span> -PercentComplete 60<\/pre>\n
<\/p>\n
<\/pre>\n
<\/p>\n
    write \"`nInternally Defined Functions\"<\/span><\/pre>\n
<\/p>\n
    write \"----------------------------\"<\/span><\/pre>\n
<\/p>\n
    $content | foreach<\/span> {<\/pre>\n
<\/p>\n
      if<\/span> ($_ -match<\/span> \"function \\w*.\\w*\"<\/span>) {$matches.values}<\/pre>\n
<\/p>\n
    }<\/pre>\n
<\/p>\n
<\/pre>\n
<\/p>\n
    Write-Progress -Activity $Activity -Status \"Analyzing $script\"<\/span> -CurrentOperation \"Parsing commands\"<\/span> -PercentComplete 75<\/pre>\n
<\/p>\n
    write \"`nInvoked Commands\"<\/span><\/pre>\n
<\/p>\n
    write \"----------------\"<\/span><\/pre>\n
<\/p>\n
    $content | foreach<\/span> {<\/pre>\n
<\/p>\n
     $line=$_<\/pre>\n
<\/p>\n
     $cmdHash.keys | foreach<\/span> {<\/pre>\n
<\/p>\n
     #escape the ? which is a special regex character<\/span><\/pre>\n
<\/p>\n
       if<\/span> ($_ -eq<\/span> \"?\"<\/span>) {<\/pre>\n
<\/p>\n
          $key=\"\\$_\"<\/span><\/pre>\n
<\/p>\n
          [regex]$r=\"$key\"<\/span><\/pre>\n
<\/p>\n
       }<\/pre>\n
<\/p>\n
       else<\/span> {<\/pre>\n
<\/p>\n
          $key=\"$_\"<\/span><\/pre>\n
<\/p>\n
         [regex]$r=\"\\b$key\\b\"<\/span><\/pre>\n
<\/p>\n
       }<\/pre>\n
<\/p>\n
       if<\/span> ($line -match<\/span> $r) {<\/pre>\n
<\/p>\n
         write $line.Trim()<\/pre>\n
<\/p>\n
       } #end if<\/span><\/pre>\n
<\/p>\n
     } #end foreach key<\/span><\/pre>\n
<\/p>\n
<\/pre>\n
<\/p>\n
    } | select -unique #end foreach content line<\/span><\/pre>\n
<\/p>\n
<\/pre>\n
<\/p>\n
    If ($code) {<\/pre>\n
<\/p>\n
        Write-Progress -Activity $Activity -Status \"Analyzing $script\"<\/span> -CurrentOperation \"Getting script contents\"<\/span> -PercentComplete 90<\/pre>\n
<\/p>\n
        #write script contents if -code was specified<\/span><\/pre>\n
<\/p>\n
        write \"`nScript Contents\"<\/span><\/pre>\n
<\/p>\n
        write \"---------------\"<\/span><\/pre>\n
<\/p>\n
        write $data.scriptcontents<\/pre>\n
<\/p>\n
    }<\/pre>\n
<\/p>\n
} #end Process script block<\/span><\/pre>\n
<\/p>\n
<\/pre>\n
<\/p>\n
End {<\/pre>\n
<\/p>\n
    Write-Progress -Activity $Activity -Status \"Done!\"<\/span> -CurrentOperation \"Finished\"<\/span> -Completed -PercentComplete 100<\/pre>\n
<\/p>\n
} #end End script block<\/span><\/pre>\n
<\/p>\n
<\/pre>\n
<\/p>\n
#end of script<\/span><\/pre>\n
<\/p>\n
<\/pre>\n
<\/p>\n<\/div>\n<\/div>\n
The script, Get-ScriptProfile.ps1 requires PowerShell 2.0 and essentially is a giant string parser. It works pretty well with basic PowerShell 1.0 scripts. The basic syntax is to run the profile script and pass it a PowerShell script as a parameter.<\/p>\n
PS C:\\> c:\\scripts\\get-scriptprofile foo.ps1<\/p>\n
The profiling script will report:<\/p>\n