Power Rules and Regular Expressions

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

Instead of a fixed Default Rule that can either 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 PowerShell script.

Any existing Default Rule within a Workstyle can be updated to a Power Rule by setting the action to a Power Rule script, and importing the PowerShell script you want to use. EPM 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 EPM 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

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: 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 Endpoint Privilege Management to run the application in that context.

For information on creating a Power Rule, see the Core Scripting Guide.

Windows Workstyle Parameters

The Endpoint Privilege Management for Windows settings include a number of features allowing customization of text and strings used for end user messaging and auditing. If you want to include properties relating to the settings applied, the application being used, the user, or the installation of Endpoint Privilege Management for Windows, then parameters may be used which are replaced with the value of the variable at runtime.

Parameters are identified as any string surrounded by brackets ([ ]), and if detected, the Endpoint Privilege Management client attempts to expand the parameter. If successful, the parameter is replaced with the expanded property. If unsuccessful, the parameter remains part of the string. The table below shows a summary of all available parameters and where they are supported.

Parameter	Description
[PG_AGENT_VERSION]	The version of Endpoint Privilege Management for Windows
[PG_APP_DEF]	The name of the Application Rule that matched the application
[PG_APP_GROUP]	The name of the Application Group that contained a matching Application Rule
[PG_AUTH_METHODS]	Lists the authentication and/or authorization methods used to allow the requested action to proceed
[PG_AUTH_USER_DOMAIN]	The domain of the designated user who authorized the application
[PG_AUTH_USER_NAME]	The account name of the designated user who authorized the application
[PG_COM_APPID]	The APPID of the COM component being run
[PG_COM_CLSID]	The CLSID of the COM component being run
[PG_COM_NAME]	The name of the COM component being run
[PG_COMPUTER_DOMAIN]	The name of the domain that the host computer is a member of
[PG_COMPUTER_NAME]	The NetBIOS name of the host computer
[PG_DOWNLOAD_URL]	The full URL from which an application was downloaded
[PG_DOWNLOAD_URL_DOMAIN]	The domain from which an application was downloaded
[PG_EVENT_TIME]	The date and time that the policy matched
[PG_EXEC_TYPE]	The type of execution method: Application Rule or shell rule
[PG_GPO_DISPLAY_NAME]	The display name of the GPO (Group Policy Object)
[PG_GPO_NAME]	The name of the GPO that contained the matching policy
[PG_GPO_VERSION]	The version number of the GPO that contained the matching policy
[PG_IDP_AUTH_USER_NAME]	The value given by the Identify Provider as the user who successfully authenticated to allow the requested action to proceed. Maps to the OIDC "email" scope.
[PG_MESSAGE_NAME]	The name of the custom message that was applied
[PG_POLICY_NAME]	The name of the policy
[PG_PROG_CLASSID]	The ClassID of the ActiveX control
[PG_PROG_CMD_LINE]	The command line of the application being run
[PG_PROG_DRIVE_TYPE]	The type of drive where application is being executed
[PG_PROG_FILE_VERSION]	The file version of the application being run
[PG_PROG_HASH]	The SHA-1 hash of the application being run
[PG_PROG_HASH_SHA256]	The SHA-256 hash of the application being run
[PG_PROG_NAME]	The program name of the application
[PG_PROG_PARENT_NAME]	The file name of the parent application
[PG_PROG_PARENT_PID]	The process identifier of the parent of the application
[PG_PROG_PATH]	The full path of the application file
[PG_PROG_PID]	The process identifier of the application
[PG_PROG_PROD_VERSION]	The product version of the application being run
[PG_PROG_PUBLISHER]	The publisher of the application
[PG_PROG_TYPE]	The type of application being run
[PG_PROG_URL]	The URL of the ActiveX control
[PG_STORE_PACKAGE_NAME]	The package name of the Windows Store App
[PG_STORE_PUBLISHER]	The package publisher of the Windows Store app
[PG_STORE_VERSION]	The package version of the Windows Store app
[PG_TOKEN_NAME]	The name of the built-in token or Custom Token that was applied
[PG_USER_DISPLAY_NAME]	The display name of the user
[PG_USER_DOMAIN]	The name of the domain that the user is a member of
[PG_USER_NAME]	The account name of the user
[PG_WORKSTYLE_NAME]	The name of the Workstyle

Regular Expression Syntax

Use regular expressions to control applications at a granular level. Endpoint Privilege Management uses the CAtlRegExp library, which is part of the Microsoft ATL Server implementation, and makes use of the regex parser and engine.

Examples

The following examples are from Endpoint Privilege Management QuickStart Templates.

Application Definition	Regular Expression	Application
File / Folder Name	%ProgramFiles%( \(x86\))*\\webex\\productivity tools\\ptupdate.exe	Cisco WebEx ptUpdate
File / Folder Name	vcredist_x[0-9][0-9]\.exe	Microsoft Visual C++ Redistributable Setup
File / Folder Name	((rdbgsetup)|(msvsmon))\.exe	Microsoft Visual Studio Remote Debugger
Command line	(powershell_ise.exe)|(powershell.exe)|(cmd.exe)|(wscript.exe)|(cscript)|(mshta.exe)	Any Trusted Executable
Command line arguments	-[rfRM].*[rfRM]\s\W*	rm

Syntax

Metacharacter	Meaning	Example
Any character except [\^$.|?*+()	All characters except the listed special characters match a single instance of themselves. To match one of these listed characters use a backslash escape character (see below).	abc matches abc
\ (backslash)	Escape character: interpret the next character literally.	a\+b matches a+b
. (dot)	Matches any single character.	a.b matches aab, abb or acb, etc.
[ ]	Indicates a character class. Matches any character inside the brackets (for example, [abc] matches a, b, and c).	[abc] matches a, b, or c
^ (caret)	If this metacharacter occurs at the start of a character class, it negates the character class. A negated character class matches any character except those inside the brackets (for example, [^abc] matches all characters except a, b, and c). If ^ is at the beginning of the regular expression, it matches the beginning of the input (for example, ^[abc] will only match input that begins with a, b, or c).	[^abc] matches all characters except a, b, and c
- (minus character)	In a character class, indicates a range of characters (for example, [0-9] matches any of the digits 0 through 9).	[0-9] matches any of the digits 0 through 9
?	Indicates that the preceding expression is optional: it matches once or not at all (for example, [0-9][0-9]? matches 2 and 12).	ab?c matches ac or abc
+	Indicates that the preceding expression matches one or more times (for example, [0-9]+ matches 1, 13, 999, and so on).	ab+c matches abc and abbc, abbbc, etc.
* (asterisk)	Indicates that the preceding expression matches zero or more times	ab*c matches ac and abc, abbc, etc.
| (vertical pipe)	Alternation operator: separates two expressions, exactly one of which matches.	a|b matches a or b
??, +?, *?	Non-greedy versions of ?, +, and *. These match as little as possible, unlike the greedy versions which match as much as possible. Example: given the input <abc><def>, <.*?> matches <abc> while <.*> matches <abc><def>.	Given the input <abc><def>, <.*?> matches <abc> while <.*> matches <abc><def>.
( )	Grouping operator. Example: (\d+,)*\d+ matches a list of numbers separated by commas, such as 1 or 1,23,456.	(One)|(Two) matches One or Two
{ }	Indicates a match group. The actual text in the input that matches the expression inside the braces can be retrieved through the CAtlREMatchContext object.
\	Escape character: interpret the next character literally. For example, [0-9]+ matches one or more digits, but [0-9]\+ matches a digit followed by a plus character. Also used for abbreviations, such as \a for any alphanumeric character; see table below. If \ is followed by a number n, it matches the nth match group (starting from 0). Example: <{.*?}>.*?</\0> matches "<head>Contents</head>". Note that in C++ string literals, two backslashes must be used: "\\+", "\\a", "<{.*?}>.*?</\\0>".	<{.*?}>.*?</\0> matches <head>Contents</head>
$	At the end of a regular expression, this character matches the end of the input. Example: [0-9]$ matches a digit at the end of the input.	[0-9]$ matches a digit at the end of the input
|	Alternation operator: separates two expressions, exactly one of which matches. For example, T|the matches The or the.	T|the matches The or the
!	Negation operator: the expression following ! does not match the input. Example: a!b matches a not followed by b.	a!b matches a not followed by b