6.8 KiB
| external help file | Module Name | online version | schema |
|---|---|---|---|
| NTFSSecurity.dll-Help.xml | NTFSSecurity | https://github.com/raandree/NTFSSecurity/blob/master/Docs/Cmdlets/Get-NTFSSecurityDescriptor.md | 2.0.0 |
Get-NTFSSecurityDescriptor
SYNOPSIS
Gets the security descriptor of a file or folder.
SYNTAX
Get-NTFSSecurityDescriptor [[-Path] <String[]>] [<CommonParameters>]
DESCRIPTION
The Get-NTFSSecurityDescriptor cmdlet reads the security descriptor of a file or folder into memory and returns it as a Security2.FileSystemSecurity2 object. A security descriptor holds the owner of an item, its primary group, the discretionary access control list (DACL) that grants or denies access, and the system access control list (SACL) that controls auditing.
The returned object is the starting point of the security descriptor workflow. Many cmdlets of the module accept it through a -SecurityDescriptor parameter and then change the copy in memory instead of the file system, among them Add-NTFSAccess, Remove-NTFSAccess, Clear-NTFSAccess, Add-NTFSAudit, Remove-NTFSAudit, Clear-NTFSAudit, Set-NTFSInheritance, Enable-NTFSAccessInheritance, Disable-NTFSAccessInheritance, and Set-NTFSOwner. Nothing reaches the disk until you pass the descriptor to Set-NTFSSecurityDescriptor, which makes it possible to collect several changes and apply them in a single write; that cmdlet writes only the sections that changed. Discard the variable to discard the changes.
The cmdlet reads all sections of the descriptor. When that fails, for example because the session may not read the SACL, it falls back to the access, owner, and group sections, and then to the access section alone. When the cmdlet reads the SACL, it reads the DACL in a separate call, so that the inherited access entries keep their inherited flag. Before 5.0.0, it read the DACL together with the SACL, and Windows could return the inherited entries without that flag; a descriptor written back then stored them as explicit entries. -Path accepts pipeline input by value and by property name through its FullName alias, so the output of Get-ChildItem2, Get-Item2, and Get-ChildItem binds to it. Relative paths are resolved against the current location, and when you omit -Path entirely, the cmdlet returns the descriptor of the current location.
Every path is processed on its own. When a path does not exist, the cmdlet writes a non-terminating error and continues with the next one. When reading the descriptor fails because access is denied, the cmdlet takes ownership of the item with the account of the current session, reads the descriptor, and restores the previous owner; if that fails as well, it writes a non-terminating error.
EXAMPLES
Example 1: Get the security descriptor of a folder
PS C:\> Get-NTFSSecurityDescriptor -Path C:\Data
This command reads the security descriptor of C:\Data and returns it as a FileSystemSecurity2 object.
Example 2: Collect several changes and apply them in one write
PS C:\> $sd = Get-NTFSSecurityDescriptor -Path C:\Data
PS C:\> Add-NTFSAccess -SecurityDescriptor $sd -Account 'CONTOSO\JohnDoe' -AccessRights Modify -AppliesTo ThisFolderSubfoldersAndFiles
PS C:\> Remove-NTFSAccess -SecurityDescriptor $sd -Account 'BUILTIN\Users' -AccessRights ReadAndExecute -AppliesTo ThisFolderSubfoldersAndFiles
PS C:\> Set-NTFSSecurityDescriptor -SecurityDescriptor $sd
The first three commands read the descriptor of C:\Data and change its access control list in memory, which leaves the folder untouched. The last command writes both changes to the folder at once.
Example 3: Inspect the access control list of the descriptor before writing it
PS C:\> $sd = Get-NTFSSecurityDescriptor -Path C:\Data
PS C:\> Add-NTFSAccess -SecurityDescriptor $sd -Account 'CONTOSO\JohnDoe' -AccessRights FullControl -AppliesTo ThisFolderOnly
PS C:\> Get-NTFSAccess -SecurityDescriptor $sd
The third command lists the access control entries of the descriptor in memory, which already include the permissions that were just added. Compare the result with Get-NTFSAccess -Path C:\Data to see that the folder itself has not changed yet.
Example 4: Get the security descriptor of the current location
PS C:\> Set-Location -Path C:\Data
PS C:\Data> Get-NTFSSecurityDescriptor
Without -Path, the cmdlet returns the security descriptor of the current location.
PARAMETERS
-Path
Specifies the path of one or more files or folders whose security descriptor you want to read. Relative paths are resolved against the current location. When you omit this parameter, the cmdlet uses the current location.
Type: String[]
Parameter Sets: (All)
Aliases: FullName
Required: False
Position: 1
Default value: None
Accept pipeline input: True (ByPropertyName, ByValue)
Accept wildcard characters: False
CommonParameters
This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters.
INPUTS
System.String[]
You can pipe one or more paths to this cmdlet. Objects that expose a Path or FullName property, such as the output of Get-ChildItem2 and Get-Item2, bind to -Path as well.
OUTPUTS
Security2.FileSystemSecurity2
The cmdlet returns one object per item. It wraps the item in Item and the underlying System.Security.AccessControl.FileSecurity or DirectorySecurity object in SecurityDescriptor, and it exposes the path in FullName, the item name in Name, and whether the item is a file in IsFile.
NOTES
When the module setting EnablePrivileges is $true (the default in the PrivateData section of NTFSSecurity.psd1), this cmdlet tries to enable the Backup, Restore, Take Ownership, and Security privileges while it runs and disables the privileges it enabled when it finishes. These privileges are only available in an elevated session of an account that holds them, such as a member of the local Administrators group. If a privilege cannot be enabled, the cmdlet continues without it and writes a debug message.
Add-NTFSAccess, Remove-NTFSAccess, Add-NTFSAudit, and Remove-NTFSAudit offer two parameter sets for a security descriptor, one with -AppliesTo and one with -InheritanceFlags and -PropagationFlags. Specify at least one of those parameters when you pass a descriptor to them; otherwise PowerShell cannot decide which parameter set to use and reports an ambiguous parameter set.