อัปเดตตัวสร้างโปรไฟล์สคริปต์ PowerShell

ปีที่แล้ว ฉันเขียนแถบด้านข้างสำหรับ Scripting Guy, Ed Wilson และอัปเดตหนังสือ PowerShell Best Practices ของเขา ฉันเขียนสคริปต์โดยใช้ parser ใหม่ใน PowerShell 3.0 เพื่อวิเคราะห์สคริปต์และเตรียมรายงานที่แสดงว่าคำสั่งใดที่จะรัน พารามิเตอร์ที่จำเป็น และสิ่งใดก็ตามที่อาจก่อให้เกิดอันตราย ฉันยังเขียนบทความที่มีสคริปต์สำหรับบล็อก Hey Scripting Guy ด้วย

ในระหว่างชั้นเรียนฝึกอบรม PowerShell ของฉันเมื่อสัปดาห์ที่แล้ว เรากำลังพูดถึงวิธีดูโค้ดของผู้อื่นและดูว่าโค้ดนั้นจะทำอะไรได้บ้าง ฉันยังสาธิตสคริปต์ของฉันด้วย ในระหว่างการสาธิตครั้งนั้น ฉันตระหนักว่าจำเป็นต้องแก้ไขบางอย่าง นี่คือ Get-ASTScriptProfile.ps1 เวอร์ชัน 2

#requires -version 3.0

#Get-ASTScriptProfile.ps1

<#
  ****************************************************************
  * 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.             *
  ****************************************************************
#>

<#
.Synopsis
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.

DETAILS
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.
.Example
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.
.Example
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.

.Notes
Version 2.0
Last Updated January 14, 2014
Jeffery Hicks (http://twitter.com/jeffhicks)

Learn more:
 PowerShell in Depth: An Administrator's Guide (http://www.manning.com/jones2/)
 PowerShell Deep Dives (http://manning.com/hicks/)
 Learn PowerShell 3 in a Month of Lunches (http://manning.com/jones3/)
 Learn PowerShell Toolmaking in a Month of Lunches (http://manning.com/jones4/)
 
.Inputs
None
.Outputs
Help topic
.Link
Get-Command
Get-Alias
#>

[cmdletbinding()]
Param(
[Parameter(Position=0,Mandatory,HelpMessage="Enter the path of a PowerShell script")]
[ValidateScript({Test-Path $_})]
[ValidatePattern( "\.(ps1|psm1|txt)$")]
[string]$Path,
[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)

#endregion

#region generate AST data

#include PowerShell version information
Write-Verbose "PSVersionTable"
Write-Verbose ($PSversionTable | Out-String)

$report=@"
Script Profile report for: $Path

******************
* PSVersionTable *
******************
$(($PSversionTable | Out-String).TrimEnd())

"@

Write-Verbose "Getting requirements and parameters"
$report+=@"

******************
*  Requirements  *
******************
$(($ast.ScriptRequirements | out-string).Trim())

******************
*  Parameters    *
******************
$(($ast.ParamBlock.Parameters | 
 Select Name,DefaultValue,StaticType,Attributes |
 Format-List | Out-String).Trim())
 
"@

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) {
    Try {
       $commands+= Get-Command -Name $command.text -ErrorAction Stop
    }
    Catch {
      $unresolved+= $command.Text
    }
}

foreach ($command in $aliases) {
Try {
       $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  *
******************
$(($Commands | Sort -Unique | Format-Table -autosize | Out-String).Trim())

"@

Write-Verbose "Unresolved commands"
$report+=@"

******************
*  Unresolved    *
******************
$($Unresolved | Sort -Unique | Format-Table -autosize | Out-String)
"@

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}

#get type names, some of which may come from parameters
Write-Verbose "Typenames"
$report+=@"

******************
*  TypeNames     *
******************
$($asttokens | where {$_.tokenflags -eq 'TypeName'} | 
Sort @{expression={$_.text.toupper()}} -unique | 
Select -ExpandProperty Text | Out-String)
"@

$report+=@"

******************
*  Warning       *
******************
$($danger | Format-Table -AutoSize | Out-String)
"@

#endregion

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 "$basename.help.txt"

Write-Verbose "Saving report to $reportFile"
#insert the Topic line so help recognizes it
"TOPIC" | Out-File -FilePath $reportFile -Encoding ascii 

#create the report
$report | Out-File -FilePath $reportFile -Encoding ascii -Append

#view the report with Get-Help and -ShowWindow
Get-Help (Join-Path -Path $FilePath -ChildPath $basename) -ShowWindow

#endregion

Write-Verbose "Profiling complete."

#end of script

สิ่งหนึ่งที่ฉันค้นพบคือ AST ไม่ชอบการแยกวิเคราะห์ไฟล์โดยไม่มีเส้นทางที่สมบูรณ์และได้รับการแก้ไขแล้ว ฉันพบข้อผิดพลาดเนื่องจากสคริปต์อยู่บน PSDrive เช่นเดียวกับ Scripts: ซึ่งแก้ไขเป็น C:\Scripts วิธีแก้ไขคือแก้ไขในกรณีที่ใช้เส้นทางเช่น .\file.ps1 แล้วแปลงเส้นทาง

$Path = (Resolve-Path -Path $Path).Path | Convert-Path

ฉันยังค้นพบด้วยว่าหากสคริปต์มีฟังก์ชันที่มีชื่อเช่น Main หรือ Control parser อย่างน้อยตามวิธีที่ฉันใช้ จะตรวจพบว่าเป็นแอปพลิเคชันเช่น main.cpl มีเหตุผลที่คุณควรตั้งชื่อฟังก์ชันให้มีความหมายและเป็นมาตรฐาน และพยายามหลีกเลี่ยงการใช้ชื่อที่*อาจ*ถูกสะกดผิด ฟังก์ชั่นที่เรียกว่า Notepad อาจไม่ใช่ความคิดที่ดี ฉันแก้ไขความช่วยเหลือเพื่อระบุการตีความที่ผิดที่อาจเกิดขึ้นนี้ ฉันไม่แน่ใจว่ามีอะไรอีกมากมายที่ฉันสามารถทำได้

การเปลี่ยนแปลงอื่นๆ เล็กๆ น้อยๆ ที่ฉันทำคือเพื่อความยืดหยุ่นและความชัดเจน ตอนนี้ฉันรวมข้อมูล PSVersion ไว้ในรายงานแล้ว ข้อมูลพารามิเตอร์จะแสดงเป็นรายการเพื่อหลีกเลี่ยงการสูญเสียข้อมูลใดๆ ฉันเพิ่มพารามิเตอร์การตรวจสอบความถูกต้องสำหรับไฟล์สคริปต์เพื่อให้คุณวิเคราะห์ได้เฉพาะไฟล์ .ps1, .psm1 หรือ .txt เท่านั้น

ในที่สุด ฉันเพิ่มพารามิเตอร์เพื่อให้คุณสามารถระบุโฟลเดอร์สำหรับไฟล์เอาต์พุตได้ ค่าเริ่มต้นคือ Documents\WindowsPowerShell คุณไม่ได้ระบุชื่อไฟล์ เพียงระบุเส้นทางเช่น C:\Scripts หรือ $env:temp

PS Scripts:\> .\Get-ASTScriptProfile.ps1 .\Convert-WindowsImage.ps1 -out c:\work

ซึ่งจะส่งผลให้มีรายงานหัวข้อวิธีใช้ดังนี้: