How To Use PowerShell's Abstract Syntax Tree To Your Advantage

The PowerShell AST essentially breaks down the code into a hierarchical tree with each element representing a part of the tree, making the scripts self aware.

Have you ever seen the movie Inception? It's about a guy that can enter someone's dreams and steal stuff from their subconscious. It's a trip that will leave you questioning the reality around you. It gave me that same feeling as The Matrix did, like reality is not what you believe it to be. It's some deep stuff. This has nothing to do with PowerShell, but it gives you a sense of what the PowerShell Abstract Syntax Tree (AST) does.

Imagine a PowerShell script that is self-aware. Imagine a PowerShell script that can read itself, or even generate other scripts based on what's contained in itself. Think of it as meta-scripting. It's a neat concept and has a lot of practical uses! This is what the PowerShell AST can do. The PowerShell AST essentially breaks down the code into a hierarchical tree with each element representing a part of the tree.

In this article, I'm going to go over how you can use the PowerShell AST and go over a few examples of how it works to parse PowerShell code.

To get started, you'll need to get familiar with the System.Management.Automation.Language.Parser class. This is a class that contains a few applicable static methods that we can use to read scripts and code. This class has two methods that you'll routinely use called ParseInput() and ParseFile(), which essentially do the same thing. ParseInput() reads code as a big string while ParseFile() assists you in converting a text file containing PowerShell code and converts it into a string for parsing. Both end up with the same result.

Let's say I have a simple script with the following lines:

Write-Host 'I am doing something here'
 Write-Verbose 'I am doing something here too'
 Write-Host 'Again, doing something.'
 $var1 = 'abc'
 $var2 = '123'

From within the script itself, I'd like to determine all the references to each cmdlet I have and each variable. To do this, I'll first need to figure out a way to get the entire script contents as one, big string. I can do that by using the $MyInvocation.MyCommand.ScriptContents property. I'll just add this as the last line in the script and execute it.

Once I have the script contents, I can then pass this to the ParseInput() method as mentioned above to build a "tree" from my script. I'll replace that $MyInvocation.MyCommand.ScriptContents reference with below:

[System.Management.Automation.Language.Parser]::ParseInput($MyInvocation.MyCommand.ScriptContents, [ref]$null, [ref]$null)

This gets me an output that looks like this:

PS> C:\test.ps1
 I am doing something here
 Again, doing something.
 
 
 Attributes         : {}
 UsingStatements    : {}
 ParamBlock         :
 BeginBlock         :
 ProcessBlock       :
 EndBlock           : Write-Host 'I am doing something here'
                      Write-Verbose 'I am doing something here too'
                      Write-Host 'Again, doing something.'
                      $var1 = 'abc'
                      $var2 = '123'
                      [System.Management.Automation.Language.Parser]::ParseInput($MyInvocation.MyCommand.ScriptContents,
                       [ref]$null, [ref]$null)
 DynamicParamBlock  :
 ScriptRequirements :
 Extent             : Write-Host 'I am doing something here'
                      Write-Verbose 'I am doing something here too'
                      Write-Host 'Again, doing something.'
                      $var1 = 'abc'
                      $var2 = '123'
                      [System.Management.Automation.Language.Parser]::ParseInput($MyInvocation.MyCommand.ScriptContents,
                       [ref]$null, [ref]$null)
 
 Parent             :

This doesn't do much good, though. I'd like a way to look into this and find only the function and variables contained in my script. To do that, I'll need to assign our AST to a variable. I'll call mine $ast.

PS> $ast = C:\test.ps1

This gets me an object that has various methods and properties I can now use.

PS> $ast | gm
 
 
    TypeName: System.Management.Automation.Language.ScriptBlockAst
 
 Name               MemberType Definition
 ----               ---------- ----------
 Copy               Method     System.Management.Automation.Language.Ast Copy()
 Equals             Method     bool Equals(System.Object obj)
 Find               Method     System.Management.Automation.Language.Ast Find(System.Func[System.Management.Automatio...
 FindAll            Method     System.Collections.Generic.IEnumerable[System.Management.Automation.Language.Ast] Find...
 GetHashCode        Method     int GetHashCode()
 GetHelpContent     Method     System.Management.Automation.Language.CommentHelpInfo GetHelpContent()
 GetScriptBlock     Method     scriptblock GetScriptBlock()
 GetType            Method     type GetType()
 SafeGetValue       Method     System.Object SafeGetValue()
 ToString           Method     string ToString()
 Visit              Method     System.Object Visit(System.Management.Automation.Language.ICustomAstVisitor astVisitor...
 Attributes         Property   System.Collections.ObjectModel.ReadOnlyCollection[System.Management.Automation.Languag...
 BeginBlock         Property   System.Management.Automation.Language.NamedBlockAst BeginBlock {get;}
 DynamicParamBlock  Property   System.Management.Automation.Language.NamedBlockAst DynamicParamBlock {get;}
 EndBlock           Property   System.Management.Automation.Language.NamedBlockAst EndBlock {get;}
 Extent             Property   System.Management.Automation.Language.IScriptExtent Extent {get;}
 ParamBlock         Property   System.Management.Automation.Language.ParamBlockAst ParamBlock {get;}
 Parent             Property   System.Management.Automation.Language.Ast Parent {get;}
 ProcessBlock       Property   System.Management.Automation.Language.NamedBlockAst ProcessBlock {get;}
 ScriptRequirements Property   System.Management.Automation.Language.ScriptRequirements ScriptRequirements {get;}
 UsingStatements    Property   System.Collections.ObjectModel.ReadOnlyCollection[System.Management.Automation.Languag...

The most useful method to use is the FindAll() method. This is a method that allows you to query the AST itself looking for particular types of language constructs. In our case, we're looking for function calls and variable assignments.

Read: Managing IIS Web Application Pools In PowerShell

To only find the language constructs we're looking for, we must first figure out what class is represented by each type. In our examples, those classes are CommandAst for function calls and VariableExpression for variable assignments. You can view all of the different class types at the MSDN System.Management.Automation.Language namespace page.

Here I will find all of the function references.

PS> $ast.FindAll({$args[0] -is [System.Management.Automation.Language.CommandAst]}, $true)
 
 CommandElements    : {Write-Host, 'I am doing something here'}
 InvocationOperator : Unknown
 DefiningKeyword    :
 Redirections       : {}
 Extent             : Write-Host 'I am doing something here'
 Parent             : Write-Host 'I am doing something here'
 
 CommandElements    : {Write-Verbose, 'I am doing something here too'}
 InvocationOperator : Unknown
 DefiningKeyword    :
 Redirections       : {}
 Extent             : Write-Verbose 'I am doing something here too'
 Parent             : Write-Verbose 'I am doing something here too'
 
 CommandElements    : {Write-Host, 'Again, doing something.'}
 InvocationOperator : Unknown
 DefiningKeyword    :
 Redirections       : {}
 Extent             : Write-Host 'Again, doing something.'
 Parent             : Write-Host 'Again, doing something.'

Let's now find all of the variable assignments as well.

PS> $ast.FindAll({$args[0] -is [System.Management.Automation.Language.VariableExpressionAst]},$true)
 
 ariablePath : var1
 Splatted     : False
 StaticType   : System.Object
 Extent       : $var1
 Parent       : $var1 = 'abc'
 
 VariablePath : var2
 Splatted     : False
 StaticType   : System.Object
 Extent       : $var2
 Parent       : $var2 = '123'
 
 VariablePath : MyInvocation
 Splatted     : False
 StaticType   : System.Object
 Extent       : $MyInvocation
 Parent       : $MyInvocation.MyCommand
 
 VariablePath : null
 Splatted     : False
 StaticType   : System.Object
 Extent       : $null
 Parent       : [ref]$null
 
 VariablePath : null
 Splatted     : False
 StaticType   : System.Object
 Extent       : $null
 Parent       : [ref]$null

You can see that each construct now becomes an object you can work with. You now have the knowledge to break apart your script in just about any way you'd like. By using the AST, your PowerShell scripts now can become self-aware. Just don't blame me when your scripts start trying to take your job themselves!