Test-AppLockerPolicy
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.
See Also
Reference
Get-AppLockerPolicy
Set-AppLockerPolicy
New-AppLockerPolicy
Get-AppLockerFileInformation