Get-Acl

 

Additional Resources for Get-Acl

Retrieving the Security Descriptor for an Object http://www.microsoft.com/technet/scriptcenter/topics/msh/cmdlets/get-acl.mspx

 

SYNOPSIS

Gets the security descriptor for a resource, such as a file or registry key.

 

SYNTAX

Get-Acl [[-path] <string[]>] [-filter <string>] [-include <string[]>] [-exclude <string[]>] [-audit] [<CommonParameters>]

 

DETAILED DESCRIPTION

The Get-Acl cmdlet gets objects that represent the security descriptor of a file or resource. The security descriptor contains the access control lists (ACLs) of the resource. The ACL specifies the permissions that users and user groups that have to access the resource.

 

PARAMETERS

 

-path <string[]>

Specifies the path to a resource. Get-Acl gets the security descriptor of the resource indicated by the path. Wildcards are permitted. If you omit the Path parameter, Get-Acl gets the security descriptor of the current directory.

 

The parameter name ("-Path") is optional.

 

Required?	false
Position?	1
Default value
Accept pipeline input?	true (ByValue, ByPropertyName)
Accept wildcard characters?	true

 

-filter <string>

Specifies a filter in the provider's format or language. The value of this parameter qualifies the Path parameter. The syntax of the filter, including the use of wildcards, depends on the provider. Filters are more efficient than other parameters, because the provider applies them when retrieving the objects, rather than having Windows PowerShell filter the objects after they are retrieved.

 

Required?	false
Position?	named
Default value
Accept pipeline input?	false
Accept wildcard characters?	false

 

-include <string[]>

Retrieves only the specified items. The value of this parameter qualifies the Path parameter. Enter a path element or pattern, such as "*.txt". Wildcards are permitted.

 

Required?	false
Position?	named
Default value
Accept pipeline input?	false
Accept wildcard characters?	true

 

-exclude <string[]>

Omits the specified items. The value of this parameter qualifies the Path parameter. Enter a path element or pattern, such as "*.txt". Wildcards are permitted.

 

Required?	false
Position?	named
Default value
Accept pipeline input?	false
Accept wildcard characters?	true

 

-audit <SwitchParameter>

Gets the audit data for the security descriptor from the system access control list (SACL).

 

Required?	false
Position?	named
Default value	False
Accept pipeline input?	false
Accept wildcard characters?	false

 

<CommonParameters>

This cmdlet supports the common parameters: -Verbose, -Debug, -ErrorAction, -ErrorVariable, and -OutVariable. For more information, type, "get-help about_commonparameters".

 

INPUT TYPE

String

 

RETURN TYPE

System.Security.AccessControl.DirectorySecurity object

 

NOTES

 

For more information, type "Get-Help Get-Acl -detailed". For technical information, type "Get-Help Get-Acl -full".

 

When specifying multiple values for a parameter, use commas to separate the values. For example, "<parameter-name> <value1>, <value2>".

 

By default, Get-Acl displays the Windows PowerShell path to the resource (<provider>::<resource-path>), the owner of the resource, and "Access", a list (array) of the access control entries in the discretionary access control list (DACL) for the resource. The DACL list is controlled by the resource owner.

 

When you format the result as a list, ("get-acl | format-list"), in addition to the path, owner, and access list, Windows PowerShell displays the following fields:

 

·          Group: The security group of the owner.

·          Audit:  A list (array) of entries in the system access control list (SACL). The SACL specifies the types of access attempts for which Windows generates audit records.

·          Sddl: The security descriptor of the resource displayed in a single text string in Security Descriptor Definition Language format. Windows PowerShell uses the GetSddlForm method of security descriptors to retrieve this data.

 

Because Get-Acl is supported by the file system and registry providers, you can use Get-Acl to view the ACL of file system objects, like files and directories, and registry objects, like registry keys and entries.

 

EXAMPLE 1

 

 

This command gets the security descriptor of the C:Windows directory.

 

EXAMPLE 2

 

 

This command gets the Path and SDDL strings for all of the .log files in the C:\windows director whose names begin with "k."

 

The command uses Get-Acl to get objects representing the security descriptors of each log file. It passes the results to the Select-Objectcmdlet, which selects only the values of the PSPath and SDDL fields. Then, it passes the results to the Format-Listcmdlet to display the results as a list. Lists are often used in Windows Powershell, because long values appear truncated in tables.

 

The SDDL values are valuable to system administrators, because they are simple text strings that contain all of the information in the security descriptor. As such, they are easy to pass and store, and can be parsed when needed.

 

EXAMPLE 3

 

 

This command gets the security descriptors of the .log files in the C:\Windows directory whose names begin with "k." It uses the Audit parameter to retrieve the audit records from the SACL in the security descriptor. Then it uses the For-EachObjectparameter to count the number of audit records associated with each file. The result is a list of numbers representing the number of audit records for each log file.

 

EXAMPLE 4

 

 

This command uses Get-Acl to get the security descriptor of the Control subkey (HKLM\SYSTEM\CurrentControlSet\Control) of the registry.

 

The Path parameter specifies the Control subkey. The pipeline operator (|) passes the security descriptor that Get-Acl retrieves to the Format-Listcommand, which formats the properties of the security descriptor as a list so that they are easy to read.

 

RELATED LINKS

Set-Acl

about_namespace