EPM for Windows core scripting

What is Windows core scripting?

A Power Rule 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.

How is it useful?

Any existing Default rule in a Workstyle can be updated to a Power Rule by setting the Run a Rule Script option to a Power Rule script, and importing the PowerShell script you want to use. Endpoint Privilege Management 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 the Endpoint Privilege Management client 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 about the status, progress, or outcome of your rule. The supported messages include:

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

Power Rules is a highly flexible feature with 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: Collect 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 submit tickets to IT Service Management solutions, and determine the outcome of a service ticket.
• File Reputation: Perform additional checks on an application by looking up the file hash in an application store, reputation service, or a vulnerability database.
• Privileged Access Management: Check out credentials from a password safe or vault, and pass them back to Endpoint Privilege Management to run the application in that context.

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

For a list of cmdlets, see PowerShell PRInterface cmdlets.

Get started with Power Rules

This section takes you through creating an example Power Rule, adding it to an Application Rule and seeing it work in Endpoint Privilege Management for Windows.

You need an Endpoint Privilege Management for Windows 5.6 or later environment to run this script.

Example script

This script overrides a Default rule block for all applications where the PG_PROG_PATH variable does not contain cmd.exe.

Create the Power Rule script

1. On the machine where you installed the Endpoint Privilege Management Policy Editor, open Windows Notepad and paste the following code.

$ExecutingProgramPath = Get-PRVariable -Name "PG_PROG_PATH"
$ProgramNameToMatch = 'cmd.exe'
Show-PRMessageDialog -Title 'Rule Script Dialog' -LabelHeader "You just ran: $ExecutingProgramPath. This script will block $ProgramNameToMatch" -ButtonOK 'OK' 
if($ExecutingProgramPath.Contains($ProgramNameToMatch))
{
  Set-PRRuleProperty -Action 'Block' 
}
  else
{
  Set-PRRuleProperty -Action 'Allow'
}

2. Save the file as test-rulescript.ps1, ensuring you specify the ps1 extension.

You can use the Endpoint Privilege Management Policy Editor or the Endpoint Privilege Management ePO Extension to apply the rule script in policy.

Apply the rule script in policy

This summary is intended for those who are familiar with editing policy in Endpoint Privilege Management Policy Editor. If you need more information, see the Administration Guide.

Endpoint Privilege Management Policy Editor

These instructions apply to the Endpoint Privilege Management Policy Editor.

In the Policy Editor:

1. Create a block message called Test Power Rule Block Message. This message displays if the rule script doesn't run.
2. Create an Application Group called Test Power Rule Applications and add both mspaint.exe and cmd.exe as the File or Folder Name in the matching criteria.
3. Create a Workstyle called Test Power Rules Applications and add an Application Rule.

In the Application Rule:

1. Set the Application Group to Test Power Rule Applications from the Target Application Group dropdown list.
2. From the Run a Rule Script dropdown list, select Manage Scripts.
3. From the Rule Scripts node, click Import Script.
4. Navigate to test-rulescript.ps1 and click Open.
5. Click Close on the Script Manager dialog box.
6. Set the Default Action to Block Execution and set the Default End User Message to Test Power Rule Block Message that you created earlier. The default action you choose should always be more restrictive than your Power Rule script.
7. Set Raise an Event to On.
8. Click OK to finish configuring the Application Rule.

You have now configured a Workstyle containing an Application Rule, which in turn targets an Application Group, containing both cmd.exe and mspaint.exe as matching criteria on the File or Folder Name. The Application Rule is configured to run the Power Rule, which blocks the application if the file or folder name contains cmd.exe; otherwise it allows it.

If the Power Rule does not run, the default action is Block, and the Endpoint Privilege Management block message you configured displays.

The next section includes the core integration script on the endpoint.

Endpoint Privilege Management ePO Extension

These instructions apply to the Endpoint Privilege Management ePO Extension.

In the Policy Editor:

1. Create a block message called Test Power Rule Block Message. This message displays if the rule script does not run.
2. Create an Application Group called Test Power Rule Applications and add both mspaint.exe and cmd.exe as the File or Folder Name in the matching criteria.
3. Create a Workstyle called Test Power Rules Applications and add an Application Rule.

In the Application Rule:

1. Set the Application Group to Test Power Rule Applications from the Target Application Group dropdown list.
2. From the Run a Rule Script dropdown list, select test-rulescript.ps1.
3. Set the Default Action to Block Execution and set the Default End User Message to the Test Power Rule Block Message that you created earlier. The default action you choose should always be more restrictive than the Power Rule script.
4. Set Raise an Event to On.
5. Click OK to finish configuring the Application Rule.

You have now configured a Workstyle containing an Application Rule, which in turn targets an Application Group, containing both cmd.exe and mspaint.exe as matching criteria on the File or Folder Name. The Application Rule is configured to run the Power Rule, which blocks the application if the file or folder name contains cmd.exe; otherwise it allows it.

If the Power Rule does not run, the default action is Block, and the Endpoint Privilege Management block message you configured is displayed.

The next section takes you through testing the core integration script on the endpoint.

Run the Power Rule script at the endpoint

You can now use your Endpoint Privilege Management environment to see the results of your Power Rule.

1. Ensure the policy is applied and that you have a valid license.
2. From the Start menu, type cmd.exe and press Return. The Rule Script Dialog displays.
3. When you click OK, cmd.exe does not run because the script stops it. The Default rule properties you set in the script editor are not used because you do not see the Endpoint Privilege Management block message.
4. Run mspaint.exe. You see the message from the script, but it runs successfully.

If you see the Endpoint Privilege Management block message, ensure the Workstyle is enabled, has a valid license, and is configured correctly.

Script examples

Variables, Enable and Catch Logs, Audit Events, Request User Input, and Messages

#Enables logging to file
#Shows business justification dialog and outputs result to log file
#Utilizes Set-ScriptProperty to show name, version and output on event

#Import the PRInterface
Import-Module 'C:\PowerRules\Output\PRInterface\PRInterface.psd1'

#Import the PRTestHarness
Import-Module 'C:\PowerRules\Output\PRTestHarness\PRTestHarness.psd1'

#Instantiate PRTestHarness
$global:DefendpointAccessor = New-PRTestHarness -TestConfig 'C:\PowerRules\Output\PRTestHarness\AddAdmin_ExampleApp.json'

#Set the logging file and location
Set-PRLogSettings -LogToFile $true -LogFilePath "C:\Temp\examplescriptlog.log"

#Declare two variables for the prgram name an program path
$ProgramName = Get-PRVariable -Name "PG_PROG_NAME"
$ProgramPath = Get-PRVariable -Name "PG_PROG_PATH"

#Declare a new variable for the result of the business justification and dialog result
$businessJustificationDialogResult = Show-PRBusinessJustificationDialog -LabelHeader "Please enter a business justification for why you need to run $ProgramName" -Title "Business justification for launching application"

#If the user clicked 'OK', write the business justification they entered to the log file 
If ($businessJustificationDialogResult.DialogResult -eq 'OK') 
{
    Write-PRLog -Message ("Business Justification: {0}" -f 
$businessJustificationDialogResult.BusinessJustification) 
}

#If the user clicked 'Cancel', write the message and $ProgramName out to the log file
ElseIf ($businessJustificationDialogResult.DialogResult -eq 'Cancel') 
{
    Write-PRLog -Message ("User chose to cancel the launch of $ProgramName") 
}

#Sets the script properties, program name and program path to show on events
Set-PRScriptProperty -ScriptName "Example Power Rules Script" -ScriptVersion "1.0.0" -ScriptOutput "User attempted to launch $ProgramName from $ProgramPath"

Variables, Enable and Catch Logs, Change Rule Behavior, and Messages

This example uses the message and token names in the QuickStart policy for Windows version 5.3. Ensure you import this template prior to running this script.

#Import the PRInterface
Import-Module 'C:\PowerRules\Output\PRInterface\PRInterface.psd1'

#Import the PRTestHarness
Import-Module 'C:\PowerRules\Output\PRTestHarness\PRTestHarness.psd1'

#Instantiate PRTestHarness
$global:DefendpointAccessor = New-PRTestHarness -TestConfig 'C:\PowerRules\Output\PRTestHarness\AddAdmin_ExampleApp.json'

#Sets the logging to file and to the console
Set-PRLogSettings -LogToFile $true -LogFilePath "C:\Temp\examplescriptlog.log" 
Set-PRLogSettings -LogToConsole $true

#Declare a new variable for the program path 
$ExecutingProgramPath = Get-PRVariable -Name "PG_PROG_PATH"

#Declare a new variable for the string 'cmd.exe'
$ProgramNameToMatch = 'cmd.exe' 

#Display a message to the user 
Show-PRMessageDialog -Title 'Rule Script Dialog' -LabelHeader "You just ran: $ExecutingProgramPath. This script will block $ProgramNameToMatch" -ButtonOK 'OK'

#Check to see if the variable $ExecutingProgramPath contains 'cmd.exe' 
if($ExecutingProgramPath.Contains($ProgramNameToMatch))
{
    #Set the action to block and the message to the Block Message
    Set-PRRuleProperty -Action 'Block' -Message 'Block Message'
    Write-PRLog -Message 'This application was blocked'
}
else
{
    #Set the action to allow, the message to the Allow Message (Yes / No) and the Token 
    #to the Avecto Support Token
    Set-PRRuleProperty -Action 'Allow' -Message 'Allow Message (Yes / No)' `
    -Token 'Custom' -TokenName 'Avecto Support Token'
    Write-PRLog -Message 'This application was allowed to run'
}

Use the PRInterface and PRTestHarness Modules as well as a Settings file to get the Challenge Code

#Import the PRInterface
Import-Module 'C:\PowerRules\Output\PRInterface\PRInterface.psd1'

#Import the PRTestHarness
Import-Module 'C:\PowerRules\Output\PRTestHarness\PRTestHarness.psd1'

#Instantiate PRTestHarness
$global:DefendpointAccessor = New-PRTestHarness -TestConfig 'C:\PowerRules\Output\PRTestHarness\AddAdmin_ExampleApp.json' 

Get-PRChallengeCode

Use the Set-PRRunAsProperty and a Settings file

Ensure the Settings file is present in the location you specify in the TestSettings parameter for Accessor.

Settings File
{
"Account": {
"UserName": "Stan",
"Password": "Stan"
}
}

#Import the PRInterface
Import-Module 'C:\PowerRules\Output\PRInterface\PRInterface.psd1'

#Import the PRTestHarness
Import-Module 'C:\PowerRules\Output\PRTestHarness\PRTestHarness.psd1'

#Instantiate PRTestHarness
$global:DefendpointAccessor = New-PRTestHarness -TestConfig 'C:\PowerRules\Output\PRTestHarness\AddAdmin_ExampleApp.json' -TestSettings "C:\PowerRules\Settings.json"

# Get Account details from settings file (which is encrypted on endpoint)
$Settings = Get-PRScriptSettings
$AccountName = $Settings.Account.UserName
$Password = $Settings.Account.Password

# Set script properties to appear in audit eventsSet-PRScriptProperty -ScriptName "Run As Demo" -ScriptVersion "1.0.0" -ScriptOutput "Running as $AccountName"

#Set RunAs account properties
Set-PRRunAsProperty -Username "$AccountName" -Password "$Password"

#Set Rule Properties to run
Set-PRRuleProperty -Action "Allow" -Token "Passive"

Set up a script environment to access PowerShell

To create a Power Rules script outside the environment, you must set up a scripting environment. This allows you to access the PowerShell cmdlets you can use to write your script and test it in a mock environment.

The first steps are to import the following modules:

• PRInterface module: Contains the cmdlets you can use for your script. It is installed with EPM for Windows.
• PRTestHarness module: Allows you to mimic the behavior of so the rule script behaves as if was installed.

You can then create an instance of the TestHarness module and provide test data if required.

1. Import the PRInterface module. You can import the module to a different environment if you need to work on a script in a separate environment.
2. Import the PRTestHarness module.
3. Create an instance of the PRTestHarness module. This allows you to work with, and if you choose, stub the PRTestHarness module with test data.

Import the PRInterface PowerShell module

PRInterface is the name of a PowerShell module that provides cmdlets for the Power Rules script to use to pass information to and from . Using it you can:

• Manipulate the behavior of a rule
• Provide information about an event
• Show customizable dialog boxes that display information to, and gather information from, an end user
• Run an application as another user
• Add detail to audit events

You can use the PowerShell cmdlet get-help to view the full help documentation, including examples, in PowerShell.

📘

You must change the paths to point to your PRInterface folder.

You can import the PRInterface modules, so your script mimics the behavior of the PowerShell execution environment. The AddAdmin_ExamplesApp.json file in the PRTestHarness folder contains example data you can use to get started.

For a list of variables, see the for Windows Administration Guide.

To import the PRInterface module:

Import-Module 'C:\PowerRules\PRInterface\PRInterface.psd1'

Import the PRTestHarness PowerShell module

PRTestHarness is a PowerShell module that provides a mechanism for testing Power Rules scripts outside the execution environment. This allows you to simulate an event and run a script in PowerShell ISE to see the resulting behavior. This means you can speed up script development by testing and debugging outside the Power Rules environment.

The test harness mimics the behavior of EPM for Windows. This process is known as stubbing and it allows you to write scripts using the PRInterface module in other PowerShell environments.

You must change the paths to point to your PRTestHarness folder.

To import the PRTestHarness module:

Import-Module 'C:\PowerRules\PRTestHarness\PRTestHarness.psd1'

Stub with PRTestHarness

Each time you want to edit your integration script in a new instance of Windows PowerShell ISE, you need to create a Accessor, and optionally, provide example data to it. This example references the AddAdmin_ExampleApp.json file, which contains example data.

Stub the interface with some test data:

$global:DefendpointAccessor = New-PRTestHarness -TestConfig 'C:\\PowerRules\\PRTestHarness\\AddAdmin_ExampleApp.json'

Test the configuration

You can provide the following arguments to the PRTestHarness cmdlet:

[-TestConfig <string>] [-TestSettings <string>] [<CommonParameters>]

Test the data is coming through from the AddAdmin_ExampleApp.json file:

Get-PRChallengeCode

-TestSettings allows you to also specify a path with file name to a Settings file. Settings files are encrypted on the endpoint so any credentials or sensitive information for your integration are protected.

For more information, see Use a Settings File with a Rule Script File.

PowerShell PRInterface cmdlets

The following cmdlets are available from the PRInterface module. You can run the get-help command in PowerShell to obtain detailed information on each cmdlet, including the syntax and description:

get-help <cmdletname>

Example

get-help Get-PRVariable

PowerShell cmdlets

Use a settings file with a rule script file

A Settings (*.json) file is an optional file you can use in your integration. Settings files are encrypted at the endpoint so they are useful for storing credentials and other sensitive information.

After you associate a Settings file with a rule script (*.ps1), that Settings file is used wherever the rule script is used. If you change the Settings file, the updated Settings file is applied to all rules referencing the rule script.

In EPM for Windows, the two files are intrinsically linked after you associate a Settings file with a rule script.

Test a settings file

Instantiate the PRTestHarness with a Settings file using Accessor.

$Global:defendpointAccessor = New-PRTestHarness -TestConfig "C:\\PowerRules\\PRTestHarness\\AddAdmin_ExampleApp.json" -TestSettings "\\PowerRules\\Settings.json"

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.

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 does not run and the event states Script execution skipped: Application Type not supported. This is an 801 event.

Validation

Some restrictions are enforced by the Policy Editor but cannot be enforced in a scripting environment. The following is guidance for creating your Power Rule. If EPM 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. However, 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 is 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:

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.

Encoding

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.