--- external help file: NTFSSecurity.dll-Help.xml Module Name: NTFSSecurity online version: https://github.com/raandree/NTFSSecurity/blob/master/Docs/Cmdlets/Get-NTFSEffectiveAccess.md schema: 2.0.0 --- # Get-NTFSEffectiveAccess ## SYNOPSIS Gets the rights an account effectively has on a file or folder. ## SYNTAX ### Path (Default) ``` Get-NTFSEffectiveAccess [[-Path] ] [[-Account] ] [-ServerName ] [-ExcludeNoneAccessEntries] [] ``` ### SecurityDescriptor ``` Get-NTFSEffectiveAccess [-SecurityDescriptor] [[-Account] ] [-ServerName ] [-ExcludeNoneAccessEntries] [] ``` ## DESCRIPTION Calculates the rights an account really has on a file or a folder and writes the result as a single `Security2.FileSystemAccessRule2` object per item. The cmdlet evaluates the complete discretionary access control list (DACL) of the item against the group memberships of the account with the Windows Authorization API, so allow entries, deny entries, and inherited entries are combined the same way the Windows access check combines them. This is the equivalent of the "Effective Access" tab of the advanced security dialog. The calculation covers the NTFS permissions of the item only. Share permissions are stored in a separate security descriptor and are not part of the result, so access over a network share can be more restrictive than this cmdlet reports. When `-Account` is omitted, the account that runs the session is used. `-ServerName` selects the computer whose authorization manager resolves the group memberships of the account and defaults to `localhost`; when the remote authorization manager of the named computer cannot be reached, the cmdlet falls back to the local one and warns that the result is based on the group memberships known on this computer and may be inaccurate. The warning names the computer that couldn't be reached. For a name of this computer, such as `localhost`, `.`, or its computer name, the local authorization manager gives the result of the named computer, so the cmdlet doesn't warn. The remote authorization manager of a computer answers only the administrators of that computer and the members of its local group Access Control Assistance Operators. For a name of this computer, the cmdlet uses the local authorization manager when the remote one refuses the user who runs the cmdlet, so a user who isn't an administrator gets the result on a computer in a domain, too; for the name of another computer, the cmdlet writes an error and doesn't fall back. Reading effective access relies on the Security privilege, and the cmdlet warns when the account does not hold it or the privilege is disabled. When `-Path` is omitted, the cmdlet calculates the effective access to the current location. In the `SecurityDescriptor` parameter set, it calculates the effective access from a `Security2.FileSystemSecurity2` object that `Get-NTFSSecurityDescriptor` returned, without reading the item again. ## EXAMPLES ### Example 1: Get the effective access of the current user ```PowerShell PS C:\> Get-NTFSEffectiveAccess -Path C:\Data ``` This command returns the rights the account that runs the session has on `C:\Data`, combining all allow and deny entries of the folder. ### Example 2: Get the effective access of another account ```PowerShell PS C:\> Get-NTFSEffectiveAccess -Path C:\Data -Account 'CONTOSO\JohnDoe' ``` This command returns the rights of a domain user on `C:\Data`. A group such as `CONTOSO\Domain Users` or `BUILTIN\Users` can be used in the same way. ### Example 3: Compare the effective access of a folder tree ```PowerShell PS C:\> Get-ChildItem2 -Path C:\Data -Recurse -Directory | Get-NTFSEffectiveAccess -Account 'CONTOSO\JohnDoe' ``` This command shows for every subfolder of `C:\Data` what an account is allowed to do there, which makes the folders visible where inheritance is broken or a deny entry applies. ### Example 4: Calculate effective access with the group memberships of a file server ```PowerShell PS C:\> Get-NTFSEffectiveAccess -Path \\FileServer\Data -Account 'CONTOSO\JohnDoe' -ServerName FileServer ``` This command asks the authorization manager of the file server to resolve the group memberships of the account, which gives a more accurate result than the local fallback. ## PARAMETERS ### -Account Specifies the account the effective access is calculated for. An account can be given as a name such as `CONTOSO\JohnDoe`, `BUILTIN\Users`, or `NT AUTHORITY\SYSTEM`, or as a SID string such as `S-1-5-32-544`. The default is the account that runs the current session. ```yaml Type: IdentityReference2 Parameter Sets: (All) Aliases: NTAccount, IdentityReference Required: False Position: 2 Default value: Current user Accept pipeline input: True (ByPropertyName) Accept wildcard characters: False ``` ### -ExcludeNoneAccessEntries Indicates that items on which the account has no rights at all are left out of the result. Because every calculated result includes the `Synchronize` right, an item counts as without rights when `Synchronize` is the only right. ```yaml Type: SwitchParameter Parameter Sets: (All) Aliases: Required: False Position: Named Default value: None Accept pipeline input: False Accept wildcard characters: False ``` ### -Path Specifies the path of one or more files or folders the effective access is calculated for. Relative paths are resolved against the current location. The parameter accepts pipeline input by value and by property name through its alias `FullName`. When you omit the parameter, the cmdlet uses the current location. ```yaml Type: String[] Parameter Sets: Path Aliases: FullName Required: False Position: 1 Default value: None Accept pipeline input: True (ByPropertyName, ByValue) Accept wildcard characters: False ``` ### -SecurityDescriptor Specifies one or more security descriptors that `Get-NTFSSecurityDescriptor` returned. The cmdlet calculates the effective access from the in-memory object instead of reading the item again. A security descriptor contains information about the owner of the object, and the primary group of an object. The security descriptor also contains two access control lists (ACL). The first list is called the discretionary access control lists (DACL), and describes who should have access to an object and what type of access to grant. The second list is called the system access control lists (SACL) and defines what type of auditing to record for an object. ```yaml Type: FileSystemSecurity2[] Parameter Sets: SecurityDescriptor Aliases: Required: True Position: 1 Default value: None Accept pipeline input: True (ByPropertyName, ByValue) Accept wildcard characters: False ``` ### -ServerName Specifies the computer whose authorization manager resolves the group memberships of the account. The default is `localhost`. Name the computer that stores the item when you query a network path, because the group memberships known there determine the result; if that computer cannot be reached, the cmdlet falls back to the local authorization manager and warns that the result may be inaccurate. The remote authorization manager of a computer answers only its administrators and the members of its local group Access Control Assistance Operators. For the name of another computer, any other user gets a non-terminating `GetEffectiveAccessError` with the message "Access is denied" and no result for the item; for a name of this computer, the cmdlet uses the local authorization manager instead. ```yaml Type: String Parameter Sets: (All) Aliases: Required: False Position: Named Default value: localhost Accept pipeline input: False 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](http://go.microsoft.com/fwlink/?LinkID=113216). ## INPUTS ### System.String[] One or more paths of files or folders, piped by value or by the property `FullName`. ### Security2.FileSystemSecurity2[] One or more security descriptors that `Get-NTFSSecurityDescriptor` returned. The cmdlet calculates the effective access from the descriptor in memory instead of reading the item again. ### Security2.IdentityReference2 The account the effective access is calculated for, piped by the property `Account`, `NTAccount`, or `IdentityReference`. ## OUTPUTS ### Security2.FileSystemAccessRule2 One object per item, with the calculated rights in `AccessRights` and the account in `Account`. The object describes a result, not an entry of the ACL, so it is always of the access type `Allow`, it is never inherited, and it carries no inheritance or propagation flags. ## 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. Reading effective access needs the Security privilege. In a session that does not hold it, the cmdlet warns before it starts and the calculation may fail with an error. Use `Enable-Privileges` in an elevated session to enable the privilege, and `Get-Privileges` to see which privileges the session holds. When the calculation fails, the error names the cause that Windows reported, such as a security descriptor without an owner; before 5.0.0, it blamed a missing Security privilege whenever the privilege wasn't enabled. Before 5.0.0, `-ExcludeNoneAccessEntries` had no effect, and the cmdlet returned nothing without `-Path` or for `-SecurityDescriptor`. When the computer of `-ServerName` couldn't be reached, the cmdlet warned that it had calculated the result on this computer, but returned no access instead of that result. Before 5.0.0-rc7, the warning about a computer that couldn't be reached didn't name the computer, and the cmdlet warned for every name of this computer except `localhost` in lowercase, such as `.`, `LOCALHOST`, or the computer name. Before 5.0.0-rc7, a user who wasn't an administrator got the error "Access is denied" and no result on a computer in a domain, also for a name of this computer, such as the default `localhost`. ## RELATED LINKS [Get-NTFSAccess](Get-NTFSAccess.md) [Get-NTFSSimpleAccess](Get-NTFSSimpleAccess.md) [Get-NTFSInheritance](Get-NTFSInheritance.md) [Enable-Privileges](Enable-Privileges.md) [Get-Privileges](Get-Privileges.md)