Additional Guidance on Using PowerShell

You can use the PowerShell get-help command to get help on any cmdlet in PowerShell. You can also use the following arguments for additional guidance on the cmdlet:

  • -examples
  • -detailed
  • -full
  • -online


Power Rules requires PowerShell 3.0 or later. Run the following command to check the version of PowerShell you are running:


If you attempt to edit an Application Rule containing a Power Rule in a Privilege Management Policy Editor older than v5.3.x, the PowerRuleScript attribute (that is linked to the Power Rule) is removed from the Application Rule.

For more information about compatibility with other Privilege Management for Windows versions, please see the Release Notes for each version.

Third Party Integration Security

When you integrate with a third party, you should ensure you use the most secure mechanism possible. For example, if a vendor offers both HTTP and HTTPS, use HTTPS.

Supported Application Types

All Application Types are supported, with the exception of:

  • Remote PowerShell Script
  • Remote PowerShell Command
  • Windows Service
  • Windows Store Application

If you use these application types with a Power Rule, the rule script will not run and the event will state, Script execution skipped: Application Type not supported. This is an 801 event.


Some restrictions are enforced by the Privilege Management Policy Editor but cannot be enforced in a scripting environment. The following is guidance for creating your Power Rule. If Privilege Management cannot determine the correct course of action, the Default rule is applied.

All messages and tokens must exist in your policy configuration prior to referencing them in a Power Rule script.

  • The Action must match the Message. For example, if the Action is Allow, the message must be of type Allow.
  • If you set the Action to Allow, we assume a passive Token but you can add a different token such as a Custom Token you created.
  • Tokens cannot be used when the action is Block.
  • If you specify an account to run as, your action must be Allow.

If the script fails, a local audit event 801 will be triggered.

If you use Set-PRRunAsProperty, then you need to use Set-PRRuleProperty and set the -Action argument to Allow. You can optionally set the -Token argument. If you do not define a token, then a Passive token is applied.

The values for -Action and -Token are case sensitive.

For more information, please see Script Audit Failure Event.

Script Restrictions

There are some scripting restrictions you need to be aware of when you are creating your own integrations.

Block Comments

Single line comments are supported, but block comments are not. Block comments take the form:

<# block comment #>

PowerShell single line comments are supported.

# comment


The #Requires notation is not supported.

Script Audit Failure Event

If a rule script fails, then a local Windows event is created, and the Privilege Management for Windows event number is 801. This event is always created, even when auditing is turned off. The following fields are shown in the event:

Variable Name Description
RuleScriptFileName Name attribute of the script in the config
RuleScriptName Set by script properties
RuleScriptVersion Set by script properties
RuleScriptPublisher The publisher of the script
RuleScriptRuleAffected Whether a rule script changed a Privilege Management for Windows rule
RuleScriptStatus Timeout, Exception
RuleScriptResult Script timeout exceeded: X seconds, Set Rule Properties failed validation
ExceptionType Any valid .NET exception type
ExceptionMessage The short exception message
ProcessId PID of the process matching the rule
ParentProcessId PID of the parent process matching the rule
ProcessStartTime Time the process started
Event Time Time the script started
UniqueProcessId GUID of process to link this data to associated audit process event

PowerShell Scripting Execution Policy

We recommend using one PowerShell script for each integration you create. If you create a Power Rule script that in turn calls an additional PowerShell script, you need to distribute that PowerShell script independently and may need to change your PowerShell execution policy to ensure it can run.


If you want to maintain signed scripts, you must ensure they are encoded in UTF-16 LE prior to importing them into Privilege Management for Windows. Rule script files exported from the Privilege Management Policy Editor are always encoded in UTF-16 LE.

Settings files are encrypted at the endpoint. Settings files must be encoded in UTF-8.