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
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 an Endpoint 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 Endpoint Privilege Management for Windows versions, 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.
Validation
Some restrictions are enforced by the Endpoint Privilege Management Policy Editor but cannot be enforced in a scripting environment. The following is guidance for creating your Power Rule. If Endpoint 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, 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
#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 Endpoint 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 an Endpoint 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.
Encodings
If you want to maintain signed scripts, you must ensure they are encoded in UTF-16 LE prior to importing them into Endpoint Privilege Management for Windows. Rule script files exported from the Endpoint 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.
