Test-AppLockerPolicy

Article
09/08/2009

Test-AppLockerPolicy

Tests whether the input files are allowed to run for a given user based on the specified AppLocker policy.

Syntax

Test-AppLockerPolicy [-PolicyObject] <AppLockerPolicy> -Path <String[]> [-User <String>] [-Filter <PolicyDecision[]>] [<CommonParameters>]


Test-AppLockerPolicy [-XMLPolicy] <String> -Path <String[]> [-User <String>] [-Filter <PolicyDecision[]>] [<CommonParameters>]

Detailed Description

The Test-AppLockerPolicy cmdlet uses the specified AppLocker policy to test whether a specified list of files are allowed to run on the local computer for a specific user.

Parameters

-PolicyObject <AppLockerObject>

Specifies the policy object that contains the AppLocker policy. It can be obtained from Get-AppLockerPolicy or New-AppLockerPolicy.

Attributes

Name	Value
Required?	true
Accept wildcard characters?	false
Accept Pipeline Input?	true (ByValue)
Position?	1

-XMLPolicy <String>

The XML file path that contains AppLocker policy.

Attributes

Name	Value
Required?	true
Accept wildcard characters?	false
Accept Pipeline Input?	false
Position?	1

-Path <String[]>

Specifies the list of file paths to test. Supports regular expressions.

Attributes

Name	Value
Required?	true
Accept wildcard characters?	false
Accept Pipeline Input?	true (ByValue)
Position?	named

-User <String>

Defines the user or group to be used for testing the rules in the specified AppLocker policy. You must provide the value in one of the following formats:
DNS user name (domain\username)
User Principal Name (username@domain.com)
SAM user name (username)
Security identifier (S-1-5-21-3165297888-301567370-576410423-1103)

Attributes

Name	Value
Required?	false
Accept wildcard characters?	false
Accept Pipeline Input?	false
Position?	named

-Filter <PolicyDecision>

Filters the output by the policy decision for each input file. The policy decision options include: Allowed, Denied, DeniedByDefault, and AllowedByDefault. By default, all policy decisions are displayed.

Attributes

Name	Value
Required?	false
Accept wildcard characters?	false
Accept Pipeline Input?	false
Position?	named

-CommonParameter

This cmdlet supports the common parameters: -Verbose, -Debug, -ErrorAction, -ErrorVariable, -OutBuffer, and -OutVariable. For more information, see About Common Parameter

Input and Return Types

The input type is the type of the objects that you can pipe to the cmdlet. The return type is the type of the objects that the cmdlet emits.

Input Type	.
Return Type	AppLockerPolicyDecision.

Notes

To test AppLocker rules for a nested group, you should specify a representative member of the nested group for the User parameter. For example, a rule that allows the Everyone group to run calc.exe may not appear to apply correctly when you specify the nested Finance group for the User parameter. Instead, you should specify a representative member of the Finance group for the User parameter.

Examples

EXAMPLE 1

C:\PS>Test-AppLockerPolicy -XMLPolicy C:\Policy.xml -Path C:\Windows\System32\calc.exe,  C:\Windows\System32\notepad.exe -User Everyone

Uses the AppLocker policy in C:\Policy.xml to test whether calc.exe and notepad.exe are allowed to run for users who are members of the Everyone group. If you do not specify a group, the Everyone group is used by default.

EXAMPLE 2

C:\PS>Get-ChildItem C:\Windows\System32 -filter *.exe -recurse | Convert-Path | Test-AppLockerPolicy c:\Policy.xml -User S-1-5-21-3165297888-301567370-576410423-1103 -Filter DeniedByDefault

Gets the list of all executable files under C:\Windows\System32, obtains the full path for each file using the Convert-Path cmdlet, and then uses the AppLocker policy specified in C:\Policy.xml to test whether the user with the specified SID is denied access to run the files by default. A policy decision of DeniedByDefault occurs when there are rules in the rule collection, but there are no explicit allow or deny rule that apply to the specified file and user.

EXAMPLE 3

C:\PS>Get-AppLockerPolicy -Local | Test-AppLockerPolicy -Path C:\Windows\System32\*.exe -User domain\saradavis -Filter Denied | Format-List -Property Path > C:\DeniedFiles.txt

Gets the local AppLocker policy, uses the policy to determine which executables in C:\Windows\System32 Sara Davis is explicitly denied access to run, and then redirects the list to a text file.

Test-AppLockerPolicy