EPM for Windows PowerShell API

What is the Windows PowerShell API?

Use the PowerShell API to configure Endpoint Privilege Management for Windows. The API can be used to integrate with external systems, and also provides an alternative to using the Endpoint Privilege Management Policy Editor.

How is it useful?

All operations available using the Endpoint Privilege Management Policy Editor are also available using the PowerShell API. Use the Get-Help <cmdlet name> command to access syntax help.

The types properties and values are documented in the PowerShell API.chm help file located in the PowerShell directory: C:/Program Files/Avecto/Privilege Guard Client/PowerShell.

⚠️

Important

To maintain backwards compatibility, the PowerShell cmdlets are not renamed along with the product. Therefore, many of the objects and cmdlets reference the former product name Defendpoint.

The examples in this guide show you how to retrieve, update, and save an existing configuration file.

The typical workflow for using the PowerShell API is:

• Get-DefendpointSettings.
• Find the relevant section of the config you want to work with.
• Update, add, or delete the information.
• Set-DefendpointSettings.

Prerequisites

Before running any cmdlets, run the following two commands to initialize the cmdlets:

Import-Module 'C:/Program Files/Avecto/Privilege Guard Client/PowerShell/Avecto.Defendpoint.Cmdlets/Avecto.Defendpoint.Cmdlets.dll'

Import-Module 'C:/Program Files/Avecto/Privilege Guard Client/PowerShell/Avecto.Defendpoint.Cmdlets/Avecto.Defendpoint.Settings.dll'

Get application definitions from files

Command: Get-DefendpointFileInformation

Description

Use Get-DefendpointFileInformation to return properties Endpoint Privilege Management for Windows can use as matching criteria for files and applications such as Publisher, ProductName, and FileName.

This cmdlet supports Common Parameters.

Syntax

Get-DefendpointFileInformation [-Path '/path/to/file'] [-Directory '/path/to/directory' [-Recurse]] [-FileType 'ApplicationType.$FileType'] [-COM]

Parameters

File types

Return values

The command Get-DefendpointFileInformation returns a list of application definitions.

Example

Get all executables in a specified path and reference the FileName of the first:

$Executables = Get-DefendpointFileInformation –Path "C:\Program Files\Internet Explorer\*.exe"
$Executables.Item(0).FileName

Examples

Get all application files in a specified directory and return unique publishers:

$Files = Get-DefendpointFileInformation –Directory "C:\Program Files\Internet Explorer\"
$Files.Publisher

Get all registered COM objects:

Get-DefendpointFileInformation –COM

Recursively search for all batch files in a directory:

Get-DefendpointFileInformation -Directory "C:/Users/admin/Desktop" -FileType "BatchFile" -Recurse

Retrieve settings

Command: Get-DefendpointSettings

Description

Use the Get-DefendpointSettings cmdlet to retrieve the Endpoint Privilege Management for Windows settings from the Local Group Policy, a specified Group Policy Object (GPO), or from a specified XML file.

The output is a DefendpointSettings object or an XML- formatted string, depending on the parameters supplied.

After the settings are in a PowerShell session or script, you can update relevant sections, and then write them back using Set-DefendpointSettings.

This cmdlet supports Common Parameters.

Syntax

Get-DefendpointSettings [-LocalPolicy] [-LocalFile -FileLocation 'path/to/file'] [-UserPolicy] [-Domain -LDAP 'path/to/LDAP'] [-XML]

Parameters

Return values

By default, Get-DefendpointSettings returns a DefendpointSettings object. Use the -XML parameter to return the Endpoint Privilege Management policy as an XML formatted string. The cmdlet returns any errors.

Example

Get the local Endpoint Privilege Management Settings as a DefendpontSettings object

$settings = Get-DefendpointSettings -LocalPolicy

This example outputs:

Version:5.2.102.0
ID: 1e71ef8e-4ffc-4769-9a5b-11ea102b0f8e
ConfigRevision:	510
ApplicationGroups:{cmd}
ContentGroups:{}
URLGroups:{}
Tokens:{}
GlobalOptionsSets:{}
Files: Avecto.Defendpoint.Settings.FileList
Messages:{Block Message, Allow Message (Elevate)}
Policies:{New Workstyle}
Licenses:{Avecto.Defendpoint.Settings.License}
RegistryValues:{}

Example

Save the local Endpoint Privilege Management Settings into an XML file

Get-DefendpointSettings -LocalPolicy -XML > C:/Users/admin/Desktop/DefendpointSettings.xml

The above example does not output anything to the terminal. A file called DefendpointSettings.xml is created at C:/Users/admin/Desktop.

Example

Assign Local Endpoint Privilege Management Settings to a Variable to Work with PowerShell

$settings = Get-DefendpointSettings -LocalPolicy

Example

Get the Endpoint Privilege Management Settings of the Group Policy Object Specified by an LDAP Path

Get-DefendpointSettings -Domain -LDAP "LDAP://DC13.Acme.com/CN=
{31B2F340-016D-11D2-945F-00C04FB984F9},CN=Policies,CN=System,DC=Acme,DC=com"

This example outputs:

Version:5.2.102.0
ID:	1e71ef8e-4ffc-4769-9a5b-11ea102b0f8e
ConfigRevision:	510
ApplicationGroups:	{cmd}
ContentGroups:	{}
URLGroups:	{}
Tokens:	{}
GlobalOptionsSets:	{}
Files:	Avecto.Defendpoint.Settings.FileList
Messages:	{Block Message, Allow Message (Elevate)}
Policies:	{New Workstyle}
Licenses:	{Avecto.Defendpoint.Settings.License}
RegistryValue:	{}

Update settings

Command: Set-DefendpointSettings

Description

The Set-DefendpointSettings cmdlet takes an XML file or Endpoint Privilege Management for Windows settings object as input and saves it to either a local file, a Local Group policy, or a Group Policy Object (GPO).

By default, Set-DefendpointSettings overwrites the existing Endpoint Privilege Management for Windows settings at the target location unless the -Merge parameter is used.

Syntax

Set-DefendpointSettings [-SettingsObject 'path/to/object'] [-LocalPolicy -XML 'path/to/file'] [-UserPolicy] [-Merge 'path/to/file']

Parameters

Return values

Set-DefendpointSettings returns errors if there are any. If not, the function does not return anything.

Example

Add License to Endpoint Privilege Management Settings Configuration

$PGLicence = "YOUR_LICENCE_HERE"
$PGConfig = Get-DefendpointSettings -LocalFile
$PGLicence = New-Object Avecto.Defendpoint.Settings.License
$PGLicence.Code = "$PGLicense"
$PGConfig.Licenses.Add($PGLicence)
Set-DefendpointSettings -SettingsObject $PGConfig -LocalFile

Although this example is not part of the API, it is useful to know in this context.

Example

Set the local Endpoint Privilege Management for Windows Settings from an XML File

This example does not output anything to the terminal.

Set-DefendpointSettings –LocalPolicy -XML C:/Users/admin/Desktop/PrivilegeGuardConfig.xml

Example

Merge an Endpoint Privilege Management Config with the Domain Machine Policy Endpoint Privilege Management Config.

This example does not output anything to the terminal.

# Set the licence and LDAP.
$Ldap = "LDAP://DC13.Acme.com/CN={31B2F340-016D-11D2-945F-
>> 00C04FB984F9},CN=Policies,CN=System,DC=Acme,DC=com"

# Get the local PG Config file.
$PGConfig = Get-DefendpointSettings -Domain -LDAP $Ldap

# Create a new license object.
$PGLicence = New-Object Avecto.Defendpoint.Settings.License
$PGLicence.Code = "$PGLicense"

# Add the license to the defendpoint config.
$PGConfig.Licenses.Add($PGLicence)

# Merge the Defendpoint config with the existing Domain Machine policy Defendpoint config.
Set-DefendpointSettings -SettingsObject $PGConfig -Domain -Ldap $Ldap

Use cases

The use cases assume that your config is a local file in the default location and that you already loaded the modules required.

When adapting the examples to your use case, reference the PowerShell API.chm help file located in the PowerShell directory: C:/Program Files/Avecto/Privilege Guard Client/PowerShell.

Application groups

Example

Add a new application definition (FileName contains) to an existing Application Group with a new application definition

# Get settings
$PGConfig = Get-DefendpointSettings -LocalFile

# Find target Application Group
$TargetAppGroup = $PGConfig.ApplicationGroups | Where-Object {$_.name -eq 'YourApplicationGroupName'}    

# Create an empty application definition
$PGApp = new-object Avecto.Defendpoint.Settings.Application $PGConfig

# Populate the things you want to
$PGApp.Description = "Microsoft Calculator"
$PGApp.Type = [Avecto.Defendpoint.Settings.ApplicationType]::Executable
$PGApp.CheckFileName = 1 # 0 = Disabled 1 = Enabled
$PGApp.FileName = "Calc.exe"
$PGApp.FileNameStringMatchType = 2 # 2 = Contains (see StringMatchType in PowerShell API.chm)
$PGApp.OpenDlgDropRights = 1    

# Add the application definition to the target Application Group
$TargetAppGroup.Applications.Add($PGApp)

# Save the settings
Set-DefendpointSettings -SettingsObject $PGConfig -LocalFile

Example

Add a new application definition to an existing Application Group with Get-DefendpointFileInformation

# Get settings
$PGConfig = Get-DefendpointSettings -LocalFile

# Find target Application Group
$TargetAppGroup = $PGConfig.ApplicationGroups | Where-Object {$_.name -eq 'YourApplicationGroupName'}

# Get the details of the file(s) you want to match on
$PGApp1 = Get-DefendpointFileInformation -Path 'C:\Windows\System32\cmd.exe'    

# Add the list of application definitions to the target app group
$TargetAppGroup.Applications.AddRange($PGApp1)

# Save the settings
Set-DefendpointSettings -SettingsObject $PGConfig -LocalFile

Account filters

Example

Add an account to an existing account filter

# Get the local settings file
$PGConfig = Get-DefendpointSettings -LocalFile

# Find the Workstyle you want to work with (Workstyles are known as policies here)
$TargetWorkstyle = $PGConfig.Policies | Where-Object {$_.name -eq 'YourWorkstyleName'}

# Get first account filter in list
$TargetAccountFilterCollection = $TargetWorkstyle.Filters.AccountsFilter[0]

# Create an account object and populate it’s values
$Account = New-Object Avecto.Defendpoint.Settings.Account
$Account.Name = Get-WmiObject win32_useraccount | Where-Object {$_.Name -eq 'AccountName' -and
$_.Domain -eq 'DomainName'} | % {return $_.Caption}
$Account.SID = Get-WmiObject win32_useraccount | Where-Object {$_.Name -eq 'AccountName' -and
$_.Domain -eq ‘DomainName’} | % {return $_.SID}


# Add new account to the filter collection
$TargetAccountFilterCollection.Accounts.WindowsAccounts.Add($Account)
# Save Settings
Set-DefendpointSettings -SettingsObject $PGConfig -LocalFile