Rules

Configuring rules for PS Protect.

You can configure rules to determine which script executions to audit and\or block. This document outlines how to configure rules. You can generate rules with the configuration cmdlets.

$Condition = New-PSPCondition -Property "command" -contains -Value "webrequest"
$BlockAction = New-PSPAction -Block
$FileAction = New-PSPAction -File -Format "{applicationName},{rule}" -Path "%temp%\audit.csv" -Name 'File'
$Rule = New-PSPRule -Name "Web Request" -Condition $Condition -Action @($BlockAction, $FileAction)

Conditions

Rules are evaluated based on conditions. Conditions look at various properties of a PowerShell script and execution environment to determine whether the script can run or if it should be audited.

Multiple Conditions

Rules can contain multiple conditions. If all of the conditions are met, the rule will execute the actions defined by the action references.

$Condition = New-PSPCondition -Property "command" -contains -Value "webrequest"
$Condition2 = New-PSPCondition -Property "command" -contains -Value "invoke"
$BlockAction = New-PSPAction -Block
$Rule = New-PSPRule -Name "Web Request" -Condition @($Condition, $Condition1) -Action @($BlockAction, $FileAction)

Properties

Conditions check specific properties to ensure that they meet the given criteria. Below is a list of the available properties. PowerShell Protect takes advantage of the PowerShell Abstract Syntax Tree (AST) to analyzer scripts.

Property Name

Description

Administrator

The administrator property returns true if the current user is an elevated user. This property validates not only that the user has admin privileges but that they also are running a UAC elevated application.

ApplicationName

The application property returns a string that contains information about the application running PowerShell. This may be a process like PowerShell.exe or Pwsh.exe. This could also be a third-party application running the PowerShell engine.

Command

The command property matches commands. PowerShell Protect uses the script's AST to match command executions within a script. Using the command property condition won't match definitions of commands but only executions.

ComputerName

The computer name property matches the current computer's name.

ContentPath

The content path property matches the path of the script that was run. This will be a null string when running a command inside a terminal like PowerShell.exe.

Domain

The domain path property returns the current domain of the user running the command.

DomainController

The domain controller property returns true if the current machine is a domain controller.

Member

The member property matches any .NET property or methods that are executed within the script. This can be helpful for blocking method calls to .NET classes that may invoke low-level APIs that may be undesirable.

Script

The script property returns a string that contains the entire content of the script. You can use this for using basic matching of strings within the script.

String

The string property matches strings within the script. This includes both regular strings and strings that contain variable expansions.

Variable

The variable property matches variables within the script.

Operators

Operators are used for matching properties to values. Below is a list of available operators. None of the operators are case sensitive.

Operator

Description

Contains

Contains determines whether a property contains the value string.

NotContains

NotContains determines whether a property doesn't contain the value string.

EndsWith

EndsWith determines whether a property ends with the value string.

NotEndsWith

NotEndsWith determines whether a property doesn't end with the value string.

Equals

Equals determines the property equals the value string.

NotEquals

NotEquals determines whether the property doesn't equal the value string.

StartsWith

StartsWith determines whether the property starts with the value string.

NotStartsWith

NotStartsWith determines whether the property doesn't start with the value string.

Matches

Matches uses RegEx to determine whether the property matches the value string.

Value

The value is a string to match with the property value during execution. This is a string, boolean or a RegEx.

‚Äč