Apply Power Rules Scripts to Your Application Rules

A Power Rule is a PowerShell based framework that lets you change the outcome of an Application Rule, based on the outcome of a PowerShell script.

Rather than a fixed default rule that can be set to Allow, Elevate, Audit, or Block for the applications in the targeted Application Group, a Power Rule lets you determine your own outcome based on any scenario you can build into a Power Shell script.

Any existing default rule within a Workstyle can be updated to a Power Rule simply by setting the action to a Power Rule script, and importing the PowerShell script you want to use. Privilege Management for Windows provides a PowerShell module with an interface to collect information about the user, application, and policy. The module can then send a resulting action back to Privilege Management for Windows to apply.

The Power Rules module also provides a variety of message options that allow you to collect additional information to support your PowerShell script logic and provide updates to the user as to the status, progress, or outcome of your rule. The messages that are supported include:

  • Authentication message
  • Business Justification message
  • Information message
  • Pass code message
  • Vaulted credential message
  • Asynchronous progress dialog for long running tasks

The Power Rule feature is highly flexible, and has unlimited potential. If you can do it in PowerShell, you can do it in a Power Rule. Here are some example use cases for Power Rules:

  • Environmental Factors: Collecting additional information about the application, user, computer, or network status to influence whether an application should be allowed to run, or run with elevated privileges.
  • Service Management: Automatically submitting tickets to IT Service Management solutions, and determining the outcome of a service ticket.
  • File Reputation: Performing additional checks on an application by looking up the file hash in an application store, reputation service, or a vulnerability database.
  • Privileged Access Management: Checking out credentials from a password safe or vault, and passing them back to Privilege Management for Windows to run the application in that context.

Power Rules are best used for exception handling and in conjunction with static policy.

For more information, please see the following:

Power Rules Additional Guidance

You can use the PowerShell get-help command to get help on any cmdlet in PowerShell. You can also use the following arguments to get additional guidance on the cmdlet: -examples, -detailed, -full, and -online.

Compatibility

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

$PSVersionTable.PSVersion

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, you should use HTTPS.

Supported Application Types

All application types are supported, with the following exceptions:

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

If you try to use these application types with a Power Rule, the Rule Script is not executed and the event states:

Script execution skipped: Application Type not supported.

Validation

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 for Windows cannot determine the correct course of action, it applies the default rule.

All Messages and Tokens must exist in your policy configuration prior to being referenced 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 a Custom Token that you have 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 is triggered.

If you use Set-PRRunAsProperty, you need to use Set-PRRuleProperty and set the -Action argument to Allow. You can optionally set the -Token argument. If you don't define a token, then a passive token is applied.

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

Script Restrictions

There are some restrictions that 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

#Requires

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

Encodings

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.