This week is focused on creating some awareness around the EpmTools PowerShell module. That PowerShell module is available to be used to diagnose and troubleshoot issues with Endpoint Privilege Management (EPM). Besides that, it can also be used to get the required attributes directly from a file or application. The best part is that the EpmTools PowerShell module is included by default with the installation of the Microsoft EPM agent. That provides IT administrators with a set of cmdlets to easily retrieve information about the actual local configuration of the Microsoft EPM agent, including the received policies, the applied client settings, and more. This blog post will provide an overview of the available cmdlets in the EpmTools PowerShell module, followed the steps and examples for actually using those cmdlets.
Note: Keep in mind that Endpoint Privilege Management is part of the Intune Suite and requires additional licensing.
Overview of the available cmdlets in the EpmTools PowerShell module
Before looking at actually using the EpmTools PowerShell module, it’s good to first be familiar with the available capabilities. The EpmTools PowerShell module currently contains six cmdlets for diagnosing and troubleshooting anything related to the Microsoft EPM agent. Those cmdlets are briefly summarized in the the table below.
| Command | Description |
|---|---|
| Get-Policies | This command can be used to retrieve a list of all policies that are received by the Microsoft EPM Agent for a specific policy type. |
| Get-DeclaredConfiguration | This command can be used to retrieve a list of WinDC documents that identify the policies that are targeted to the device. |
| Get-DeclaredConfigurationAnalysis | This command can be used to retrieve a list of WinDC documents of type MSFTPolicies and checks if the policy is already present in the Microsoft EPM Agent. |
| Get-ElevationRules | This command can be used to query the Microsoft EPM agent lookup functionality and retrieves the available rules based on the given lookup and target. |
| Get-ClientSetting | This command can be used to process all existing client settings policies to display the effective client settings used by the Microsoft EPM Agent. |
| Get-FileAttributes | This command can be used to retrieve the file attributes for a .exe file and extracts its Publisher and CA certificates to a set location. |
Note: The available cmdlets are also documented in the readme.md file in the EpmTools folder.
Getting started with the EpmTools PowerShell module
After being familiar with the available cmdlets, it’s time to actually start using those cmdlets. That all starts with importing the required module that is available within the EpmTools folder of the Microsoft EPM agent. For that simply use the following.
Import-Module 'C:\Program Files\Microsoft EPM Agent\EpmTools\EpmCmdlets.dll'After importing the EpmTools PowerShell module the available cmdlets can be used. That includes the cmdlet to retrieve a list of all policies that are received by the Microsoft EPM agent. Using that cmdlet requires to specify the policy type of either elevation rules (ElevationRules) or client settings (ClientSettings). The following is an example for the client settings.
Get-Policies -PolicyType ClientSettingsNext is to retrieve a list of all WinDC documents. For every policy there are two WinDC documents available. One for the actual policy (MSFTPolicy) and one for the inventory operation (MSFTInventory). For this action there is also a differentiation between elevation rules (ElevationRules) and client settings (ClientSettings). The following is an example for the client settings.
Get-DeclaredConfiguration -PolicyType ClientSettingsAs a follow up, it’s good to check if the policy is already available within the Microsoft EPM agent. For that it’s possible to retrieve the WinDC documents for the actual policy (MSFTPolicy), including a check if it’s already present. This also contains the differentiation between elevation rules (ElevationRules) and client settings (ClientSettings). The following is an example for the client settings.
Get-DeclaredConfigurationAnalysis -PolicyType ClientSettingsBesides that, it’s also possible to check if an elevation rule is available for a specific target. Either by looking at the name of the file (FileName), or by looking at the certificate payload (CertificatePayLoad). The following is an example for Adobe Acrobat.
Get-ElevationRules -Target acrobat.exe -Lookup FileNameLast, but definitely not least, is the option to get a quick overview of the effective client settings. For that, there are no parameters required and the following example can be used.
Get-ClientSettingBesides all the information that can be retrieved about the configuration of the Microsoft EPM agent, there is also a cmdlet available that can be used to retrieve information about a specific file. That can also include the certificate information. All focused on eventually creating a new elevation rule. The following is a basic example for Adobe Acrobat.
Get-FileAttributes -FilePath "C:\Program Files\Adobe\Acrobat DC\Acrobat\Acrobat.exe"Note: Keep in mind that for each cmdlet the standard -verbose parameter can be used, to retrieve verbose insights about the performed action.
More information
For more information about Endpoint Privilege Management and the EpmTools PowerShell module, refer to the following docs.