You can configure rules to determine which script executions to audit and\or block. This document outlines how to configure rules.

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.

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

Properties

Conditions check specific properties to ensure that they meet the given criteria. Below is a list of the available properties.

AMSIBypass

The AMSI Bypass condition detects an attempt to bypass AMSI to allow for execution of malicious script. This condition does not require an operator or value.

<Rule>
    <Conditions>
        <Condition>
            <Property>AmsiBypass</Property>
        </Condition>
    </Conditions>
    <Actions>
        <ActionRef>
            <Name>Block</Name>
        </ActionRef>
    </Actions>
</Rule>

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.

Application

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.

LoggingBypass

This property checks for an attempt to bypass the module and script block logging features of PowerShell. This property does not require an operator or value.

<Rule>
    <Conditions>
        <Condition>
            <Property>LoggingBypass</Property>
        </Condition>
    </Conditions>
    <Actions>
        <ActionRef>
            <Name>Block</Name>
        </ActionRef>
    </Actions>
</Rule>

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.

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 whether 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.

Action References

Rules can define with actions are taken if the rule conditions are satisfied using action references. You can simply use the name of the action in the action reference.

<Actions>
  <ActionRef>
    <Name>File</Name>
  </ActionRef>
  <ActionRef>
    <Name>Block</Name>
  </ActionRef>
</Actions>

Examples

The following example audits and blocks any calls to Invoke-WebRequest.

<?xml version="1.0" encoding="utf-8" ?>
<Configuration>
  <Rules>
    <Rule>
      <Name>Web Request</Name>
      <Conditions>
        <Condition>
          <Property>command</Property>
          <Operator>contains</Operator>
          <Value>invoke-webrequest</Value>
        </Condition>
      </Conditions>
      <Actions>
        <ActionRef>
          <Name>File</Name>
        </ActionRef>
        <ActionRef>
          <Name>Block</Name>
        </ActionRef>
      </Actions>
    </Rule>
  </Rules>
  <Actions>
    <Action>
      <Name>File</Name>
      <Type>File</Type>
      <Settings>
        <Setting>
          <Name>Path</Name>
          <Value>%temp%\test.txt</Value>
        </Setting>
        <Setting>
          <Name>Format</Name>
          <Value>{applicationName},{rule}</Value>
        </Setting>
      </Settings>
    </Action>
    <Action>
      <Name>Block</Name>
      <Type>Block</Type>
    </Action>
  </Actions>
</Configuration>