NTFSSecurity/Docs

NTFSSecurity

NTFSSecurity will be archived soon. Please move to WindowsAccessControl, which is also on the PowerShell Gallery: Install-Module -Name WindowsAccessControl.

NTFSSecurity is a PowerShell module for managing the permissions, audit settings, inheritance, and ownership of files and folders on NTFS volumes.

PowerShell offers only Get-Acl and Set-Acl; everything between reading and writing an access control list is up to you. NTFSSecurity closes this gap with task-level cmdlets that work with the PowerShell pipeline.

Features

• Read, add, remove, and clear access entries and audit entries.
• Show the effective access of an account and find orphaned entries.
• Inspect, enable, and disable inheritance.
• Get and set the owner of files and folders.
• Change several entries in memory and write them in one step.
• Enable the Backup, Restore, Take Ownership, and Security privileges to work on items that you can't otherwise access.
• Work with paths longer than 260 characters.
• Create hard links and symbolic links, list the hard links of a file, and get file hashes and disk space.

Requirements

• Windows with NTFS volumes.
• Windows PowerShell 5.1 or PowerShell 7. Get-FileHash2 works only in Windows PowerShell.
• An elevated session for audit operations, owner changes, and access to items that your account can't open. See Privileges.

Installation

Install the module from the PowerShell Gallery:

Install-Module -Name NTFSSecurity

To try a prerelease of the next version, add -AllowPrerelease. A prerelease is for testing; don't use it in production.

You can also install a release without the PowerShell Gallery. Download NTFSSecurity.zip from the releases page on GitHub and extract it into a module folder. In an elevated session, these commands install the module for all users of Windows PowerShell 5.1 and PowerShell 7:

Unblock-File -Path .\NTFSSecurity.zip
Expand-Archive -Path .\NTFSSecurity.zip -DestinationPath "$env:ProgramFiles\WindowsPowerShell\Modules"

Unblock-File removes the mark that Windows adds to downloaded files. If you extract a marked zip file with File Explorer, the extracted files keep the mark, and the execution policy RemoteSigned stops the module from loading.

The zip file contains the folder NTFSSecurity. Remove an older copy of that folder first. To install the module only for yourself, extract it into a folder of $env:PSModulePath in your profile instead, for example Documents\WindowsPowerShell\Modules for Windows PowerShell 5.1 or Documents\PowerShell\Modules for PowerShell 7.

Getting started

Import-Module -Name NTFSSecurity
Get-Command -Module NTFSSecurity
Get-NTFSAccess -Path C:\Windows

Read Concepts for the background and Examples for common tasks. Every cmdlet has a reference page with all parameters and examples; see the cmdlet list. The FAQ answers questions that come up again and again.

Cmdlets

Permissions

Cmdlet	Description
Get-NTFSAccess	Gets the access control entries (ACEs) of a file, a folder, or a security descriptor.
Add-NTFSAccess	Adds an access control entry (ACE) to a file, a folder, or a security descriptor.
Remove-NTFSAccess	Removes rights from the access control entries (ACEs) of a file, a folder, or a security descriptor.
Clear-NTFSAccess	Removes all explicit access control entries from a file or folder.
Get-NTFSEffectiveAccess	Gets the rights an account effectively has on a file or folder.
Get-NTFSOrphanedAccess	Gets the access control entries whose account cannot be resolved to a name.
Get-NTFSSimpleAccess	Gets the permissions of folders reduced to read, write, and delete.

Auditing

Cmdlet	Description
Get-NTFSAudit	Gets the audit entries of a file or folder.
Add-NTFSAudit	Adds an audit entry to a file or folder.
Remove-NTFSAudit	Removes an audit entry from a file or folder.
Clear-NTFSAudit	Removes all explicit audit entries from a file or folder.
Get-NTFSOrphanedAudit	Gets the audit entries whose account cannot be resolved.

Inheritance

Cmdlet	Description
Get-NTFSInheritance	Gets the inheritance state of the access rules and the audit rules of a file or folder.
Set-NTFSInheritance	Sets the inheritance of the access rules and the audit rules of a file or folder.
Enable-NTFSAccessInheritance	Restores the inheritance of access rules on a file or folder.
Disable-NTFSAccessInheritance	Blocks the inheritance of access rules on a file or folder.
Enable-NTFSAuditInheritance	Restores the inheritance of audit rules on a file or folder.
Disable-NTFSAuditInheritance	Blocks the inheritance of audit rules on a file or folder.

Owner and security descriptor

Cmdlet	Description
Get-NTFSOwner	Gets the owner of a file or folder.
Set-NTFSOwner	Sets the owner of a file or folder.
Get-NTFSSecurityDescriptor	Gets the security descriptor of a file or folder.
Set-NTFSSecurityDescriptor	Writes a security descriptor to the file or folder it was read from.

Privileges

Cmdlet	Description
Get-Privileges	Gets the privileges in the access token of the current PowerShell process.
Enable-Privileges	Enables the file system privileges in the access token of the current PowerShell process.
Disable-Privileges	Disables the file system privileges in the access token of the current PowerShell process.

Files and folders with long paths

Cmdlet	Description
Get-ChildItem2	Gets the files and folders in one or more folders, including paths longer than 260 characters.
Get-Item2	Gets the file or folder at a specified path, including paths longer than 260 characters.
Copy-Item2	Copies a file to another location, including paths longer than 260 characters.
Move-Item2	Moves a file or folder to another location, including paths longer than 260 characters.
Remove-Item2	Deletes a file or folder, including paths longer than 260 characters.
Test-Path2	Determines whether a file or folder exists at the specified path.

Links, hashes, and disk space

Cmdlet	Description
Get-NTFSHardLink	Gets all hard links that refer to the same file as the specified path.
New-NTFSHardLink	Creates a hard link to an existing file.
New-NTFSSymbolicLink	Creates a symbolic link to an existing file or folder.
Get-FileHash2	Gets the hash value of one or more files.
Get-DiskSpace	Gets size, free space, and cluster information for the volumes of a computer.

Tutorials

The author of the module wrote two tutorials in 2014. Some cmdlet names in them have changed since; use the cmdlet reference for the current names.

• NTFSSecurity Tutorial 1 - Getting, adding and removing permissions
• NTFSSecurity Tutorial 2 - Managing NTFS Inheritance and Using Privileges

Version history

See the changelog for the changes since 4.2.6 and the version history for 4.2.6 and earlier.

Contributing

Contributions are welcome. See the contributor guide.

License

NTFSSecurity is licensed under the MIT license.