Application definitions

Unlike other application types, Endpoint Privilege Management for Windows only manages the privileges for the installation of ActiveX controls. ActiveX controls usually require administrative rights to install, but once installed, run with the standard privileges of the web browser.

Matching criteria:

• ActiveX Codebase matches
• CLSID matches
• ActiveX Version matches

Matching criteria:

• File or Folder Name matches
• Command Line matches
• Drive matches
• File Hash (SHA-1) matches
• File Hash (SHA-256) matches
• Trusted Ownership matches
• Application Requires Elevation (UAC)
• Parent Process matches
• Source URL matches
• BeyondTrust Zone Identifier exists

A COM elevation is an elevation typically initiated from Explorer, when an integrated task requires administrator rights. Explorer uses COM to launch the task with admin rights, without having to elevate Explorer. Every COM class has a unique identifier, called a CLSID, that is used to launch the task.

COM tasks usually trigger a Windows UAC prompt because they need administrative privileges to proceed. EPM allows you to target specific COM CLSIDs and assign privileges to the task without granting full administration rights to the user. COM based UAC prompts can also be targeted and replaced with custom messaging, where COM classes can be allowlisted and/or audited.

COM classes are hosted by a COM server DLL or EXE, so COM classes can be validated from properties of the hosting COM server. You can configure:

Matching criteria:

• File or Folder Name matches
• Drive matches
• File Hash (SHA-1) matches
• File Hash (SHA-256) matches
• Product Name matches
• Publisher matches
• CLSID matches
• App ID matches
• COM Display Name matches
• Product Description matches
• Product Version matches
• File Version matches
• Trusted Ownership matches
• Application Requires Elevation (UAC): Match if Application Requires Elevation (User Account Control) is always enabled, as COM classes require UAC to elevate
• Source URL matches

Matching criteria:

• File or Folder Name matches
• Command Line matches
• Drive matches
• File Hash (SHA-1) matches
• File Hash (SHA-256) matches
• Product Name matches
• Publisher matches
• Product Description matches
• Product Version matches
• File Version matches
• Trusted Ownership matches
• Application Requires Elevation (UAC)
• Parent Process matches
• Source URL matches
• BeyondTrust Zone Identifier exists

Matching criteria:

• File or Folder Name matches
• Command Line matches
• Drive matches
• File Hash (SHA-1) matches
• File Hash (SHA-256) matches
• Product Name matches
• Publisher matches
• Product Description matches
• Product Version matches
• File Version matches
• Trusted Ownership matches
• Application Requires Elevation (UAC)
• Parent Process matches
• Source URL matches
• BeyondTrust Zone Identifier exists

EPM allows standard users to install and uninstall Windows Installer packages that normally require local admin rights. The following package types are supported:

• Microsoft Software Installers (MSI)
• Microsoft Software Updates (MSU)
• Microsoft Software Patches (MSP)

When a Windows Installer package is added to an Application Group, and assigned to an Application Rule or On-Demand Application Rule, the action will be applied to both the installation of the file, and also uninstallation when using Add/Remove Programs or Programs and Features.

ℹ️

Note

The publisher property of an MSx file may sometimes differ to the publisher property once installed in Programs and Features. We therefore recommend applications targeted using the Match Publisher validation rule are tested for both installation and uninstallation, prior to deployment, using the EPM Activity Viewer.

Installer packages typically create child processes as part of the overall installation process. Therefore, we recommend when elevating MSI, MSU, or MSP packages, that the advanced option Allow child processes will match this application definition is enabled.

ℹ️

Note

If you want to apply more granular control over installer packages and their child processes, use the Child Process validation rule to allowlist or blocklist those processes that will or will not inherit privileges from the parent software installation.

Matching criteria:

• File or Folder Name matches
• Command Line matches
• Drive matches
• File Hash (SHA-1) matches
• File Hash (SHA-256) matches
• Product Name matches
• Publisher matches
• Product Version matches
• Product Code matches
• Upgrade Code matches
• Trusted Ownership matches
• Application Requires Elevation (UAC)
• Parent Process matches
• Source URL matches
• BeyondTrust Zone Identifier exists

Matching criteria:

• File or Folder Name matches
• Command Line matches
• Drive matches
• File Hash (SHA-1) matches
• File Hash (SHA-256) matches
• Publisher matches
• Trusted Ownership matches
• Application Requires Elevation (UAC)
• Parent Process matches
• Source URL matches
• BeyondTrust Zone Identifier exists

Endpoint Privilege Management for Windows allows you to target specific PowerShell scripts and assign privileges to the script without granting local administration rights to the user. Scripts can also be blocked if they are not authorized or allowlisted.

ℹ️

Note

PowerShell scripts that contain only a single line are interpreted and matched as a PowerShell command, and will not match a PowerShell script definition. We recommend PowerShell scripts contain at least two lines of commands to ensure they are correctly matched as a PowerShell script. This cannot be achieved by adding a comment to the script.

Matching criteria:

• File or Folder Name matches
• Command Line matches
• Drive matches
• File Hash (SHA-1) matches
• File Hash (SHA-256) matches
• Publisher matches
• Trusted Ownership matches
• Parent Process matches
• Source URL matches
• BeyondTrust Zone Identifier exists

Example PowerShell configurations

Create new configuration, save to local file

# Import both Defendpoint cmdlet module
Import-Module 'C:\Program Files\Avecto\Privilege Guard Client\PowerShell\Avecto.Defendpoint.Cmdlets\Avecto.Defendpoint.Cmdlets.dll'
# Create a new variable containing a new Defendpoint Configuration Object
$PGConfig = New-Object Avecto.Defendpoint.Settings.Configuration


## Add License ##
# Create a new license object
$PGLicence = New-Object Avecto.Defendpoint.Settings.License
# Define license value
$PGLicence.Code = "5461E0D0-DE30-F282-7D67-A7C6-B011-2200"
# Add the License object to the local PG Config file
$PGConfig.Licenses.Add($PGLicence)

## Add Application Group ##
# Create an Application Group object
$AppGroup = new-object Avecto.Defendpoint.Settings.ApplicationGroup
# Define the value of the Application Group name
$AppGroup.name = "New App Group"
# Add the Application Group object to the local PG Config file
$PGConfig.ApplicationGroups.Add($AppGroup)

## Add Application ##
# Create an application object
$PGApplication = new-object Avecto.Defendpoint.Settings.Application $PGConfig
# Use the Get-DefendpointFileInformation to target Windows Calculator
$PGApplication = Get-DefendpointFileInformation -Path C:\windows\system32\calc.exe
# Add the application to the Application group
$PGConfig.ApplicationGroups[0].Applications.AddRange($PGApplication)

## Add Message ##
# Create a new message object
$PGMessage = New-Object Avecto.Defendpoint.Settings.message $PGConfig
#Define the message Name, Description and OK action and the type of message
$PGMessage.Name = "Elevation Prompt"
$PGMessage.Description = "An elevation message"
$PGMessage.OKAction = [Avecto.Defendpoint.Settings.Message+ActionType]::Proceed
$PGMessage.Notification = 0
# Define whether the message is displayed on a secure desktop
$PGMessage.ShowOnIsolatedDesktop = 1
# Define How the message contains
$PGMessage.HeaderType = [Avecto.Defendpoint.Settings.message+MsgHeaderType]::Default
$PGMessage.HideHeaderMessage = 0
$PGMessage.ShowLineOne = 1
$PGMessage.ShowLineTwo = 1
$PGMessage.ShowLineThree = 1
$PGMessage.ShowReferLink = 0
$PGMessage.ShowCancel = 1
$PGMessage.ShowCRInfoTip = 0
# Define whether a reason settings
$PGMessage.Reason = [Avecto.Defendpoint.Settings.message+ReasonType]::None
$PGMessage.CacheUserReasons = 0
# Define authorization settings
$PGMessage.PasswordCheck = 
Avecto.Defendpoint.Settings.message+AuthenticationPolicy]::None
$PGMessage.AuthenticationType = [Avecto.Defendpoint.Settings.message+MsgAuthenticationType]::Any
$PGMessage.RunAsAuthUser = 0
# Define Message strings
$PGMessage.MessageStrings.Caption = "This is an elevation message"
$PGMessage.MessageStrings.Header = "This is an elevation message header"
$PGMessage.MessageStrings.Body = "This is an elevation message body"
$PGMessage.MessageStrings.ReferURL = "http:\\www.bbc.co.uk"
$PGMessage.MessageStrings.ReferText = "This is an elevation message refer"
$PGMessage.MessageStrings.ProgramName = "This is a test Program Name"
$PGMessage.MessageStrings.ProgramPublisher = "This is a test Program Publisher"
$PGMessage.MessageStrings.PublisherUnknown = "This is a test Publisher Unknown"
$PGMessage.MessageStrings.ProgramPath = "This is a test Path"
$PGMessage.MessageStrings.ProgramPublisherNotVerifiedAppend = "This is a test verification failure"
$PGMessage.MessageStrings.RequestReason = "This is a test Request Reason"
$PGMessage.MessageStrings.ReasonError = "This is a test Reason Error"
$PGMessage.MessageStrings.Username = "This is a test Username"
$PGMessage.MessageStrings.Password = "This is a test Password"
$PGMessage.MessageStrings.Domain = "This is a test Domain"
$PGMessage.MessageStrings.InvalidCredentials = "This is a test Invalid Creds"
$PGMessage.MessageStrings.OKButton = "OK"
$PGMessage.MessageStrings.CancelButton = "Cancel"
# Add the PG Message to the PG Configuration
$PGConfig.Messages.Add($PGMessage)

## Add custom Token ##
# Create a new custom Token object
$PGToken = New-Object Avecto.Defendpoint.Settings.Token
# Define the Custom Token settings
$PGToken.Name = "Custom Token 1"
$PGToken.Description = "Custom Token 1"
$PGToken.ClearInheritedPrivileges = 0
$PGToken.SetAdminOwner = 1
$PGToken.EnableAntiTamper = 0
$PGToken.IntegrityLevel = Avecto.Defendpoint.Settings.Token+IntegrityLevelType]::High
# Add the Custom Token to the PG Configuration
$PGConfig.Tokens.Add($PGToken)

## Add Policy ##
# Create new policy object
$PGPolicy = new-object Avecto.Defendpoint.Settings.Policy $PGConfig
# Define policy details
$PGPolicy.Disabled = 0
$PGPolicy.Name = "Policy 1"
$PGPolicy.Description = "Policy 1"
# Add the policy to the PG Configurations
$PGConfig.Policies.Add($PGPolicy)

## Add Policy Rule ##
# Create a new policy rule
$PGPolicyRule = New-Object Avecto.Defendpoint.Settings.ApplicationAssignment PGConfig
# Define the Application rule settings
$PGPolicyRule.ApplicationGroup = $PGConfig.ApplicationGroups[0]
$PGPolicyRule.BlockExecution = 0
$PGPolicyRule.ShowMessage = 1
$PGPolicyRule.Message = $PGConfig.Messages[0]
$PGPolicyRule.TokenType = [Avecto.Defendpoint.Settings.Assignment+TokenTypeType]::AddAdmin
$PGPolicyRule.Audit = [Avecto.Defendpoint.Settings.Assignment+AuditType]::On
$PGPolicyRule.PrivilegeMonitoring = [Avecto.Defendpoint.Settings.Assignment+AuditType]::Off
$PGPolicyRule.ForwardEPO = 0
$PGConfig.Policies[0].ApplicationAssignments.Add($PGPolicyRule)

## Set the Defendpoint configuration to a local file and prompt for user confirmation ##
Set-DefendpointSettings -SettingsObject $PGConfig -Localfile –Confirm

Open local user policy, modify then save

# Import the Defendpoint cmdlet module
Import-Module 'C:\Program Files\Avecto\Privilege Guard Client\PowerShell\Avecto.Defendpoint.Cmdlets\Avecto.Defendpoint.Cmdlets.dll'
# Get the local file policy Defendpoint Settings
$PGConfig = Get-DefendpointSettings -LocalFile
# Disable a policy
$PGPolicy = $PGConfig.Policies[0]
$PGPolicy.Disabled = 1
$PGConfig.Policies[0] = $PGPolicy
# Remove the PG License
$TargetLicense = $PGConfig.Licenses[0]
$PGConfig.Licenses.Remove($TargetLicense)
# Update an existing application definition to match on Filehash
$UpdateApp = $PGConfig.ApplicationGroups[0].Applications[0]
$UpdateApp.CheckFileHash = 1
$PGConfig.ApplicationGroups[0].Applications[0] = $UpdateApp
# Set the Defendpoint configuration to the local file policy and prompt for user confirmation
Set-DefendpointSettings -SettingsObject $PGConfig -LocalFile -Confirm

Open local configuration and save to domain GPO

# Import the Defendpoint cmdlet module
Import-Module 'C:\Program Files\Avecto\Privilege Guard Client\PowerShell\Avecto.Defendpoint.Cmdlets\Avecto.Defendpoint.Cmdlets.dll'
# get the local Defendpoint configuration and set this to the domain computer policy, ensuring the user is prompted to confirm the change
Get-DefendpointSettings -LocalFile | Set-DefendpointSettings -Domain -LDAP "LDAP://My.Domain/CN={GUID},CN=Policies,CN=System,DC=My,DC=domain" –Confirm

Matching criteria:

• File or Folder Name matches
• Command Line matches
• Drive matches
• File Hash (SHA-1) matches
• File Hash (SHA-256) matches
• Trusted Ownership matches
• Application Requires Elevation (UAC)
• Parent Process matches
• Source URL matches
• BeyondTrust Zone Identifier exists

EPM provides an additional level of granularity for management of remote PowerShell cmdlets to ensure you can execute these commands without local administrator privileges on the target computer.

Get-service -Name *time* | restart-Service –PassThru

EPM allows you to target specific command strings and assign privileges to the command without granting local admin rights to the user. Commands can also be blocked if they are not authorized or allowlisted. All remote PowerShell commands are fully audited for visibility.

To allow standard users to connect to a remote computer with Windows Remote Management, or WinRM (a privilege normally reserved for local administrator accounts), it is necessary to enable the General rule Enable Windows Remote Management Connections. This rule grants standard users, who match the Workstyle, the ability to connect using WinRM, and can be targeted to specific users, groups of users, or computers using Workstyle filters.

1. Select the Application Group you want to add the application to.
2. Right-click and select Insert Application > Remote PowerShell Command.
3. You can leave the Select reference script file blank to match on all applications of this files, type in a specific name or path manually, or click Browse Cmdlets. This lists the PowerShell cmdlets for the version of PowerShell that you installed. If the cmdlet you want to use is not listed because the target version of PowerShell is different, you can manually enter it.
4. Enter a description, if required. By default, this is the name of the application you are inserting.
5. You need to configure the matching criteria for the PowerShell command. You can configure:
   • Command Line matches: PowerShell removes double quotes from the Command Line before it is sent to the target. Command Line definitions that include double quotes are not matched by EPM for remote PowerShell commands.
6. Click OK. The application is added to the Application Group.

ℹ️

Note

For more information, see:

• [Application definitions](#) for more about command line matching.
• To manage remote PowerShell scripts instead of a single cmdlet, see [Insert Remote PowerShell scripts](#insert-scipts).

Messaging

EPM end user messaging includes limited support for remote PowerShell sessions; block messages can be assigned to Workstyle rules, which block remote PowerShell scripts and commands. If a block message is assigned to a Workstyle, which blocks a script or command, then the body message text of an assigned message will be displayed in the remote console session as an error.

Insert Remote PowerShell scripts

In a remote PowerShell session, a script (.PS1) can be executed from a remote computer against a target computer. Normally this requires local administrator privileges on the target computer, with little control over the scripts that are executed, or the actions that the script performs. For example:

Invoke-Command -ComputerName RemoteServer -FilePath c:\script.ps1 –Credential xxx

You can target specific PowerShell scripts remotely and assign privileges to the script without granting local administration rights to the user. Scripts can also be blocked if they are not authorized or allowlisted. All remote PowerShell scripts executed are fully audited for visibility.

ℹ️

Note

You must use the Invoke-Command cmdlet to run remote PowerShell scripts. EPM cannot target PowerShell scripts that are executed from a remote PowerShell session. Remote PowerShell scripts must be matched by either a SHA-1 File Hash or a Publisher (if the script has been digitally signed).

You can elevate individual PowerShell scripts and commands which are executed from a remote machine. This eliminates the need for users to be logged on with an account which has local admin rights on the target computer. Instead, elevated privileges are assigned to specific commands and scripts which are defined in Application Groups, and applied by a Workstyle.

PowerShell scripts and commands can be allowlisted to block the use of unauthorized scripts, commands, and cmdlets. Granular auditing of all remote PowerShell activity provides an accurate audit trail of remote activity.

PowerShell definitions for scripts and commands are treated as separate application types, which allows you to differentiate between predefined scripts authorized by IT, and session-based ad hoc commands.

To allow standard users to connect to a remote computer with Windows Remote Management, or WinRM (a privilege normally reserved for local administrator accounts), it is necessary to enable the General rule Enable Windows Remote Management Connections. This rule grants standard users who match the EPM Workstyle the ability to connect using WinRM, and can be targeted to specific users, groups of users, or computers using Workstyle filters.

Matching criteria:

• File Hash (SHA-1) matches
• File Hash (SHA-256) matches
• Publisher matches

You can leave the Select reference script file blank to match on all applications of this files, type in a specific name or path manually, or click Browse File.

ℹ️

Note

Remote PowerShell scripts that contain only a single line will be interpreted and matched as a Remote PowerShell Command, and will fail to match a PowerShell script definition. We therefore recommend PowerShell scripts contain at least two lines of commands to ensure they are correctly matched as a script. This cannot be achieved by adding a comment to the script.

Messaging

End user messaging includes limited support for remote PowerShell sessions; block messages can be assigned to Workstyle rules which block remote PowerShell scripts and commands. If a block message is assigned to a Workstyle which blocks a script or command, then the body message text of an assigned message will be displayed in the remote console session as an error.

EPM allows standard users to uninstall Microsoft Software Installers (MSIs) and executables (EXEs) that would normally require local admin rights.

When the Uninstaller application type is added to an Application Group and assigned to an Application Rule in the policy, the end user can uninstall applications using Programs and Features or, in Windows 10, Apps and Features.

The Uninstaller application type allows you to uninstall an EXE or MSI when it is associated with an Application Rule. As the process of uninstalling a file requires admin rights, you need to ensure when you target the Application Group in the Application Rules you set the access token to Add Full Admin.

ℹ️

Note

The Uninstaller type must be associated with an Application Rule. It does not apply to On-Demand Application Rules.

You cannot use the Uninstaller application type to uninstall the BeyondTrust or the BeyondTrustEPM Adapter using, irrespective of your user rights. The anti-tamper mechanism built into EPM prevents users from uninstalling EPM, and the uninstall will fail with an error message.

ℹ️

Note

If a user attempts to use EPM to modify the installation of EPM, for example, uninstall it, and they do not have an anti-tamper token applied, the default behavior for the user is used. For example, if Windows UAC is configured, the associated Windows prompt will be displayed.

If you want to allow users to uninstall either BeyondTrust's or the BeyondTrustEPM Adapter, you can do this by either:

• Logging in as a full administrator
• Elevating the Programs and Features control panel (or other controlling application) using a Custom Access Token that has anti-tamper disabled.

Upgrade considerations

Any pre 5.7 Uninstaller Application Groups which matched all uninstallations will be automatically upgraded when loaded by the Policy Editor to File or Folder Name matches *. These will be honored by Endpoint Privilege Management for Windows.

Pre 5.7 versions of Endpoint Privilege Management will no longer match the upgraded rules, the behavior will be that of the native operating system in these cases.

If you do not want the native operating system behavior for uninstallers; please ensure that your clients are upgraded to the latest version before you deploy any policy which contains upgraded Uninstaller rules.

1. Select the Application Group you want to add the uninstaller to.
2. Right-click and select Insert Application > Uninstaller.
3. Enter a description, if required. By default, this is the name of the application you are inserting.
4. Click Browse File to select an uninstaller file and populate the available matching criteria for the selected uninstaller file.
5. Configure the matching criteria for the executable. You can configure:
   • File or Folder Name matches
   • Upgrade Code matches
   • Product Name matches
   • Publisher matches

The Windows service type allows individual service operations to be allowlisted, so that standard users are able to start, stop, and configure services without the need to elevate tools such as the Service Control Manager.

Matching criteria:

• File or Folder Name matches
• Command Line matches
• Drive matches
• File Hash (SHA-1) matches
• File Hash (SHA-256) matches
• Product Name matches
• Publisher matches
• Product Description matches
• Product Version matches
• File Version matches
• Service Name matches
• Service Display Name matches
• Service Actions match

The Windows Store application type allows the installation and execution of Windows Store applications on Windows 8 and later to be allowlisted, so that users are prevented from installing or using unknown or unauthorized applications within the Windows Store.

ℹ️

Note

EPM can only be used to block Windows Store Applications. When you use EPM to block a Windows Store Application and assign an EPM block message to the Application Rule, the native Windows block message overrides the EPM block message, meaning it is not displayed. Event number 116 is still triggered if you have events set up in your Application Rule.

Matching criteria:

• File or Folder Name matches
• Command Line matches
• Drive matches
• File Hash (SHA-1) matches
• File Hash (SHA-256) matches
• Publisher matches
• Trusted Ownership matches
• Application Requires Elevation (UAC)
• Parent Process matches
• Source URL matches
• BeyondTrust Zone Identifier exists

The application requires authorization, so you need to approve that request. This applies to anything in macOS that has a padlock on the dialog box or where the system requires authorization to change something. The URIs are unique to the application. The Auth Request URIs are generic and any Auth Request URIs can be requested by any application.

When an application triggers an authorization request, the application will use a unique Auth Request URI. This URI will be different to the URI of the application itself. This matching criteria allows you to target any authorization request by matching the Auth Request URI, allowing you to target that specific Auth Request URI and apply your own controls.

This matching criteria can be used in combination with other criteria to target authorization requests from specific applications if more than one application uses the same Auth Request URI.

When this matching criteria is used in a definition, it will only match the authorization request of the application, and not the execution of the application. If you want to apply rules to both the application execution and application authorization request, then separate definitions must be created for each.

If you want to apply different rules to application execution and application authorization requests, then definitions must be added to different Application Groups and applied to different Application Rules.

Mac Packages are always configured to match exactly against the system.install.software request URI. You cannot set Auth Request URI or Perform Match Using options.

This matching criteria can be used with the following application types:

• Binaries
• Bundles
• Packages
• System Preferences

The Command Line Arguments matching criteria allows you to target a binary or sudo command based on the arguments passed to the command being executed on the command line. Command Line Arguments can be executed either through the Terminal, or through a script. With this matching criteria, you can apply a specific action (such as block, allow, or audit) to specific Command Line Arguments, rather than only applying actions to the use of the binary or sudo command.

The Command Line Arguments matching criteria will match specifically the arguments passed to the binary or sudo command. The following example shows a command for listing the contents of the /Applications directory:

MyMac:~ standarduser$ ls -la /Applications

• ls is the binary being executed, and is targeted by using the File or Folder Name matching criteria in a Binary definition.
• -la /Applications are the arguments being passed to ls, and is targeted by using the Command Line Arguments matching criteria in a Binary definition.

ℹ️

Note

Endpoint Privilege Management for Mac will only match the command line arguments, which will not include the beginning binary or sudo command being executed. If you want to match both the binary and sudo command, as well as the command line, then both the File or Folder Name and the Command Line Arguments matching criteria must be enabled and populated in the definition.

This matching criteria allows you to target all, or just parts of the command line being used. This is achieved by inserting wildcards into the Command Line Arguments string, defining which part of the command line you want to match, or by using a regular expression.

This matching criteria includes the following matching options:

• Command Line Arguments (for example, -la /Applications)
• Exact Match
• Starts With
• Ends With
• Contains
• Regular Expressions

This matching criteria can be used with the following application types:

• Binaries
• Scripts
• Sudo Commands

ℹ️

Note

You can match on any command line argument with the exception of those listed in Mac Sudo command arguments not supported.

This matching criteria allows you to target applications based on their name / path on disk. It is an effective way of automatically allowlisting applications located in trusted areas of the filesystem (for example, /Applications or /System), and for targeting specific applications based on their full path.

This matching criteria can be used in combination with other criteria in a definition, giving you more granularity over which applications you can target based on their properties. Although you may enter relative file names, we strongly recommended you enter the full path to a file.

Applications can be matched on the file or folder name. You can choose to match based on the following options:

• File or Folder Name (for example, /Applications/iTunes.app)
• Exact Match
• Starts With
• Ends With
• Contains
• Regular Expressions

You can match on the file path containing or starting with the /AppTranslocation/ folder, however we recommend you block all applications attempting to run from this location to ensure unsigned applications are not run. Instead, we recommend you run applications from the /Applications/ folder.

ℹ️

Note

Targeting bundles with an Exact Match path applies only to the main binary in the Contents/MacOS directory as specified in the bundle's plist.

This matching criteria can be used with the following application types:

• Binaries
• Bundles
• Packages
• System Preferences
• Sudo Commands
• Scripts

This definition ensures the contents of the application (which can normally be edited by any user) remain unchanged, as changing a single character in the script will cause the SHA-1 hash to change.

A file hash is a digital fingerprint of an application, generated from the contents of application binary or bundle. Changing the contents of an application results in an entirely different hash. Every application, and every version of the same application, has a unique hash. Endpoint Privilege Management for Mac uses hashes to compare the application being executed against a hash stored in the configuration.

File hash matching is the most specific criteria, as it can be used to ensure the application being run is the exact same application used when creating the definition, and that it has not been modified.

This matching criteria includes the following matching options:

• File Hash

This matching criteria can be used with the following application types:

• Binaries
• Bundles
• Packages
• System Preferences
• Sudo Commands
• Scripts

ℹ️

Note

Although file hash is the more reliable matching criteria for matching a specific application, you must ensure definitions are kept up to date. When updates are applied to the endpoint, new versions of applications may be added, and so their SHA-1 hashes will be different. Applications on different versions of macOS also have different SHA-1 hashes.

Changes to file hash auditing

Prior to version 21.6, the file hash audited depends on the context, for example, whether the application is a bundle or whether it’s code signed:

• Signed applications report the code directory hash (CDHash).
• Unsigned single files (binaries, scripts) and signed packages report a SHA-1.
• Unsigned bundles report a recursively generated SHA-1 of all their contents. In a worst case scenario, this can take several minutes to generate.

In version 21.6, what is audited is simplified to provide support for reputation services such as VirusTotal:

• Single files report a SHA-1.
• Bundles report the SHA-1 of their main binary, as specified by their Info.plist.

Changes to file hash matching criteria

Support for matching signed applications using their CDHash is continuing, and we also now support matching against the audited SHA-1.

Support for recursive SHA-1 matching for unsigned bundles will be removed once Apple Silicon is widely adopted by businesses, as unsigned code is not allowed to run on these devices. It can cause significant performance issues.

How to determine a file’s hash for matching criteria

If you have audit events available through reporting, then you can find the appropriate SHA-1 file hash there. This is not as secure as using a CDHash for bundles.

Signed application (bundle, binary, script):

codesign -dvvv <path to bundle or file> 2>&1 | egrep "^CDHash"

Unsigned files (binary, script) and both signed and unsigned packages:

shasum -a 1 <path to file>

Unsigned bundle:

shasum -a 1 <path to bundle’s main binary>

Set the SHA-256 file hash on an application. The SHA-256 hash is supported on all appropriate macOS applications. On the macOS operating system, you can select match. The does NOT match setting is not available on macOS. We recommend using SHA-256 rather than SHA-1.

How to determine a file’s hash for matching criteria

If you have audit events available through reporting, then you can find the appropriate SHA-256 file hash there. This is not as secure as using a CDHash for bundles.

Unsigned files (binary, script) and both signed and unsigned packages:

shasum -a 256 <path to file>

Unsigned bundle:

shasum -a 256 <path to bundle’s main binary>

If the application you entered has a File Version property, then it is automatically extracted. You can choose to Check Min Version, Check Max Version, and edit the version number fields. Alphanumeric characters are supported in the version of applications.

For application types with defined versions, you can optionally use the File Version matching criteria to target applications of a specific version or range of versions. This allows you to apply rules and actions to certain versions of an application, for example, blocking an application if it’s version is less than the version defined in the definition.

File Version matching can be applied either as a minimum required version, as a maximum required version, or you can use both to define a range of versions (between a minimum and a maximum).

This matching criteria includes the following matching options:

• File Min Version
• File Max Version

This matching criteria can be used with the following application types:

• Bundles
• System Preferences

This option can be used to check if an application’s parent process matches a specific Application Group. You must create an Application Group for this purpose or specify an existing Application Group in the Parent Process group. Setting match all parents in tree to True will traverse the complete parent and child hierarchy for the application, looking for any matching parent process. Setting this option to False only checks the application’s direct parent process.

When a new application executes, it is executed by another process, or parent process. In most cases on macOS, the parent process will be launchd. However, sometimes applications like binaries and bundles are executed by other applications. For example, binaries like curl can be executed from Bash, and will be created as a child of the Terminal process. However, curl can also be used by applications.

The Parent Process matching criteria allows you to the target applications based on their parent process, so you can apply different rules and actions depending on where the application is being executed from. In the example above, you can use Parent Process matching to allow curl to be used by an authorized application, but still block users from executing it directly in the Terminal.

Parent Processes are defined as an Application Group, so you can identify multiple parents without having to create multiple definitions. This also means the parent process can be defined as any type of application (binary, bundle, system preference, or package) using any of the relevant matching criteria for each application.

This matching criteria includes the following matching options:

• Parent Process Group (dropdown menu of all Application Groups existing in the configuration)

This definition can be used with the following application types:

• Binaries
• Bundles
• Sudo Commands
• Scripts

This option can be used to check for the existence of a valid publisher. If you have browsed for an application, then the certificate subject name will automatically be retrieved, if the application has been signed. By default, a substring match is attempted (Contains). Alternatively, you may choose to pattern match based on either a wildcard match (? and *) or a Regular Expression. The available operators are identical to the File or Folder Name definition.

Some applications are digitally signed with a certificate, giving a guarantee the application is genuine and from a specific vendor. The certificate also ensures the application has not been tampered with by an unauthorized source. The vendor who owns the certificate can be identified from certain properties of the certificate, which are referred to as Authorities. A certificate typically contains several Authorities linked together in a chain of trust.

To check if an application has been digitally signed and what the certificate Authorities are, use the following command example to check the certificate of the iTunes.app application bundle:

Codesign -dvvv /Applications/iTunes.app/

If the application has a certificate, there will be one or more Authorities listed in the output:

Authority=Software Signing
Authority=Apple Code Signing Certification Authority
Authority=Apple Root CA

In the output, the first Authority listed is the authority most specific to the application. In this example, you can see Apple uses the certificate Authority Software Signing to digitally sign iTunes.app.

With the Publisher matching criteria, you can target applications based on the publisher information contained in its certificate. This matching criteria can also be used in combination with other matching criteria, as a way of ensuring the application is a genuine application from the vendor.

ℹ️

Note

All apps downloaded from the Apple Store will have certificates with the same authority, as Apple resigns all applications before making them available in the Apple Store.

This matching criteria includes the following matching options:

• Publisher (For example, the Publisher for Apple applications is Software Signing)
• Exact Match
• Starts With
• Ends With
• Contains
• Regular Expressions

This definition can be used with the following application types:

• Binaries
• Bundles
• Packages
• System Preferences
• Sudo Commands

If an application was downloaded using a web browser, this option can be used to check where the application or installer was originally downloaded from. The application is tracked by Endpoint Privilege Management for Mac at the point it is downloaded, so if a user decided to run the application or installer at a later date, the source can still be verified. By default, a substring match is attempted (Contains). Alternatively, you can choose to pattern match based on either a wildcard match (? and *) or a Regular Expression. The available operators are the same as the File or Folder Name definition.

This definition can be used with the following application types:

• Bundles
• System Preferences

Every macOS application bundle has a defined Uniform Resource Identifier (URI), a property that uniquely identifies the application to the system. URI’s follow a specific structure, typically referencing the vendor and application. For example, the URI for Apple iTunes is com.apple.iTunes.

The URI matching criteria provides an effective way of targeting applications where the filename or file path may not always be known. It is also an effective way of targeting applications from a specific vendor.

This matching criteria can also be used in combination with other matching criteria, as a way of ensuring the application is a genuine application from the vendor.

This is the Unique Request Identifier for the application bundle. You can choose to match based on the following options:

• URI (for example, com.apple.iTunes)
• Exact Match
• Starts With
• Ends With
• Contains
• Regular Expressions

This definition can be used with the following application types:

• Bundles

Use to allow installation of bundles to the /Applications directory. This matching criteria can be used in combination with other criteria to allow or deny installation of the matched bundle.

You can choose from the following options to allow installation to the /Applications directory:

• Yes
• No

This definition can be used with the following application type:

• Bundles

This definition can be used to allow deletion of bundles from the /Applications directory. This matching criteria can be used in combination with other criteria to allow or deny deletion of the matched bundle.

You can choose from the following options to allow deletion from the /Applications directory:

• Yes
• No

This definition can be used with the following application type:

• Bundles