diff --git a/.memory-bank/activeContext.md b/.memory-bank/activeContext.md index 5aa1f75..760b817 100644 --- a/.memory-bank/activeContext.md +++ b/.memory-bank/activeContext.md @@ -9,23 +9,32 @@ source: current task evidence ## Current focus -Work package 1 (housekeeping) on branch `ai/housekeeping`; the five work -packages and their order are in `progress.md`. +Work packages 1 and 2 are pushed; the maintainer opens their PRs: +`ai/housekeeping` into `master`, and `ai/ship-help` into +`ai/housekeeping`. The work packages and their order are in `progress.md`. ## Evidence -- PR #91 is merged into `master` as `690d8dd` (squash merge). The local - branch `ai/docs-alignment` had the same tree as `690d8dd` and is deleted; - GitHub had already deleted the remote branch. -- `.memory-bank/promptHistory.md` is ignored by git (`.gitignore`) and stays - a local file. -- The changelog policy is Decision 7. The inline Decisions moved to - `decisions/` records because `systemPatterns.md` was near its 110-line - budget. -- Read the Docs project `ntfssecurity` still builds the fork - `Sup3rlativ3/NTFSSecurity`. +- AppVeyor 54834155 (`ai/housekeeping`, `74abb0b`) passed. AppVeyor + 54834154 (`ai/ship-help`, `fba3a7d`) passed all four `test_script` + steps; Pester passed 218 of 218 tests in Windows PowerShell 5.1, + including the `Get-Help -Online` tests. +- The same build listed 870 tests on the Tests tab: the NUnit import files + each Pester 5 test under every enclosing block (Pester, file, Describe, + Context), so 216 tests appear four times and 2 three times. The + follow-up commit on `ai/ship-help` reports the results through the build + worker API instead (`POST api/tests/batch`), one entry per test; a local + run of step 04 against a sample test file sent 11 entries for 11 tests. +- The AppVeyor job log API returns `application/octet-stream`; decode the + bytes as UTF-8 before searching it. +- Merging work package 1 with a merge commit keeps `ai/ship-help` valid; + after a squash merge it needs + `git rebase --onto origin/master ai/housekeeping ai/ship-help`. +- PR descriptions for both work packages are in the session folder + (`files/pr`), outside the repository. ## Next step -The maintainer pushes `ai/housekeeping` and opens the PR. After the -go-ahead, start work package 2 (ship the generated help). +The maintainer pushes the follow-up commit on `ai/ship-help`, opens both +PRs, and checks that AppVeyor lists 218 tests; then work package 3 (Read +the Docs). diff --git a/.memory-bank/decisions/0008-commit-generated-help.md b/.memory-bank/decisions/0008-commit-generated-help.md new file mode 100644 index 0000000..22c4d2c --- /dev/null +++ b/.memory-bank/decisions/0008-commit-generated-help.md @@ -0,0 +1,26 @@ +--- +status: accepted +date: 2026-10-02 +last-verified: 2026-10-02 +owner: shared +source: maintainer choice in work package 2 (option A) +--- + +# Decision 8: Commit the generated help file and check it in CI + +- Choice: `NTFSSecurity\en-US\NTFSSecurity.dll-Help.xml` is generated from + `Docs/Cmdlets` with `New-ExternalHelp` (platyPS 0.14.2, Windows + PowerShell 5.1) and committed. `NTFSSecurity.csproj` copies it to the + output as `Content`, the manifest `FileList` lists it, and `appveyor.yml` + regenerates it and fails on `git status --porcelain -- NTFSSecurity/en-US`. +- Rationale: Releases are built locally in Visual Studio (Debug, written to + `C:\Program Files\WindowsPowerShell\Modules\NTFSSecurity`) and published + by hand with `Publish-Module`. A committed file ships with every build + and needs no tool on the build machine. Generating it in an MSBuild step + would need platyPS on every build machine, or would silently ship without + help when platyPS is missing. +- Consequence: every change to `Docs/Cmdlets` must be followed by + `New-ExternalHelp -Path .\Docs\Cmdlets -OutputPath .\NTFSSecurity\en-US + -Force`. The output is deterministic (byte-identical between runs), so + the CI check is exact. +- Rejected: an MSBuild `AfterBuild` target that runs platyPS. diff --git a/.memory-bank/progress.md b/.memory-bank/progress.md index 4cf9146..53dcd2d 100644 --- a/.memory-bank/progress.md +++ b/.memory-bank/progress.md @@ -33,7 +33,20 @@ source is unchanged since the 4.2.6 release except the superseded: #91 ships the same two `learn.microsoft.com` links in `Docs/index.md` and `README.md`. The maintainer decided to close it; the remote-mutation hook denied the agent's `gh pr close`, so the - maintainer closes it by hand. + maintainer closed it by hand (2026-10-02 21:18 UTC). +- 2026-10-02: Work package 2 (ship help, `ai/ship-help`, stacked on + `ai/housekeeping`): `en-US\NTFSSecurity.dll-Help.xml` generated from + `Docs/Cmdlets`, committed, copied by the csproj, and listed in a complete + `FileList` (Decision 8); stale `NTFSSecurity-Help.xml` and the unused + `NTFSSecurity.Help.pshproj` removed; `Tests\Help.Tests.ps1` (Pester 5) + and two CI steps added; six inline links in five cmdlet pages reworded + because platyPS drops the space after a link in the help text. Tests: 218 + of 218 pass in Windows PowerShell 5.1; without the help file 180 of 182 + failed. +- 2026-10-04: Work packages 1 and 2 pushed; AppVeyor 54834155 + (`74abb0b`) and 54834154 (`fba3a7d`, 218 of 218 Pester tests) passed. A + follow-up commit reports each test once on the AppVeyor Tests tab + (the NUnit upload listed 870 entries). ## Stable capabilities @@ -49,12 +62,11 @@ Work packages in the order agreed with the maintainer. Each gets one `ai/` branch and PR, committed locally; the maintainer pushes, and the next package starts only after the maintainer's go-ahead. -1. Housekeeping: committed on `ai/housekeeping`; awaiting push and PR. -2. Ship help: generate `en-US\NTFSSecurity.dll-Help.xml` from `Docs/Cmdlets` - with `New-ExternalHelp` and ship it (csproj `Content`, manifest - `FileList`); remove the stale `NTFSSecurity-Help.xml` and, if unused, - `NTFSSecurity\Help\NTFSSecurity.Help.pshproj`. Ask the maintainer: - commit the file plus a CI currency check, or generate it in the build. +1. Housekeeping: `ai/housekeeping` pushed at `74abb0b`, AppVeyor green; + PR into `master` to open. +2. Ship help: `ai/ship-help` pushed at `fba3a7d`, AppVeyor green; the + follow-up commit for the Tests tab awaits push. PR into + `ai/housekeeping` to open. 3. Read the Docs: project `ntfssecurity` (maintainer `Sup3rlativ3`) builds the fork; switch it to this repository or import a new project. Ask before installing Python for `mkdocs build --strict`. @@ -62,7 +74,11 @@ the next package starts only after the maintainer's go-ahead. inheritance entries from `CmdletsToExport` (36 cmdlets remain); ask about the next version (with or without a `PassThur` alias), `PowerShellVersion`, and `DotNetFrameworkVersion`; align `AssemblyInfo`. - No tag or publish. + No tag or publish. Inputs found in work package 2: `Test-ModuleManifest` + already fails on `PowerShellVersion = '2.0'` with `CompatiblePSEditions`; + releases ship Debug builds plus `.pdb`, `.xml`, and + `System.Management.Automation.dll` (`Private=True` reference), which + `FileList` doesn't list. 5. Code defects, listed below: `review: on`, one PR per group, regression test first. Pester 5 tests import `NTFSSecurity\bin\Release`, run in a `$env:TEMP` sandbox and in `appveyor.yml`, and skip elevated cases when diff --git a/.memory-bank/systemPatterns.md b/.memory-bank/systemPatterns.md index eb0e35c..e377dbd 100644 --- a/.memory-bank/systemPatterns.md +++ b/.memory-bank/systemPatterns.md @@ -18,7 +18,9 @@ NTFSSecurity.psd1 ─┬─ ScriptsToProcess: NTFSSecurity.Init.ps1 │ (Owner, IsInheritanceBlocked, LengthOnDisk on │ FileInfo/DirectoryInfo; AccountType on ACEs) ├─ ModuleToProcess: NTFSSecurity.psm1 (aliases) - └─ NestedModules: NTFSSecurity.dll (36 cmdlets) + ├─ NestedModules: NTFSSecurity.dll (36 cmdlets) + └─ en-US\NTFSSecurity.dll-Help.xml (Get-Help; generated + from Docs/Cmdlets, Decision 8) NTFSSecurity.dll ── cmdlets ──> Security2.dll (FileSystemAccessRule2, FileSystemAuditRule2, IdentityReference2, FileSystemInheritanceInfo, EffectiveAccess) @@ -52,6 +54,7 @@ Each Decision record is a file in `decisions/`; read only the relevant ones. | 5 | [Document defects, don't fix them in docs work](decisions/0005-document-defects-separately.md) | | 6 | [CI checks the docs against a build of the source](decisions/0006-ci-checks-docs-against-build.md) | | 7 | [CHANGELOG lists user-visible changes only](decisions/0007-changelog-user-visible-only.md) | +| 8 | [Commit the generated help file and check it in CI](decisions/0008-commit-generated-help.md) | ## Patterns @@ -61,5 +64,20 @@ Each Decision record is a file in `decisions/`; read only the relevant ones. `Docs/Cmdlets` must round-trip through `Update-MarkdownHelp` unchanged. - platyPS rewrites non-ASCII punctuation such as em dashes; keep cmdlet pages ASCII-only. +- In cmdlet pages, end a sentence with a link: platyPS renders a link as + `text (url)` in the help file and drops the space after it. - Verify examples in a `$env:TEMP` sandbox, never on real data; parse every example and check its parameters against `Get-Command` metadata. + +### Testing the module + +- Pester 5 tests in `Tests/*.Tests.ps1` import + `NTFSSecurity\bin\Release\NTFSSecurity.psd1` and run in Windows + PowerShell 5.1 (as in AppVeyor); PowerShell 7 runs are a secondary check. +- `Get-Help -Online` is tested with the internal test hook + `BypassOnlineHelpRetrieval`, which returns the URI instead of opening a + browser. In PowerShell 7 the hook also skips the help file, so that test + runs only in Windows PowerShell; PowerShell 7 resolves the same URI. +- Report Pester 5 results to AppVeyor through the build worker API, not as + an uploaded NUnit file: the NUnit import files each test under every + enclosing block (870 entries for 218 tests in build 54834154). diff --git a/.memory-bank/techContext.md b/.memory-bank/techContext.md index c426e25..8acbb66 100644 --- a/.memory-bank/techContext.md +++ b/.memory-bank/techContext.md @@ -22,6 +22,10 @@ source: repository evidence - Documentation: MkDocs (`mkdocs.yml`, theme `readthedocs`, `docs_dir: ./Docs`) built by Read the Docs (`.readthedocs.yml` v2); cmdlet pages are platyPS 0.14 markdown (schema 2.0.0) in `Docs/Cmdlets`. +- Help: `NTFSSecurity\en-US\NTFSSecurity.dll-Help.xml`, generated from + `Docs/Cmdlets` and committed (Decision 8). +- Tests: Pester 5 tests in `Tests` (`Help.Tests.ps1`) against the Release + build. ## Environment @@ -34,6 +38,12 @@ source: repository evidence `/p:CscToolPath` to the Roslyn `csc.exe` of the `Microsoft.Net.Compilers` package; the legacy C# 5 compiler fails with CS0136. `dotnet msbuild` fails on the binary resources in `Resources.resx` (MSB3822, MSB3823). +- platyPS 0.14.2, Pester 5.7.1, PSScriptAnalyzer, and powershell-yaml are + installed only for PowerShell 7. Windows PowerShell 5.1 imports platyPS + and Pester by full path + (`~\OneDrive\Documents\PowerShell\Modules\platyPS\0.14.2`, + `C:\Program Files\PowerShell\Modules\Pester\5.7.1`) with + `$env:PSModulePath` cleared. MarkdownLinkCheck is not installed. ## Constraints @@ -43,8 +53,15 @@ source: repository evidence `-PassThru` rename and `CompatiblePSEditions` in the manifest. - `CmdletsToExport` lists `Show-NTFSSimpleAccess`, which no longer exists (WinForms code removed in `d3063de`), and repeats the inheritance cmdlets. -- `NTFSSecurity/NTFSSecurity-Help.xml` is a stale pre-4.x MAML file for old - command names; binary-module help must be named `NTFSSecurity.dll-Help.xml`. +- `Test-ModuleManifest` fails in Windows PowerShell 5.1: + `CompatiblePSEditions` requires `PowerShellVersion` 5.1 or higher, and the + manifest says `2.0` (work package 4). +- Releases have no script and no CI deployment. Evidence from 4.2.6: the + Gallery DLLs are Debug builds (`DebuggableAttribute` 263), the nuspec + comes from `Publish-Module`, the package holds the whole output folder + (`.pdb`, `AlphaFS.xml`, 7 MB `System.Management.Automation.dll`), and the + published manifest differs from the tag only by `ModuleVersion` (tags + carry the previous version). GitHub releases attach `NTFSSecurity.zip`. - CI: AppVeyor project `raandree/ntfssecurity` builds branches and pull requests. Read the Docs (`ntfssecurity`) and a second AppVeyor project are attached to the fork `Sup3rlativ3/NTFSSecurity`. @@ -60,12 +77,23 @@ source: repository evidence per project plus `Microsoft.NETFramework.ReferenceAssemblies.net452` 1.0.3, build `NTFSSecurity.csproj` in Release with `TargetFrameworkRootPath`/`FrameworkPathOverride`, import - `NTFSSecurity\bin\Release\NTFSSecurity.psd1`, run `Update-MarkdownHelp`, - and fail on `git diff -- Docs/Cmdlets`; then `Get-MarkdownLink -BrokenOnly`. + `NTFSSecurity\bin\Release\NTFSSecurity.psd1`, then: 01 run + `Update-MarkdownHelp` and fail on `git diff -- Docs/Cmdlets`; 02 + `Get-MarkdownLink -BrokenOnly`; 03 regenerate the help file and fail on + `git status --porcelain -- NTFSSecurity/en-US`; 04 Pester 5.7.1 on + `Tests`, each result reported once through the build worker API + (`POST $env:APPVEYOR_API_URL/api/tests/batch`). +- AppVeyor REST API (public, no token): build + `api/projects/raandree/ntfssecurity/builds/`, job log + `api/buildjobs//log` (bytes; decode as UTF-8), and test list + `api/buildjobs//tests`. - Run platyPS in Windows PowerShell 5.1 to avoid PowerShell 7.4+ `-ProgressAction` noise. - Placeholder check: no `{{` left in `Docs/Cmdlets/*.md`. -- Help build check: `New-ExternalHelp -Path ./Docs/Cmdlets` to a temp folder. +- Help file: `New-ExternalHelp -Path .\Docs\Cmdlets -OutputPath + .\NTFSSecurity\en-US -Force` must leave `git status` unchanged. +- Pester: run detached (`Start-DetachedPowerShell.ps1`) in Windows + PowerShell 5.1; a run without `bin\Release\en-US` must fail. - Markdown lint: `npx markdownlint-cli2` with `MD013` limited to prose (tables, code, and headings excluded) on the conceptual pages. - YAML: `ConvertFrom-Yaml` (powershell-yaml) on `mkdocs.yml`, diff --git a/CHANGELOG.md b/CHANGELOG.md index 6dae653..f48741d 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -23,6 +23,10 @@ in the wiki. ### Fixed +- Fix `Get-Help`, which showed only the syntax: ship the help file + `en-US\NTFSSecurity.dll-Help.xml` generated from the cmdlet documentation, + including the links that `Get-Help -Online` opens, instead of the outdated + `NTFSSecurity-Help.xml` - Fix documentation examples that did not work, such as restoring permissions from a CSV file and filtering entries by account - Fix the documentation site navigation, the "Edit on GitHub" links, and the diff --git a/Docs/Cmdlets/Add-NTFSAccess.md b/Docs/Cmdlets/Add-NTFSAccess.md index 68619c2..e80826e 100644 --- a/Docs/Cmdlets/Add-NTFSAccess.md +++ b/Docs/Cmdlets/Add-NTFSAccess.md @@ -90,7 +90,7 @@ This command restores the access control entries that `Get-NTFSAccess` exported ### -AccessRights -Specifies the rights the ACE grants or denies. The parameter accepts basic rights such as `Read`, `ReadAndExecute`, `Modify`, and `FullControl`, granular rights such as `CreateFiles`, `Traverse`, or `WriteAttributes`, and any combination of them. An `Allow` ACE always receives `Synchronize` in addition to the specified rights. See [Concepts](../Concepts.md) for how the values relate to the Windows security dialog. +Specifies the rights the ACE grants or denies. The parameter accepts basic rights such as `Read`, `ReadAndExecute`, `Modify`, and `FullControl`, granular rights such as `CreateFiles`, `Traverse`, or `WriteAttributes`, and any combination of them. An `Allow` ACE always receives `Synchronize` in addition to the specified rights. For how the values relate to the Windows security dialog, see [Concepts](../Concepts.md). ```yaml Type: FileSystemRights2 @@ -159,7 +159,7 @@ Accept wildcard characters: False Specifies which kind of child objects inherit the ACE. `ContainerInherit` passes the ACE on to child folders, `ObjectInherit` passes it on to child files, and `None` keeps the ACE on the item itself. The default is `ContainerInherit, ObjectInherit`. Inheritance flags have no effect on files, where the ACE is always created with `None`. -For details about the flags, see [InheritanceFlags Enum](https://learn.microsoft.com/en-us/dotnet/api/system.security.accesscontrol.inheritanceflags) in the .NET documentation. +For details about the flags, see the .NET documentation of the [InheritanceFlags Enum](https://learn.microsoft.com/en-us/dotnet/api/system.security.accesscontrol.inheritanceflags). ```yaml Type: InheritanceFlags diff --git a/Docs/Cmdlets/Add-NTFSAudit.md b/Docs/Cmdlets/Add-NTFSAudit.md index 25ac651..6b24358 100644 --- a/Docs/Cmdlets/Add-NTFSAudit.md +++ b/Docs/Cmdlets/Add-NTFSAudit.md @@ -92,7 +92,7 @@ This command adds an audit entry for `CONTOSO\JohnDoe` to the in-memory security ### -AccessRights -Specifies the access rights to audit. The value accepts the basic rights such as `Read`, `Write`, `Modify`, and `FullControl` as well as the individual rights such as `Delete` or `WriteAttributes`, and it accepts a comma-separated list that combines them. See [Concepts](../Concepts.md) for the meaning of each right. +Specifies the access rights to audit. The value accepts the basic rights such as `Read`, `Write`, `Modify`, and `FullControl` as well as the individual rights such as `Delete` or `WriteAttributes`, and it accepts a comma-separated list that combines them. For the meaning of each right, see [Concepts](../Concepts.md). ```yaml Type: FileSystemRights2 diff --git a/Docs/Cmdlets/Get-NTFSAudit.md b/Docs/Cmdlets/Get-NTFSAudit.md index d76b5d2..03ec754 100644 --- a/Docs/Cmdlets/Get-NTFSAudit.md +++ b/Docs/Cmdlets/Get-NTFSAudit.md @@ -27,7 +27,7 @@ Get-NTFSAudit [-SecurityDescriptor] [-Account `. diff --git a/NTFSSecurity/Help/NTFSSecurity.Help.pshproj b/NTFSSecurity/Help/NTFSSecurity.Help.pshproj deleted file mode 100644 index e811fa7..0000000 --- a/NTFSSecurity/Help/NTFSSecurity.Help.pshproj +++ /dev/null @@ -1,2786 +0,0 @@ - - - NTFSSecurity - 3.2.3 - Windows PowerShell Module for managing file and folder security on NTFS volumes - true - false - - - - Add-NTFSAccess - - - - - - - - - - - - - - - - - - - Add-NTFSAccess [-Path] <String[]> [-Account] <IdentityReference2[]> [-AccessRights] <FileSystemRights2> [-AccessType <AccessControlType>] [-InheritanceFlags <InheritanceFlags>] [-PropagationFlags <PropagationFlags>] [-PassThru] [-InformationAction <ActionPreference>] [-InformationVariable <String>] - Add-NTFSAccess [-Path] <String[]> [-Account] <IdentityReference2[]> [-AccessRights] <FileSystemRights2> [-AccessType <AccessControlType>] [-AppliesTo <ApplyTo>] [-PassThru] [-InformationAction <ActionPreference>] [-InformationVariable <String>] - Add-NTFSAccess [-SecurityDescriptor] <FileSystemSecurity2[]> [-Account] <IdentityReference2[]> [-AccessRights] <FileSystemRights2> [-AccessType <AccessControlType>] [-AppliesTo <ApplyTo>] [-PassThru] [-InformationAction <ActionPreference>] [-InformationVariable <String>] - Add-NTFSAccess [-SecurityDescriptor] <FileSystemSecurity2[]> [-Account] <IdentityReference2[]> [-AccessRights] <FileSystemRights2> [-AccessType <AccessControlType>] [-InheritanceFlags <InheritanceFlags>] [-PropagationFlags <PropagationFlags>] [-PassThru] [-InformationAction <ActionPreference>] [-InformationVariable <String>] - - - - Path - - System.Management.Automation.ParameterAttribute - System.Management.Automation.ParameterAttribute - System.Management.Automation.ValidateNotNullOrEmptyAttribute - System.Management.Automation.AliasAttribute - - - FullName - - - - - - Account - - System.Management.Automation.ParameterAttribute - System.Management.Automation.AliasAttribute - - - IdentityReference, ID - - - - - - AccessRights - - System.Management.Automation.ParameterAttribute - System.Management.Automation.AliasAttribute - - - FileSystemRights - - - - - - AccessType - - System.Management.Automation.ParameterAttribute - System.Management.Automation.AliasAttribute - - - AccessControlType - - - - - - InheritanceFlags - - System.Management.Automation.ParameterAttribute - System.Management.Automation.ParameterAttribute - - - - - - - PropagationFlags - - System.Management.Automation.ParameterAttribute - System.Management.Automation.ParameterAttribute - - - - - - - PassThru - - System.Management.Automation.ParameterAttribute - - - - - - - InformationAction - - System.Management.Automation.AliasAttribute - System.Management.Automation.ParameterAttribute - - - infa - - - - - - InformationVariable - - System.Management.Automation.ParameterAttribute - System.Management.Automation.Internal.CommonParameters+ValidateVariableName - System.Management.Automation.AliasAttribute - - - iv - - - - - - AppliesTo - - System.Management.Automation.ParameterAttribute - System.Management.Automation.ParameterAttribute - - - - - - - SecurityDescriptor - - System.Management.Automation.ParameterAttribute - System.Management.Automation.ParameterAttribute - System.Management.Automation.ValidateNotNullOrEmptyAttribute - - - - - - - - - - false - - - Add-NTFSAudit - - - - - - - - - - - - - - - - - Add-NTFSAudit [-Account] <IdentityReference2> [-AccessRights] <FileSystemRights> [-Type <AuditFlags>] [-InheritanceFlags <InheritanceFlags>] [-PropagationFlags <PropagationFlags>] [-PassThru] [-InformationAction <ActionPreference>] [-InformationVariable <String>] - Add-NTFSAudit [-Account] <IdentityReference2> [-AccessRights] <FileSystemRights> [-Type <AuditFlags>] [-AppliesTo <ApplyTo>] [-PassThru] [-InformationAction <ActionPreference>] [-InformationVariable <String>] - - - - Account - - System.Management.Automation.ParameterAttribute - System.Management.Automation.AliasAttribute - - - IdentityReference, ID - - - - - - AccessRights - - System.Management.Automation.ParameterAttribute - System.Management.Automation.AliasAttribute - - - FileSystemRights - - - - - - Type - - System.Management.Automation.ParameterAttribute - - - - - - - InheritanceFlags - - System.Management.Automation.ParameterAttribute - - - - - - - PropagationFlags - - System.Management.Automation.ParameterAttribute - - - - - - - PassThru - - System.Management.Automation.ParameterAttribute - - - - - - - InformationAction - - System.Management.Automation.AliasAttribute - System.Management.Automation.ParameterAttribute - - - infa - - - - - - InformationVariable - - System.Management.Automation.ParameterAttribute - System.Management.Automation.Internal.CommonParameters+ValidateVariableName - System.Management.Automation.AliasAttribute - - - iv - - - - - - AppliesTo - - System.Management.Automation.ParameterAttribute - - - - - - - - - - false - - - Copy-NTFSAccess - - - - - - - - - - - - - - - - Copy-NTFSAccess [-Path] <String> [-DestinationPath] <String> [-Account <IdentityReference2[]>] [-PassThru] [-InformationAction <ActionPreference>] [-InformationVariable <String>] - - - - Path - - System.Management.Automation.ParameterAttribute - System.Management.Automation.ValidateNotNullOrEmptyAttribute - System.Management.Automation.AliasAttribute - - - FullName - - - - - - DestinationPath - - System.Management.Automation.ParameterAttribute - System.Management.Automation.ValidateNotNullOrEmptyAttribute - - - - - - - Account - - System.Management.Automation.ParameterAttribute - System.Management.Automation.AliasAttribute - - - IdentityReference, ID - - - - - - PassThru - - System.Management.Automation.ParameterAttribute - - - - - - - InformationAction - - System.Management.Automation.AliasAttribute - System.Management.Automation.ParameterAttribute - - - infa - - - - - - InformationVariable - - System.Management.Automation.ParameterAttribute - System.Management.Automation.Internal.CommonParameters+ValidateVariableName - System.Management.Automation.AliasAttribute - - - iv - - - - - - - - - false - - - Disable-NTFSAccessInheritance - - - - - - - - - - - - - - - - - Disable-NTFSAccessInheritance [[-Path] <String[]>] [-RemoveInheritedAccessRules] [-PassThru] [-InformationAction <ActionPreference>] [-InformationVariable <String>] - Disable-NTFSAccessInheritance [-SecurityDescriptor] <FileSystemSecurity2[]> [-RemoveInheritedAccessRules] [-PassThru] [-InformationAction <ActionPreference>] [-InformationVariable <String>] - - - - Path - - System.Management.Automation.ParameterAttribute - System.Management.Automation.ValidateNotNullOrEmptyAttribute - System.Management.Automation.AliasAttribute - - - FullName - - - - - - RemoveInheritedAccessRules - - System.Management.Automation.ParameterAttribute - - - - - - - PassThru - - System.Management.Automation.ParameterAttribute - - - - - - - InformationAction - - System.Management.Automation.AliasAttribute - System.Management.Automation.ParameterAttribute - - - infa - - - - - - InformationVariable - - System.Management.Automation.ParameterAttribute - System.Management.Automation.Internal.CommonParameters+ValidateVariableName - System.Management.Automation.AliasAttribute - - - iv - - - - - - SecurityDescriptor - - System.Management.Automation.ParameterAttribute - System.Management.Automation.ValidateNotNullOrEmptyAttribute - - - - - - - - - - false - - - Disable-NTFSAuditInheritance - - - - - - - - - - - - - - - - - Disable-NTFSAuditInheritance [[-Path] <String[]>] [-RemoveInheritedAccessRules] [-PassThru] [-InformationAction <ActionPreference>] [-InformationVariable <String>] - Disable-NTFSAuditInheritance [-SecurityDescriptor] <FileSystemSecurity2[]> [-RemoveInheritedAccessRules] [-PassThru] [-InformationAction <ActionPreference>] [-InformationVariable <String>] - - - - Path - - System.Management.Automation.ParameterAttribute - System.Management.Automation.ValidateNotNullOrEmptyAttribute - System.Management.Automation.AliasAttribute - - - FullName - - - - - - RemoveInheritedAccessRules - - System.Management.Automation.ParameterAttribute - - - - - - - PassThru - - System.Management.Automation.ParameterAttribute - - - - - - - InformationAction - - System.Management.Automation.AliasAttribute - System.Management.Automation.ParameterAttribute - - - infa - - - - - - InformationVariable - - System.Management.Automation.ParameterAttribute - System.Management.Automation.Internal.CommonParameters+ValidateVariableName - System.Management.Automation.AliasAttribute - - - iv - - - - - - SecurityDescriptor - - System.Management.Automation.ParameterAttribute - System.Management.Automation.ValidateNotNullOrEmptyAttribute - - - - - - - - - - false - - - Disable-Privileges - - - - - - - - - - - - - - - - Disable-Privileges [-PassThru] [-InformationAction <ActionPreference>] [-InformationVariable <String>] - - - - PassThru - - System.Management.Automation.ParameterAttribute - - - - - - - InformationAction - - System.Management.Automation.AliasAttribute - System.Management.Automation.ParameterAttribute - - - infa - - - - - - InformationVariable - - System.Management.Automation.ParameterAttribute - System.Management.Automation.Internal.CommonParameters+ValidateVariableName - System.Management.Automation.AliasAttribute - - - iv - - - - - - - - - false - - - Enable-NTFSAccessInheritance - - - - - - - - - - - - - - - - - Enable-NTFSAccessInheritance [[-Path] <String[]>] [-PassThru] [-RemoveExplicitAccessRules] [-InformationAction <ActionPreference>] [-InformationVariable <String>] - Enable-NTFSAccessInheritance [-SecurityDescriptor] <FileSystemSecurity2[]> [-PassThru] [-RemoveExplicitAccessRules] [-InformationAction <ActionPreference>] [-InformationVariable <String>] - - - - Path - - System.Management.Automation.ParameterAttribute - System.Management.Automation.ValidateNotNullOrEmptyAttribute - System.Management.Automation.AliasAttribute - - - FullName - - - - - - PassThru - - System.Management.Automation.ParameterAttribute - - - - - - - RemoveExplicitAccessRules - - System.Management.Automation.ParameterAttribute - - - - - - - InformationAction - - System.Management.Automation.AliasAttribute - System.Management.Automation.ParameterAttribute - - - infa - - - - - - InformationVariable - - System.Management.Automation.ParameterAttribute - System.Management.Automation.Internal.CommonParameters+ValidateVariableName - System.Management.Automation.AliasAttribute - - - iv - - - - - - SecurityDescriptor - - System.Management.Automation.ParameterAttribute - System.Management.Automation.ValidateNotNullOrEmptyAttribute - - - - - - - - - - false - - - Enable-NTFSAuditInheritance - - - - - - - - - - - - - - - - - Enable-NTFSAuditInheritance [[-Path] <String[]>] [-PassThru] [-RemoveExplicitAccessRules] [-InformationAction <ActionPreference>] [-InformationVariable <String>] - Enable-NTFSAuditInheritance [-SecurityDescriptor] <FileSystemSecurity2[]> [-PassThru] [-RemoveExplicitAccessRules] [-InformationAction <ActionPreference>] [-InformationVariable <String>] - - - - Path - - System.Management.Automation.ParameterAttribute - System.Management.Automation.ValidateNotNullOrEmptyAttribute - System.Management.Automation.AliasAttribute - - - FullName - - - - - - PassThru - - System.Management.Automation.ParameterAttribute - - - - - - - RemoveExplicitAccessRules - - System.Management.Automation.ParameterAttribute - - - - - - - InformationAction - - System.Management.Automation.AliasAttribute - System.Management.Automation.ParameterAttribute - - - infa - - - - - - InformationVariable - - System.Management.Automation.ParameterAttribute - System.Management.Automation.Internal.CommonParameters+ValidateVariableName - System.Management.Automation.AliasAttribute - - - iv - - - - - - SecurityDescriptor - - System.Management.Automation.ParameterAttribute - System.Management.Automation.ValidateNotNullOrEmptyAttribute - - - - - - - - - - false - - - Enable-Privileges - - - - - - - - - - - - - - - - Enable-Privileges [-PassThru] [-InformationAction <ActionPreference>] [-InformationVariable <String>] - - - - PassThru - - System.Management.Automation.ParameterAttribute - - - - - - - InformationAction - - System.Management.Automation.AliasAttribute - System.Management.Automation.ParameterAttribute - - - infa - - - - - - InformationVariable - - System.Management.Automation.ParameterAttribute - System.Management.Automation.Internal.CommonParameters+ValidateVariableName - System.Management.Automation.AliasAttribute - - - iv - - - - - - - - - false - - - Get-ChildItem2 - - Gets the items and child items in one or more specified locations. - The Get-ChildItem2 cmdlet gets the items in one or more specified locations. If the item is a container, it gets the items inside the container, known as child items. You can use the Recurse parameter to get items in all child containers. - -Get-ChildItem2 does not have a 248 character limit on the path. It does not use the FileSystem provider but AlphaFS (https://github.com/alphaleonis/AlphaFS/) which is faster. - -Get-ChildItem2 supports only locations on the file system. Get-ChildItem2 cmdlet gets the directories, subdirectories, and files. In a file system directory, it gets subdirectories and files. - -By default, Get-ChildItem2 gets non-hidden items, but you can use the Directory, File, Hidden, ReadOnly, and System parameters to get only items with these attributes. To create a complex attribute search, use the Attributes parameter. If you use these parameters, Get-ChildItem gets only the items that meet all search conditions, as though the parameters were connected by an AND operator. - You can also refer to Get-ChildItem2 by its built-in alias dir2. - -Get-ChildItem2 does not get hidden items by default. To get hidden items, use the Force parameter. - System.String[] - - You can pipe a file system path (in quotation marks) to Get-ChildItem2. - Alphaleonis.Win32.Filesystem.DirectoryInfo, Alphaleonis.Win32.Filesystem.FileInfo, System.String - - - - - - - - Get-ChildItem2 [[-Path] <String[]>] [[-Filter] <String>] [-Recurse] [-Directory] [-File] [-Attributes <FileAttributes>] [-Hidden] [-System] [-ReadOnly] [-Force] [-SkipMountPoints] [-SkipSymbolicLinks] [-Depth <Nullable`1[Int32]>] [-InformationAction <ActionPreference>] [-InformationVariable <String>] - - - - Path - - System.Management.Automation.ParameterAttribute - System.Management.Automation.ValidateNotNullOrEmptyAttribute - System.Management.Automation.AliasAttribute - - - FullName - - Specifies a path to one or more locations. Wildcards are NOT permitted. The default location is the current directory (.). - - - - Filter - - System.Management.Automation.ParameterAttribute - - - Specifies a wildcard filter. The value of this parameter qualifies the Path parameter. 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. - - - - Recurse - - System.Management.Automation.ParameterAttribute - - - Gets the items in the specified locations and in all child items of the locations. - - - - Directory - - System.Management.Automation.ParameterAttribute - - - Gets directories (folders). - -To get only directories, use the Directory parameter and omit the File parameter. To exclude directories, use the File parameter and omit the Directory parameter, or use the Attributes parameter. - - - - File - - System.Management.Automation.ParameterAttribute - - - Gets files. - -To get only files, use the File parameter and omit the Directory parameter. To exclude files, use the Directory parameter and omit the File parameter, or use the Attributes parameter. - - - - Attributes - - System.Management.Automation.ParameterAttribute - - - Gets files and folders with the specified attributes. This parameter supports all attributes and lets you specify complex combinations of attributes. - -To find files and folders with commonly used attributes, you can use the Attributes parameter, or the Directory, File, Hidden, ReadOnly, and System switch parameters. - -The Attributes parameter supports the following attributes: Archive, Compressed, Device, Directory, Encrypted, Hidden, Normal, NotContentIndexed, Offline, ReadOnly, ReparsePoint, SparseFile, System, and Temporary. For a description of these attributes, see the FileAttributes enumeration at http://go.microsoft.com/fwlink/?LinkId=201508. - - - - SkipMountPoints - - System.Management.Automation.ParameterAttribute - - - Skips mount points. - -Use this switch to not follow mount points when doing a recursive listing. - - - - SkipSymbolicLinks - - System.Management.Automation.ParameterAttribute - - - Skips symbolic links. - -Use this switch to not follow symbolic links when doing a recursive listing. - - - - Depth - - System.Management.Automation.ParameterAttribute - - - Limits the depth in a recursive listing. - -If you need only a certain level of subfolders, use this parameter. For example, if you only need the content of the current folder + the content of all subfolders, specify a depth of 1. - - - - InformationAction - - System.Management.Automation.AliasAttribute - System.Management.Automation.ParameterAttribute - - - infa - - - - - - InformationVariable - - System.Management.Automation.ParameterAttribute - System.Management.Automation.Internal.CommonParameters+ValidateVariableName - System.Management.Automation.AliasAttribute - - - iv - - - - - - Hidden - - System.Management.Automation.ParameterAttribute - - - Gets only hidden files and directories (folders). By default, Get-ChildItem gets only non-hidden items, but you can use the Force parameter to include hidden items in the results. - -To get only hidden items, use the Hidden parameter or the Hidden value of the Attributes parameter. To exclude hidden items, omit the Hidden parameter or use the Attributes parameter. - - - - System - - System.Management.Automation.ParameterAttribute - - - Gets only system files and directories (folders). - -To get only system files and folders, use the System parameter or the System value of the Attributes parameter. To exclude system files and folders, use the Attributes parameter. - - - - ReadOnly - - System.Management.Automation.ParameterAttribute - - - Gets only read-only files and directories (folders). - -To get only read-only items, use the ReadOnly parameter or the ReadOnly value of the Attributes parameter. To exclude read-only items, use the Attributes parameter. - - - - Force - - System.Management.Automation.ParameterAttribute - - - Gets hidden files and folders. By default, hidden files and folder are excluded. You can also get hidden files and folders by using the Hidden parameter or the Hidden value of the Attributes parameter. - - - - - - Example 1 - C:\PS> Get-ChildItem2 - This command gets the files and subdirectories in the current directory. If the current directory does not have child items, the command does not return any results. - - - - Example 2 - C:\PS> Get-Childitem -System -File -Recurse - This command gets system files in the current directory and its subdirectories. - - - - Example 3 - PS C:\> Get-ChildItem2 -Path D:\LabSources\ -Force -Depth 2 - Gets all items from the folder D:\LabSources up to a level of 2. The Force switch makes the command to return also hidden items. - - - - - - false - - - Get-DiskSpace - - Retrieves a statistic about a file system drive. - Get-DiskSpace retrieves a drive and usage statistic of a given drive. The information provided is AvailableFreeSpacePercent, AvailableFreeSpaceUnitSizeClusterSize, DriveName, TotalSizeUnitSize, UsedSpacePercent, UsedSpaceUnitSize, FreeBytesAvailable, TotalNumberOfBytes, TotalNumberOfFreeBytes, BytesPerSector, NumberOfFreeClusters, SectorsPerCluster, TotalNumberOfClusters. - - - System.String - - - Alphaleonis.Win32.Filesystem.DiskSpaceInfo - - - - - - - - Get-DiskSpace [[-DriveLetter] <String[]>] [-InformationAction <ActionPreference>] [-InformationVariable <String>] - - - - DriveLetter - - System.Management.Automation.ParameterAttribute - System.Management.Automation.ValidatePatternAttribute - - - The drive to get the statistic from. - - - - InformationAction - - System.Management.Automation.AliasAttribute - System.Management.Automation.ParameterAttribute - - - infa - - - - - - InformationVariable - - System.Management.Automation.ParameterAttribute - System.Management.Automation.Internal.CommonParameters+ValidateVariableName - System.Management.Automation.AliasAttribute - - - iv - - - - - - - - Example 1 - PS C:\> Get-DiskSpace -DriveLetter d: - Get the drive statistic of drive D:. - AvailableFreeSpacePercent : 75.73% -AvailableFreeSpaceUnitSize : 361.07 GB -ClusterSize : 4096 -DriveName : d:\ -TotalSizeUnitSize : 476.81 GB -UsedSpacePercent : 24.27% -UsedSpaceUnitSize : 115.74 GB -FreeBytesAvailable : 387699257344 -TotalNumberOfBytes : 511974567936 -TotalNumberOfFreeBytes : 387699257344 -BytesPerSector : 512 -NumberOfFreeClusters : 94653139 -SectorsPerCluster : 8 -TotalNumberOfClusters : 124993791 - - - - - false - - - Get-Item2 - - Gets files and folders. - The Get-Item2 cmdlet gets the item at the specified location. It does not get the contents of the item at the location. - -Get-ChildItem2 does not have a 248 character limit on the path. It does not use the FileSystem provider but AlphaFS (https://github.com/alphaleonis/AlphaFS/) which is faster. - -The Get-Item cmdlet works only on the file system and gets files and folders. - - You can also refer to Get-Item2 by its built-in alias gi2. - System.String[] - - You can pipe a file system path (in quotation marks) to Get-ChildItem2. - Alphaleonis.Win32.Filesystem.DirectoryInfo, Alphaleonis.Win32.Filesystem.FileInfo, System.String - - - - - - - - Get-Item2 [[-Path] <String[]>] [-InformationAction <ActionPreference>] [-InformationVariable <String>] - - - - Path - - System.Management.Automation.ParameterAttribute - System.Management.Automation.ValidateNotNullOrEmptyAttribute - System.Management.Automation.AliasAttribute - - - FullName - - Specifies a path to one or more locations. Wildcards are NOT permitted. The default location is the current directory (.). - - - - InformationAction - - System.Management.Automation.AliasAttribute - System.Management.Automation.ParameterAttribute - - - infa - - - - - - InformationVariable - - System.Management.Automation.ParameterAttribute - System.Management.Automation.Internal.CommonParameters+ValidateVariableName - System.Management.Automation.AliasAttribute - - - iv - - - - - - - - Example 1 - PS C:\> Get-Item2 - Gets the current folder. - Directory: - - -Mode Inherits LastWriteTime Size(M) Name ----- -------- ------------- ------- ---- -d--hs True 8/4/2015 11:00 PM <DIR> C:\ - - - Example 2 - PS C:\> Get-Item2 -Path C:\Windows - Gets the Windows folder. - Directory: C:\ - - -Mode Inherits LastWriteTime Size(M) Name ----- -------- ------------- ------- ---- -d---- True 8/4/2015 10:18 PM <DIR> Windows - - - - - false - - - Get-NTFSAccess - - - - - - - - - - - - - - - - - Get-NTFSAccess [[-Path] <String[]>] [-Account <IdentityReference2>] [-ExcludeExplicit] [-ExcludeInherited] [-InformationAction <ActionPreference>] [-InformationVariable <String>] - Get-NTFSAccess [-SecurityDescriptor] <FileSystemSecurity2[]> [-Account <IdentityReference2>] [-ExcludeExplicit] [-ExcludeInherited] [-InformationAction <ActionPreference>] [-InformationVariable <String>] - - - - Path - - System.Management.Automation.ParameterAttribute - System.Management.Automation.ValidateNotNullOrEmptyAttribute - System.Management.Automation.AliasAttribute - - - FullName - - - - - - Account - - System.Management.Automation.ParameterAttribute - System.Management.Automation.AliasAttribute - System.Management.Automation.ValidateNotNullOrEmptyAttribute - - - IdentityReference, ID - - - - - - ExcludeExplicit - - System.Management.Automation.ParameterAttribute - - - - - - - ExcludeInherited - - System.Management.Automation.ParameterAttribute - - - - - - - InformationAction - - System.Management.Automation.AliasAttribute - System.Management.Automation.ParameterAttribute - - - infa - - - - - - InformationVariable - - System.Management.Automation.ParameterAttribute - System.Management.Automation.Internal.CommonParameters+ValidateVariableName - System.Management.Automation.AliasAttribute - - - iv - - - - - - SecurityDescriptor - - System.Management.Automation.ParameterAttribute - System.Management.Automation.ValidateNotNullOrEmptyAttribute - - - - - - - - - - false - - - Get-NTFSAudit - - - - - - - - - - - - - - - - Get-NTFSAudit [-Account <IdentityReference2>] [-ExcludeExplicit] [-ExcludeInherited] [-InformationAction <ActionPreference>] [-InformationVariable <String>] - - - - Account - - System.Management.Automation.ParameterAttribute - System.Management.Automation.AliasAttribute - System.Management.Automation.ValidateNotNullOrEmptyAttribute - - - IdentityReference, ID - - - - - - ExcludeExplicit - - System.Management.Automation.ParameterAttribute - - - - - - - ExcludeInherited - - System.Management.Automation.ParameterAttribute - - - - - - - InformationAction - - System.Management.Automation.AliasAttribute - System.Management.Automation.ParameterAttribute - - - infa - - - - - - InformationVariable - - System.Management.Automation.ParameterAttribute - System.Management.Automation.Internal.CommonParameters+ValidateVariableName - System.Management.Automation.AliasAttribute - - - iv - - - - - - - - - false - - - Get-NTFSEffectiveAccess - - - - - - - - - - - - - - - - - Get-NTFSEffectiveAccess [[-Path] <String[]>] [[-Account] <IdentityReference2>] [-ServerName <String>] [-ExcludeNoneAccessEntries] [-InformationAction <ActionPreference>] [-InformationVariable <String>] - Get-NTFSEffectiveAccess [-SecurityDescriptor] <FileSystemSecurity2[]> [[-Account] <IdentityReference2>] [-ServerName <String>] [-ExcludeNoneAccessEntries] [-InformationAction <ActionPreference>] [-InformationVariable <String>] - - - - Path - - System.Management.Automation.ParameterAttribute - System.Management.Automation.ValidateNotNullOrEmptyAttribute - System.Management.Automation.AliasAttribute - - - FullName - - - - - - Account - - System.Management.Automation.ParameterAttribute - System.Management.Automation.AliasAttribute - System.Management.Automation.ValidateNotNullOrEmptyAttribute - - - NTAccount - IdentityReference - - - - - - ServerName - - System.Management.Automation.ParameterAttribute - - - - - - - ExcludeNoneAccessEntries - - System.Management.Automation.ParameterAttribute - - - - - - - InformationAction - - System.Management.Automation.AliasAttribute - System.Management.Automation.ParameterAttribute - - - infa - - - - - - InformationVariable - - System.Management.Automation.ParameterAttribute - System.Management.Automation.Internal.CommonParameters+ValidateVariableName - System.Management.Automation.AliasAttribute - - - iv - - - - - - SecurityDescriptor - - System.Management.Automation.ParameterAttribute - System.Management.Automation.ValidateNotNullOrEmptyAttribute - - - - - - - - - - false - - - Get-NTFSInheritance - - - - - - - - - - - - - - - - - Get-NTFSInheritance [[-Path] <String[]>] [-InformationAction <ActionPreference>] [-InformationVariable <String>] - Get-NTFSInheritance [-SecurityDescriptor] <FileSystemSecurity2[]> [-InformationAction <ActionPreference>] [-InformationVariable <String>] - - - - Path - - System.Management.Automation.ParameterAttribute - System.Management.Automation.ValidateNotNullOrEmptyAttribute - System.Management.Automation.AliasAttribute - - - FullName - - - - - - InformationAction - - System.Management.Automation.AliasAttribute - System.Management.Automation.ParameterAttribute - - - infa - - - - - - InformationVariable - - System.Management.Automation.ParameterAttribute - System.Management.Automation.Internal.CommonParameters+ValidateVariableName - System.Management.Automation.AliasAttribute - - - iv - - - - - - SecurityDescriptor - - System.Management.Automation.ParameterAttribute - System.Management.Automation.ValidateNotNullOrEmptyAttribute - - - - - - - - - - false - - - Get-NTFSOrphanedAccess - - - - - - - - - - - - - - - - - Get-NTFSOrphanedAccess [[-Path] <String[]>] [-Account <IdentityReference2>] [-ExcludeExplicit] [-ExcludeInherited] [-InformationAction <ActionPreference>] [-InformationVariable <String>] - Get-NTFSOrphanedAccess [-SecurityDescriptor] <FileSystemSecurity2[]> [-Account <IdentityReference2>] [-ExcludeExplicit] [-ExcludeInherited] [-InformationAction <ActionPreference>] [-InformationVariable <String>] - - - - Path - - System.Management.Automation.ParameterAttribute - System.Management.Automation.ValidateNotNullOrEmptyAttribute - System.Management.Automation.AliasAttribute - - - FullName - - - - - - Account - - System.Management.Automation.ParameterAttribute - System.Management.Automation.AliasAttribute - System.Management.Automation.ValidateNotNullOrEmptyAttribute - - - IdentityReference, ID - - - - - - ExcludeExplicit - - System.Management.Automation.ParameterAttribute - - - - - - - ExcludeInherited - - System.Management.Automation.ParameterAttribute - - - - - - - InformationAction - - System.Management.Automation.AliasAttribute - System.Management.Automation.ParameterAttribute - - - infa - - - - - - InformationVariable - - System.Management.Automation.ParameterAttribute - System.Management.Automation.Internal.CommonParameters+ValidateVariableName - System.Management.Automation.AliasAttribute - - - iv - - - - - - SecurityDescriptor - - System.Management.Automation.ParameterAttribute - System.Management.Automation.ValidateNotNullOrEmptyAttribute - - - - - - - - - - false - - - Get-NTFSOrphanedAudit - - - - - - - - - - - - - - - - Get-NTFSOrphanedAudit [-Account <IdentityReference2>] [-ExcludeExplicit] [-ExcludeInherited] [-InformationAction <ActionPreference>] [-InformationVariable <String>] - - - - Account - - System.Management.Automation.ParameterAttribute - System.Management.Automation.AliasAttribute - System.Management.Automation.ValidateNotNullOrEmptyAttribute - - - IdentityReference, ID - - - - - - ExcludeExplicit - - System.Management.Automation.ParameterAttribute - - - - - - - ExcludeInherited - - System.Management.Automation.ParameterAttribute - - - - - - - InformationAction - - System.Management.Automation.AliasAttribute - System.Management.Automation.ParameterAttribute - - - infa - - - - - - InformationVariable - - System.Management.Automation.ParameterAttribute - System.Management.Automation.Internal.CommonParameters+ValidateVariableName - System.Management.Automation.AliasAttribute - - - iv - - - - - - - - - false - - - Get-NTFSOwner - - - - - - - - - - - - - - - - - Get-NTFSOwner [[-Path] <String[]>] [-InformationAction <ActionPreference>] [-InformationVariable <String>] - Get-NTFSOwner [-SecurityDescriptor] <FileSystemSecurity2[]> [-InformationAction <ActionPreference>] [-InformationVariable <String>] - - - - Path - - System.Management.Automation.ParameterAttribute - System.Management.Automation.ValidateNotNullOrEmptyAttribute - System.Management.Automation.AliasAttribute - - - FullName - - - - - - InformationAction - - System.Management.Automation.AliasAttribute - System.Management.Automation.ParameterAttribute - - - infa - - - - - - InformationVariable - - System.Management.Automation.ParameterAttribute - System.Management.Automation.Internal.CommonParameters+ValidateVariableName - System.Management.Automation.AliasAttribute - - - iv - - - - - - SecurityDescriptor - - System.Management.Automation.ParameterAttribute - System.Management.Automation.ValidateNotNullOrEmptyAttribute - - - - - - - - - - false - - - Get-NTFSSecurityDescriptor - - - - - - - - - - - - - - - - Get-NTFSSecurityDescriptor [[-Path] <String[]>] [-InformationAction <ActionPreference>] [-InformationVariable <String>] - - - - Path - - System.Management.Automation.ParameterAttribute - System.Management.Automation.ValidateNotNullOrEmptyAttribute - System.Management.Automation.AliasAttribute - - - FullName - - - - - - InformationAction - - System.Management.Automation.AliasAttribute - System.Management.Automation.ParameterAttribute - - - infa - - - - - - InformationVariable - - System.Management.Automation.ParameterAttribute - System.Management.Automation.Internal.CommonParameters+ValidateVariableName - System.Management.Automation.AliasAttribute - - - iv - - - - - - - - - false - - - Get-Privileges - - - - - - - - - - - - - - - - Get-Privileges [-InformationAction <ActionPreference>] [-InformationVariable <String>] - - - - InformationAction - - System.Management.Automation.AliasAttribute - System.Management.Automation.ParameterAttribute - - - infa - - - - - - InformationVariable - - System.Management.Automation.ParameterAttribute - System.Management.Automation.Internal.CommonParameters+ValidateVariableName - System.Management.Automation.AliasAttribute - - - iv - - - - - - - - - false - - - Get-SimpleAccess - - - - - - - - - - - - - - - - - Get-SimpleAccess [-IncludeRootFolder] [[-Path] <String[]>] [-Account <IdentityReference2>] [-ExcludeExplicit] [-ExcludeInherited] [-InformationAction <ActionPreference>] [-InformationVariable <String>] - Get-SimpleAccess [-IncludeRootFolder] [-SecurityDescriptor] <FileSystemSecurity2[]> [-Account <IdentityReference2>] [-ExcludeExplicit] [-ExcludeInherited] [-InformationAction <ActionPreference>] [-InformationVariable <String>] - - - - IncludeRootFolder - - System.Management.Automation.ParameterAttribute - - - - - - - Path - - System.Management.Automation.ParameterAttribute - System.Management.Automation.ValidateNotNullOrEmptyAttribute - System.Management.Automation.AliasAttribute - - - FullName - - - - - - Account - - System.Management.Automation.ParameterAttribute - System.Management.Automation.AliasAttribute - System.Management.Automation.ValidateNotNullOrEmptyAttribute - - - IdentityReference, ID - - - - - - ExcludeExplicit - - System.Management.Automation.ParameterAttribute - - - - - - - ExcludeInherited - - System.Management.Automation.ParameterAttribute - - - - - - - InformationAction - - System.Management.Automation.AliasAttribute - System.Management.Automation.ParameterAttribute - - - infa - - - - - - InformationVariable - - System.Management.Automation.ParameterAttribute - System.Management.Automation.Internal.CommonParameters+ValidateVariableName - System.Management.Automation.AliasAttribute - - - iv - - - - - - SecurityDescriptor - - System.Management.Automation.ParameterAttribute - System.Management.Automation.ValidateNotNullOrEmptyAttribute - - - - - - - - - - false - - - Remove-Item2 - - - - - - - - - - - - - - - - Remove-Item2 [[-Path] <String[]>] [-Force] [-Recurse] [-InformationAction <ActionPreference>] [-InformationVariable <String>] - - - - Path - - System.Management.Automation.ParameterAttribute - System.Management.Automation.ValidateNotNullOrEmptyAttribute - System.Management.Automation.AliasAttribute - - - FullName - - - - - - Force - - System.Management.Automation.ParameterAttribute - - - - - - - Recurse - - System.Management.Automation.ParameterAttribute - - - - - - - InformationAction - - System.Management.Automation.AliasAttribute - System.Management.Automation.ParameterAttribute - - - infa - - - - - - InformationVariable - - System.Management.Automation.ParameterAttribute - System.Management.Automation.Internal.CommonParameters+ValidateVariableName - System.Management.Automation.AliasAttribute - - - iv - - - - - - - - - false - - - Remove-NTFSAccess - - - - - - - - - - - - - - - - - - - Remove-NTFSAccess [-Path] <String[]> [-Account] <IdentityReference2[]> [-AccessRights] <FileSystemRights2> [-AccessType <AccessControlType>] [-InheritanceFlags <InheritanceFlags>] [-PropagationFlags <PropagationFlags>] [-PassThru] [-InformationAction <ActionPreference>] [-InformationVariable <String>] - Remove-NTFSAccess [-Path] <String[]> [-Account] <IdentityReference2[]> [-AccessRights] <FileSystemRights2> [-AccessType <AccessControlType>] [-AppliesTo <ApplyTo>] [-PassThru] [-InformationAction <ActionPreference>] [-InformationVariable <String>] - Remove-NTFSAccess [-SecurityDescriptor] <FileSystemSecurity2[]> [-Account] <IdentityReference2[]> [-AccessRights] <FileSystemRights2> [-AccessType <AccessControlType>] [-AppliesTo <ApplyTo>] [-PassThru] [-InformationAction <ActionPreference>] [-InformationVariable <String>] - Remove-NTFSAccess [-SecurityDescriptor] <FileSystemSecurity2[]> [-Account] <IdentityReference2[]> [-AccessRights] <FileSystemRights2> [-AccessType <AccessControlType>] [-InheritanceFlags <InheritanceFlags>] [-PropagationFlags <PropagationFlags>] [-PassThru] [-InformationAction <ActionPreference>] [-InformationVariable <String>] - - - - Path - - System.Management.Automation.ParameterAttribute - System.Management.Automation.ParameterAttribute - System.Management.Automation.ValidateNotNullOrEmptyAttribute - System.Management.Automation.AliasAttribute - - - FullName - - - - - - Account - - System.Management.Automation.ParameterAttribute - System.Management.Automation.AliasAttribute - - - IdentityReference, ID - - - - - - AccessRights - - System.Management.Automation.ParameterAttribute - System.Management.Automation.AliasAttribute - - - FileSystemRights - - - - - - AccessType - - System.Management.Automation.ParameterAttribute - System.Management.Automation.AliasAttribute - - - AccessControlType - - - - - - InheritanceFlags - - System.Management.Automation.ParameterAttribute - System.Management.Automation.ParameterAttribute - - - - - - - PropagationFlags - - System.Management.Automation.ParameterAttribute - System.Management.Automation.ParameterAttribute - - - - - - - PassThru - - System.Management.Automation.ParameterAttribute - - - - - - - InformationAction - - System.Management.Automation.AliasAttribute - System.Management.Automation.ParameterAttribute - - - infa - - - - - - InformationVariable - - System.Management.Automation.ParameterAttribute - System.Management.Automation.Internal.CommonParameters+ValidateVariableName - System.Management.Automation.AliasAttribute - - - iv - - - - - - AppliesTo - - System.Management.Automation.ParameterAttribute - System.Management.Automation.ParameterAttribute - - - - - - - SecurityDescriptor - - System.Management.Automation.ParameterAttribute - System.Management.Automation.ParameterAttribute - System.Management.Automation.ValidateNotNullOrEmptyAttribute - - - - - - - - - - false - - - Remove-NTFSAudit - - - - - - - - - - - - - - - - - Remove-NTFSAudit [-Account] <IdentityReference2> [-AccessRights] <FileSystemRights2> [-Type <AuditFlags>] [-InheritanceFlags <InheritanceFlags>] [-PropagationFlags <PropagationFlags>] [-PassThru] [-InformationAction <ActionPreference>] [-InformationVariable <String>] - Remove-NTFSAudit [-Account] <IdentityReference2> [-AccessRights] <FileSystemRights2> [-Type <AuditFlags>] [-AppliesTo <ApplyTo>] [-PassThru] [-InformationAction <ActionPreference>] [-InformationVariable <String>] - - - - Account - - System.Management.Automation.ParameterAttribute - System.Management.Automation.AliasAttribute - - - IdentityReference, ID - - - - - - AccessRights - - System.Management.Automation.ParameterAttribute - System.Management.Automation.AliasAttribute - - - FileSystemRights - - - - - - Type - - System.Management.Automation.ParameterAttribute - System.Management.Automation.AliasAttribute - - - AuditFlags - - - - - - InheritanceFlags - - System.Management.Automation.ParameterAttribute - - - - - - - PropagationFlags - - System.Management.Automation.ParameterAttribute - - - - - - - PassThru - - System.Management.Automation.ParameterAttribute - - - - - - - InformationAction - - System.Management.Automation.AliasAttribute - System.Management.Automation.ParameterAttribute - - - infa - - - - - - InformationVariable - - System.Management.Automation.ParameterAttribute - System.Management.Automation.Internal.CommonParameters+ValidateVariableName - System.Management.Automation.AliasAttribute - - - iv - - - - - - AppliesTo - - System.Management.Automation.ParameterAttribute - - - - - - - - - - false - - - Set-NTFSOwner - - - - - - - - - - - - - - - - - Set-NTFSOwner [[-Path] <String[]>] [-Account] <IdentityReference2> [-PassThru] [-InformationAction <ActionPreference>] [-InformationVariable <String>] - Set-NTFSOwner [-SecurityDescriptor] <FileSystemSecurity2[]> [-Account] <IdentityReference2> [-PassThru] [-InformationAction <ActionPreference>] [-InformationVariable <String>] - - - - Path - - System.Management.Automation.ParameterAttribute - System.Management.Automation.ValidateNotNullOrEmptyAttribute - System.Management.Automation.AliasAttribute - - - FullName - - - - - - Account - - System.Management.Automation.ParameterAttribute - - - - - - - PassThru - - System.Management.Automation.ParameterAttribute - - - - - - - InformationAction - - System.Management.Automation.AliasAttribute - System.Management.Automation.ParameterAttribute - - - infa - - - - - - InformationVariable - - System.Management.Automation.ParameterAttribute - System.Management.Automation.Internal.CommonParameters+ValidateVariableName - System.Management.Automation.AliasAttribute - - - iv - - - - - - SecurityDescriptor - - System.Management.Automation.ParameterAttribute - System.Management.Automation.ValidateNotNullOrEmptyAttribute - - - - - - - - - - false - - - Set-NTFSSecurityDescriptor - - - - - - - - - - - - - - - - Set-NTFSSecurityDescriptor [-SecurityDescriptor] <FileSystemSecurity2[]> [-PassThru] [-InformationAction <ActionPreference>] [-InformationVariable <String>] - - - - SecurityDescriptor - - System.Management.Automation.ParameterAttribute - - - - - - - PassThru - - System.Management.Automation.ParameterAttribute - - - - - - - InformationAction - - System.Management.Automation.AliasAttribute - System.Management.Automation.ParameterAttribute - - - infa - - - - - - InformationVariable - - System.Management.Automation.ParameterAttribute - System.Management.Automation.Internal.CommonParameters+ValidateVariableName - System.Management.Automation.AliasAttribute - - - iv - - - - - - - - - false - - - Show-SimpleAccess - - - - - - - - - - - - - - - - - Show-SimpleAccess [-IncludeRootFolder] [[-Path] <String[]>] [-Account <IdentityReference2>] [-ExcludeExplicit] [-ExcludeInherited] [-InformationAction <ActionPreference>] [-InformationVariable <String>] - Show-SimpleAccess [-IncludeRootFolder] [-SecurityDescriptor] <FileSystemSecurity2[]> [-Account <IdentityReference2>] [-ExcludeExplicit] [-ExcludeInherited] [-InformationAction <ActionPreference>] [-InformationVariable <String>] - - - - IncludeRootFolder - - System.Management.Automation.ParameterAttribute - - - - - - - Path - - System.Management.Automation.ParameterAttribute - System.Management.Automation.ValidateNotNullOrEmptyAttribute - System.Management.Automation.AliasAttribute - - - FullName - - - - - - Account - - System.Management.Automation.ParameterAttribute - System.Management.Automation.AliasAttribute - System.Management.Automation.ValidateNotNullOrEmptyAttribute - - - IdentityReference, ID - - - - - - ExcludeExplicit - - System.Management.Automation.ParameterAttribute - - - - - - - ExcludeInherited - - System.Management.Automation.ParameterAttribute - - - - - - - InformationAction - - System.Management.Automation.AliasAttribute - System.Management.Automation.ParameterAttribute - - - infa - - - - - - InformationVariable - - System.Management.Automation.ParameterAttribute - System.Management.Automation.Internal.CommonParameters+ValidateVariableName - System.Management.Automation.AliasAttribute - - - iv - - - - - - SecurityDescriptor - - System.Management.Automation.ParameterAttribute - System.Management.Automation.ValidateNotNullOrEmptyAttribute - - - - - - - - - - false - - - \ No newline at end of file diff --git a/NTFSSecurity/NTFSSecurity-Help.xml b/NTFSSecurity/NTFSSecurity-Help.xml deleted file mode 100644 index 573972c..0000000 --- a/NTFSSecurity/NTFSSecurity-Help.xml +++ /dev/null @@ -1,2333 +0,0 @@ - - - - - - - - Add-Access - - Add permission to the ACL of a file or folder. - - - - - - Add - Access - - - - - - The function adds an ACE to the item's ACL. The cmdlet needs to have the following information for that: - - Path - - Account (SamAccountName or SID) - - AccessRights (Read, Change, FullControl, etc., ...) - - AccessType (Allow or Deny) - - - -(This folder only, Only files, etc.) - -All the options are explained in the parameter section. - -The function needs to know the file or folder path. The path can be an argument or be piped into the function as string or FileSystemInfo object (result of Get-ChildItem or Get-Item). - - - Add-Access - - Account - - Takes the account that is will be granted permission. This can either be a SID (well known, domain or local) or a account name. The account name must be specified in the syntax 'Domain\UserName'. Well known accounts are not part of the domain or local machine. Use for example 'NT Authority\System' or 'Builtin\Administrators'. - - IdentityReference2 - - - AccessRights - - The right the account shall get. This parameter is of the type System.Security.AccessControl.FileSystemRights so the following values are valid: ListDirectory, ReadData, WriteData, CreateFiles, CreateDirectories, AppendData, ReadExtendedAttributes, WriteExtendedAttributes, Traverse, ExecuteFile,DeleteSubdirectoriesAndFiles, ReadAttributes, WriteAttributes, Write, Delete, ReadPermissions, Read, ReadAndExecute, Modify, ChangePermissions, TakeOwnership, Synchronize, FullControl - - FileSystemRights - - - AccessType - - The type of access you want to give, either Allow or Deny (System.Security.AccessControl.AccessControlType). - - AccessControlType - - - InheritanceFlags - - Defines what child items are going to inherit in terms of permissions. If not defined, permissions will be inherited by files and folders (ContainerInherit | ObjectInherit) - -There are three options: -- None: The permission will not be inherited by any child item -- ContainerInherit: The permission will be inherited only by directories -- ObjectInherit: The permission will be inherited only by files - - InheritanceFlags - - - PropagationFlags - - Specifies how Access Control Entries (ACEs) are propagated to child objects. - -There are three options: -- None: Specifies that no propagation flags are set. -- NoPropagateInherit: Specifies that the ACE is not propagated to child objects. -- InheritOnly: Specifies that the ACE is propagated only to child objects. This includes both container and leaf child objects. - - PropagationFlags - - - PassThru - - Returns the item's access control list by using FileSystemAccessRule2. item's ACE. By default, this cmdlet does not generate any output. - - - - Path - - Specifies the path to a resource. Add-Access adds permissions to the items indicated by the path. Wildcards are not permitted. This parameter accepts input from the pipeline so combining Get-Access with Get-ChildItem or Get-Item is the easiest way if you want to process multiple files or folders. - - String[] - - - - Add-Access - - Account - - Takes the account that is will be granted permission. This can either be a SID (well known, domain or local) or a account name. The account name must be specified in the syntax 'Domain\UserName'. Well known accounts are not part of the domain or local machine. Use for example 'NT Authority\System' or 'Builtin\Administrators'. - - IdentityReference2 - - - AccessRights - - The right the account shall get. This parameter is of the type System.Security.AccessControl.FileSystemRights so the following values are valid: ListDirectory, ReadData, WriteData, CreateFiles, CreateDirectories, AppendData, ReadExtendedAttributes, WriteExtendedAttributes, Traverse, ExecuteFile,DeleteSubdirectoriesAndFiles, ReadAttributes, WriteAttributes, Write, Delete, ReadPermissions, Read, ReadAndExecute, Modify, ChangePermissions, TakeOwnership, Synchronize, FullControl - - FileSystemRights - - - AccessType - - The type of access you want to give, either Allow or Deny (System.Security.AccessControl.AccessControlType). - - AccessControlType - - - AppliesTo - - This parameter controls inheritance and propagation like the "Apply To" drop-down box in the Windows Explorer dialog. The allowed options are: -- ThisFolderOnly -- ThisFolderSubfolderAndFiles -- ThisFolderAndSubfolders -- ThisFolderAndFiles -- SubfolderAndFilesOnly -- SubfolersOnly -- FilesOnly - - ApplyTo - - - PassThru - - Returns the item's access control list by using FileSystemAccessRule2. item's ACE. By default, this cmdlet does not generate any output. - - - - Path - - Specifies the path to a resource. Add-Access adds permissions to the items indicated by the path. Wildcards are not permitted. This parameter accepts input from the pipeline so combining Get-Access with Get-ChildItem or Get-Item is the easiest way if you want to process multiple files or folders. - - String[] - - - - - - Account - - Takes the account that is will be granted permission. This can either be a SID (well known, domain or local) or a account name. The account name must be specified in the syntax 'Domain\UserName'. Well known accounts are not part of the domain or local machine. Use for example 'NT Authority\System' or 'Builtin\Administrators'. - - IdentityReference2 - - IdentityReference2 - - - - - - AccessRights - - The right the account shall get. This parameter is of the type System.Security.AccessControl.FileSystemRights so the following values are valid: ListDirectory, ReadData, WriteData, CreateFiles, CreateDirectories, AppendData, ReadExtendedAttributes, WriteExtendedAttributes, Traverse, ExecuteFile,DeleteSubdirectoriesAndFiles, ReadAttributes, WriteAttributes, Write, Delete, ReadPermissions, Read, ReadAndExecute, Modify, ChangePermissions, TakeOwnership, Synchronize, FullControl - - FileSystemRights - - FileSystemRights - - - - - - AccessType - - The type of access you want to give, either Allow or Deny (System.Security.AccessControl.AccessControlType). - - AccessControlType - - AccessControlType - - - - - - InheritanceFlags - - Defines what child items are going to inherit in terms of permissions. If not defined, permissions will be inherited by files and folders (ContainerInherit | ObjectInherit) - -There are three options: -- None: The permission will not be inherited by any child item -- ContainerInherit: The permission will be inherited only by directories -- ObjectInherit: The permission will be inherited only by files - - InheritanceFlags - - InheritanceFlags - - - - - - PropagationFlags - - Specifies how Access Control Entries (ACEs) are propagated to child objects. - -There are three options: -- None: Specifies that no propagation flags are set. -- NoPropagateInherit: Specifies that the ACE is not propagated to child objects. -- InheritOnly: Specifies that the ACE is propagated only to child objects. This includes both container and leaf child objects. - - PropagationFlags - - PropagationFlags - - - - - - PassThru - - Returns the item's access control list by using FileSystemAccessRule2. item's ACE. By default, this cmdlet does not generate any output. - - - SwitchParameter - - - - - - Path - - Specifies the path to a resource. Add-Access adds permissions to the items indicated by the path. Wildcards are not permitted. This parameter accepts input from the pipeline so combining Get-Access with Get-ChildItem or Get-Item is the easiest way if you want to process multiple files or folders. - - String[] - - String[] - - - - - - AppliesTo - - This parameter controls inheritance and propagation like the "Apply To" drop-down box in the Windows Explorer dialog. The allowed options are: -- ThisFolderOnly -- ThisFolderSubfolderAndFiles -- ThisFolderAndSubfolders -- ThisFolderAndFiles -- SubfolderAndFilesOnly -- SubfolersOnly -- FilesOnly - - ApplyTo - - ApplyTo - - - - - - - - - FileSystemInfo or Strings - - - All parameters accept pipeline input. - - - - - - - - - Null, unless the parameter PassThru is used. - - - Security2.FileSystemAccessRule2 for each ACE on the object, if PassThru is used. - - - - - - - - - - - - - - - - - - --------------- EXAMPLE 1 -------------- - - C:\PS> -C:\PS> - PS C:\> dir | Add-Ace -Account forest3\test -AccessRights Read -PassThru - - Add read permissions to the test user account. Per default the inheritance is set to files and folders. - - - Path: C:\data\Test (Inheritance enabled) - - Identity Rights Inheritance Type IsInherited - -------- ------ ----------- ---- ----------- - raandree1\Test (S-1-5-21-30... FullControl ContainerInherit,... Allow False - - - - - - - - - - - - --------------- EXAMPLE 2 -------------- - - C:\PS> -C:\PS> - PS C:\data> dir | Add-Ace -Account raandree1\test -AccessRights Read -AppliesTo ThisFolderOnly -PassThru - - Adds read access to the test account to all items the 'dir' command returns without inheriting the access to files or folder below. - - - Path: C:\data\Test (Inheritance enabled) - - Identity Rights Inheritance Type IsInherited - -------- ------ ----------- ---- ----------- - raandree1\Test (S-1-5-21-30... Read, Synchronize None Allow False - - Path: C:\data\File1.txt (Inheritance enabled) - - Identity Rights Inheritance Type IsInherited - -------- ------ ----------- ---- ----------- - raandree1\Test (S-1-5-21-30... Read, Synchronize None Allow False - - - - - - - - - - - - - - http://gallery.technet.microsoft.com/scriptcenter/1abd77a5-9c0b-4a2b-acef-90dbb2b84e85 - - - - - - - - Copy-Access - - - - - - - - Copy - Access - - - - - - - - - Copy-Access - - Path - - - - String - - - DestinationPath - - - - String - - - Account - - - - IdentityReference2 - - - AccessType - - - - AccessControlType - - - PassThru - - - - - - - - - Path - - - - String - - String - - - - - - DestinationPath - - - - String - - String - - - - - - Account - - - - IdentityReference2 - - IdentityReference2 - - - - - - AccessType - - - - AccessControlType - - AccessControlType - - - - - - PassThru - - - - - SwitchParameter - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Disable-Inheritance - - - - - - - - Disable - Inheritance - - - - - - - - - Disable-Inheritance - - PassThru - - - - - - PreserveInheritedAccessRules - - - - - - Path - - - - String[] - - - - - - PassThru - - - - - SwitchParameter - - - - - - PreserveInheritedAccessRules - - - - - SwitchParameter - - - - - - Path - - - - String[] - - String[] - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Enable-Inheritance - - - - - - - - Enable - Inheritance - - - - - - - - - Enable-Inheritance - - PassThru - - - - - - RemoveInheritedAccessRules - - - - - - Path - - - - String[] - - - - - - PassThru - - - - - SwitchParameter - - - - - - RemoveInheritedAccessRules - - - - - SwitchParameter - - - - - - Path - - - - String[] - - String[] - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Get-Access - - Gets all Access Control Entries in the item's Discretionary Access Control List. - - - - - - Get - Access - - - - - - The function returns all ACEs defined on the item. You can filter the ACEs using the switches ExcludeExplicit and ExcludeInherited. - -Whether the item inherits the permissions from its parent is indicated in the output as well. - -The function needs to know the file or folder path. The path can be an argument or be piped into the function as string or FileSystemInfo object (result of Get-ChildItem or Get-Item). - - - Get-Access - - Account - - Takes the account that is used to filter the output. Only ACEs are shown that match the given user account. - -This can either be a SID (well known, domain or local) or a account name. The account name must be specified in the syntax 'Domain\UserName'. Well known accounts are not part of the domain or local machine. Use for example 'NT Authority\System' or 'Builtin\Administrators'. - - IdentityReference2 - - - ExcludeExplicit - - If set, only inherited ACEs are returned. - - - - ExcludeInherited - - If set, only explicitly non-inherited ACEs are returned. - - - - Path - - Specifies the path to the resource. Get-Access gets the permissions of the items indicated by the path. Wildcards are not permitted. This parameter also accepts input from the pipeline so combining Get-Access with Get-ChildItem or Get-Item is the easiest way if you want to get the access rights of multiple files and folders. - - String[] - - - - - - Account - - Takes the account that is used to filter the output. Only ACEs are shown that match the given user account. - -This can either be a SID (well known, domain or local) or a account name. The account name must be specified in the syntax 'Domain\UserName'. Well known accounts are not part of the domain or local machine. Use for example 'NT Authority\System' or 'Builtin\Administrators'. - - IdentityReference2 - - IdentityReference2 - - - - - - ExcludeExplicit - - If set, only inherited ACEs are returned. - - - SwitchParameter - - - - - - ExcludeInherited - - If set, only explicitly non-inherited ACEs are returned. - - - SwitchParameter - - - - - - Path - - Specifies the path to the resource. Get-Access gets the permissions of the items indicated by the path. Wildcards are not permitted. This parameter also accepts input from the pipeline so combining Get-Access with Get-ChildItem or Get-Item is the easiest way if you want to get the access rights of multiple files and folders. - - String[] - - String[] - - - - - - - - - System.String - - - You can pipe a string that contains a path. - - - - - - - - - Security2.FileSystemAccessRule2 - - - Get-Ace returns objects that represent the item's Access Control Entries. - - - - - - - - - - - - - - - - - - --------------- EXAMPLE 1 -------------- - - C:\PS> -C:\PS> - Get-Item c:\ | Get-Access - - Get all ACEs defined on the root of drive C: - - - Path: C:\ (Inheritance disabled) - - Identity Rights Inheritance Type IsInherited - -------- ------ ----------- ---- ----------- - NT AUTHORITY\Authenticated ... AppendData None Allow False - NT AUTHORITY\Authenticated ... -536805376 ContainerIn... Allow False - NT AUTHORITY\SYSTEM (S-1-5-18) FullControl None Allow False - NT AUTHORITY\SYSTEM (S-1-5-18) 268435456 ContainerIn... Allow False - BUILTIN\Administrators (S-1... 268435456 ContainerIn... Allow False - BUILTIN\Administrators (S-1... FullControl None Allow False - BUILTIN\Users (S-1-5-32-545) ReadAndExec... ContainerIn... Allow False - - - - - - - - - - - - --------------- EXAMPLE 2 -------------- - - C:\PS> -C:\PS> - PS C:\> dir | Where-Object { $_.PSIsContainer } | Get-Ace -ExcludeInherited - - This command returns only explicitly set ACEs on all folders. - - - - - - - - - - - - - - - --------------- EXMAPLE 3 -------------- - - C:\PS> -C:\PS> - PS C:\> dir | Get-Access -Account Builtin\Users - - This command returns all Access Control Entries whose account match 'Builtin\Users'. - - - Path: C:\Users\raandree\Desktop\ADRAP.docx (Inheritance disabled) - - -Account Access Rights Applies to Type IsInherited -------- ------------- ---------- ---- ----------- -BUILTIN\Users (S-1-5-32-545) Modify, Synch... ThisFolderOnly Allow False - - - - - - - - - - - - - - http://gallery.technet.microsoft.com/scriptcenter/1abd77a5-9c0b-4a2b-acef-90dbb2b84e85 - - - - - - - - Get-EffectiveAccess - - - - - - - - Get - EffectiveAccess - - - - - - - - - Get-EffectiveAccess - - Account - - - - IdentityReference2 - - - Path - - - - String[] - - - - - - Account - - - - IdentityReference2 - - IdentityReference2 - - - - - - Path - - - - String[] - - String[] - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Get-Inheritance - - - - - - - - Get - Inheritance - - - - - - - - - Get-Inheritance - - Path - - - - String[] - - - - - - Path - - - - String[] - - String[] - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Get-OrphanedAccess - - - - - - - - Get - OrphanedAccess - - - - - - - - - Get-OrphanedAccess - - Account - - - - IdentityReference2 - - - ExcludeExplicit - - - - - - ExcludeInherited - - - - - - Path - - - - String[] - - - - - - Account - - - - IdentityReference2 - - IdentityReference2 - - - - - - ExcludeExplicit - - - - - SwitchParameter - - - - - - ExcludeInherited - - - - - SwitchParameter - - - - - - Path - - - - String[] - - String[] - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Get-Owner - - - - - - - - Get - Owner - - - - - - - - - Get-Owner - - Path - - - - String[] - - - - - - Path - - - - String[] - - String[] - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Get-SimpleAccess - - - - - - - - Get - SimpleAccess - - - - - - - - - Get-SimpleAccess - - IncludeRootFolder - - - - - - Account - - - - IdentityReference2 - - - ExcludeExplicit - - - - - - ExcludeInherited - - - - - - Path - - - - String[] - - - - - - IncludeRootFolder - - - - - SwitchParameter - - - - - - Account - - - - IdentityReference2 - - IdentityReference2 - - - - - - ExcludeExplicit - - - - - SwitchParameter - - - - - - ExcludeInherited - - - - - SwitchParameter - - - - - - Path - - - - String[] - - String[] - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Get-SimpleEffectiveAccess - - - - - - - - Get - SimpleEffectiveAccess - - - - - - - - - Get-SimpleEffectiveAccess - - IncludeRootFolder - - - - - - Account - - - - IdentityReference2 - - - Path - - - - String[] - - - - - - IncludeRootFolder - - - - - SwitchParameter - - - - - - Account - - - - IdentityReference2 - - IdentityReference2 - - - - - - Path - - - - String[] - - String[] - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Remove-Access - - - - - - - - Remove - Access - - - - - - - - - Remove-Access - - Account - - - - IdentityReference2 - - - AccessRights - - - - FileSystemRights - - - AccessType - - - - AccessControlType - - - InheritanceFlags - - - - InheritanceFlags - - - PropagationFlags - - - - PropagationFlags - - - PassThru - - - - - - Path - - - - String[] - - - - Remove-Access - - Account - - - - IdentityReference2 - - - AccessRights - - - - FileSystemRights - - - AccessType - - - - AccessControlType - - - AppliesTo - - - - ApplyTo - - - PassThru - - - - - - Path - - - - String[] - - - - - - Account - - - - IdentityReference2 - - IdentityReference2 - - - - - - AccessRights - - - - FileSystemRights - - FileSystemRights - - - - - - AccessType - - - - AccessControlType - - AccessControlType - - - - - - InheritanceFlags - - - - InheritanceFlags - - InheritanceFlags - - - - - - PropagationFlags - - - - PropagationFlags - - PropagationFlags - - - - - - PassThru - - - - - SwitchParameter - - - - - - Path - - - - String[] - - String[] - - - - - - AppliesTo - - - - ApplyTo - - ApplyTo - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Set-Owner - - - - - - - - Set - Owner - - - - - - - - - Set-Owner - - Account - - - - IdentityReference2 - - - PassThru - - - - - - Recurse - - - - - - Path - - - - String[] - - - - - - Account - - - - IdentityReference2 - - IdentityReference2 - - - - - - PassThru - - - - - SwitchParameter - - - - - - Recurse - - - - - SwitchParameter - - - - - - Path - - - - String[] - - String[] - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Show-SimpleAccess - - - - - - - - Show - SimpleAccess - - - - - - - - - Show-SimpleAccess - - IncludeRootFolder - - - - - - Account - - - - IdentityReference2 - - - ExcludeExplicit - - - - - - ExcludeInherited - - - - - - Path - - - - String[] - - - - - - IncludeRootFolder - - - - - SwitchParameter - - - - - - Account - - - - IdentityReference2 - - IdentityReference2 - - - - - - ExcludeExplicit - - - - - SwitchParameter - - - - - - ExcludeInherited - - - - - SwitchParameter - - - - - - Path - - - - String[] - - String[] - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Show-SimpleEffectiveAccess - - - - - - - - Show - SimpleEffectiveAccess - - - - - - - - - Show-SimpleEffectiveAccess - - IncludeRootFolder - - - - - - Account - - - - IdentityReference2 - - - Path - - - - String[] - - - - - - IncludeRootFolder - - - - - SwitchParameter - - - - - - Account - - - - IdentityReference2 - - IdentityReference2 - - - - - - Path - - - - String[] - - String[] - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - diff --git a/NTFSSecurity/NTFSSecurity.csproj b/NTFSSecurity/NTFSSecurity.csproj index d5d189e..bed8c19 100644 --- a/NTFSSecurity/NTFSSecurity.csproj +++ b/NTFSSecurity/NTFSSecurity.csproj @@ -118,7 +118,6 @@ - PreserveNewest Designer @@ -144,7 +143,7 @@ - + PreserveNewest diff --git a/NTFSSecurity/NTFSSecurity.psd1 b/NTFSSecurity/NTFSSecurity.psd1 index ae6f91e..aa097ad 100644 --- a/NTFSSecurity/NTFSSecurity.psd1 +++ b/NTFSSecurity/NTFSSecurity.psd1 @@ -80,7 +80,19 @@ 'Get-DiskSpace', 'Get-FileHash2' - FileList = @('NTFSSecurity.dll', 'NTFSSecurity.types.ps1xml', 'NTFSSecurity.format.ps1xml', 'NTFSSecurity.Init.ps1', 'NTFSSecurity.psm1') + FileList = @( + 'NTFSSecurity.psd1' + 'NTFSSecurity.psm1' + 'NTFSSecurity.Init.ps1' + 'NTFSSecurity.dll' + 'Security2.dll' + 'PrivilegeControl.dll' + 'ProcessPrivileges.dll' + 'AlphaFS.dll' + 'NTFSSecurity.types.ps1xml' + 'NTFSSecurity.format.ps1xml' + 'en-US\NTFSSecurity.dll-Help.xml' + ) PrivateData = @{ EnablePrivileges = $true diff --git a/NTFSSecurity/en-US/NTFSSecurity.dll-Help.xml b/NTFSSecurity/en-US/NTFSSecurity.dll-Help.xml new file mode 100644 index 0000000..ecd6730 --- /dev/null +++ b/NTFSSecurity/en-US/NTFSSecurity.dll-Help.xml @@ -0,0 +1,10020 @@ + + + + + Add-NTFSAccess + Add + NTFSAccess + + Adds an access control entry (ACE) to a file, a folder, or a security descriptor. + + + + Adds an access control entry (ACE) to the discretionary access control list (DACL) of a file or a folder. Every account in `-Account` receives the rights in `-AccessRights`, either as an `Allow` or as a `Deny` entry. + `-AccessRights` accepts the basic rights such as `Read`, `Modify`, and `FullControl` as well as the granular rights such as `CreateFiles` or `WriteAttributes`, and several values can be combined, for example `-AccessRights ReadData, WriteData, Delete`. For the mapping between the values of this module, the rights that Windows displays, and the entries of the advanced security dialog, see Concepts (../Concepts.md). + The cmdlet has four parameter sets. The `Path` sets read the item from disk and write the changed DACL back immediately, while the `SD` sets change a `Security2.FileSystemSecurity2` object returned by `Get-NTFSSecurityDescriptor` in memory until `Set-NTFSSecurityDescriptor` writes it back. The `Simple` sets take `-AppliesTo`, the `Complex` sets take `-InheritanceFlags` and `-PropagationFlags`; both describe the same ACE flags, and `PathComplex` is the default. A command that works on a security descriptor, whether it is passed to `-SecurityDescriptor` or piped in, must therefore name `-AppliesTo` or `-InheritanceFlags` and `-PropagationFlags`; without one of them PowerShell cannot choose between the two `SD` sets and reports that the parameter set cannot be resolved. + When `-AccessType`, `-AppliesTo`, `-InheritanceFlags`, and `-PropagationFlags` are omitted, the cmdlet adds an `Allow` ACE that applies to this folder, subfolders, and files, which corresponds to the inheritance flags `ContainerInherit, ObjectInherit` and no propagation flags. An `Allow` ACE always receives the `Synchronize` right in addition to the requested rights, inheritance and propagation flags are ignored on files, and rights for an account that already has an ACE with the same access type and the same flags are merged into that ACE. The cmdlet writes no output unless `-PassThru` is used, and a failure on one item is reported as a non-terminating error while the remaining items are processed. + `-Path` accepts pipeline input by value and by property name through its alias `FullName`, so output of `Get-ChildItem`, `Get-ChildItem2`, and `Get-Item2` can be piped in. `-Account`, `-AccessRights`, `-AccessType`, `-InheritanceFlags`, and `-PropagationFlags` bind by property name as well, which lets you pipe `Security2.FileSystemAccessRule2` objects, or rows imported from a CSV file created from them, directly into the cmdlet. + + + + Add-NTFSAccess + + Path + + Specifies the path of one or more files or folders the ACE is added to. Relative paths are resolved against the current location. The parameter accepts pipeline input by value and by property name through its alias `FullName`. + + String[] + + String[] + + + None + + + Account + + Specifies one or more accounts or groups the ACE applies to. 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`. A name that cannot be translated into a SID raises an error, a SID that cannot be translated into a name is accepted. + + IdentityReference2[] + + IdentityReference2[] + + + None + + + AccessRights + + Specifies the rights the ACE grants or denies. The parameter accepts basic rights such as `Read`, `ReadAndExecute`, `Modify`, and `FullControl`, granular rights such as `CreateFiles`, `Traverse`, or `WriteAttributes`, and any combination of them. An `Allow` ACE always receives `Synchronize` in addition to the specified rights. For how the values relate to the Windows security dialog, see Concepts (../Concepts.md). + + + None + ReadData + ListDirectory + WriteData + CreateFiles + AppendData + CreateDirectories + ReadExtendedAttributes + WriteExtendedAttributes + ExecuteFile + Traverse + DeleteSubdirectoriesAndFiles + ReadAttributes + WriteAttributes + Write + Delete + ReadPermissions + Read + ReadAndExecute + Modify + ChangePermissions + TakeOwnership + Synchronize + FullControl + GenericAll + GenericExecute + GenericWrite + GenericRead + + FileSystemRights2 + + FileSystemRights2 + + + None + + + AccessType + + Specifies whether the ACE allows or denies the rights in `-AccessRights`. The default is `Allow`. A `Deny` ACE takes precedence over `Allow` ACEs that grant the same rights. + + + Allow + Deny + + AccessControlType + + AccessControlType + + + Allow + + + AppliesTo + + Specifies the scope of the ACE in the wording of the Windows security dialog, for example `ThisFolderOnly`, `ThisFolderAndSubfolders`, or `SubfoldersAndFilesOnly`. The default is `ThisFolderSubfoldersAndFiles`. The cmdlet translates the value into the equivalent inheritance and propagation flags, so this parameter and the pair `-InheritanceFlags` and `-PropagationFlags` are two ways to describe the same ACE. The values ending in `OneLevel` limit inheritance to the direct children of the folder. + + + ThisFolderOnly + ThisFolderSubfoldersAndFiles + ThisFolderAndSubfolders + ThisFolderAndFiles + SubfoldersAndFilesOnly + SubfoldersOnly + FilesOnly + ThisFolderSubfoldersAndFilesOneLevel + ThisFolderAndSubfoldersOneLevel + ThisFolderAndFilesOneLevel + SubfoldersAndFilesOnlyOneLevel + SubfoldersOnlyOneLevel + FilesOnlyOneLevel + + ApplyTo + + ApplyTo + + + ThisFolderSubfoldersAndFiles + + + PassThru + + Indicates that the cmdlet writes the access control entries of every processed item, explicit and inherited, after the change. Without this switch the cmdlet produces no output. + + + SwitchParameter + + + False + + + + Add-NTFSAccess + + SecurityDescriptor + + Specifies one or more `Security2.FileSystemSecurity2` objects, as returned by `Get-NTFSSecurityDescriptor`, that the ACE is added to. The change is made in memory only; use `Set-NTFSSecurityDescriptor` to write it to the file system. + 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. + + FileSystemSecurity2[] + + FileSystemSecurity2[] + + + None + + + Account + + Specifies one or more accounts or groups the ACE applies to. 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`. A name that cannot be translated into a SID raises an error, a SID that cannot be translated into a name is accepted. + + IdentityReference2[] + + IdentityReference2[] + + + None + + + AccessRights + + Specifies the rights the ACE grants or denies. The parameter accepts basic rights such as `Read`, `ReadAndExecute`, `Modify`, and `FullControl`, granular rights such as `CreateFiles`, `Traverse`, or `WriteAttributes`, and any combination of them. An `Allow` ACE always receives `Synchronize` in addition to the specified rights. For how the values relate to the Windows security dialog, see Concepts (../Concepts.md). + + + None + ReadData + ListDirectory + WriteData + CreateFiles + AppendData + CreateDirectories + ReadExtendedAttributes + WriteExtendedAttributes + ExecuteFile + Traverse + DeleteSubdirectoriesAndFiles + ReadAttributes + WriteAttributes + Write + Delete + ReadPermissions + Read + ReadAndExecute + Modify + ChangePermissions + TakeOwnership + Synchronize + FullControl + GenericAll + GenericExecute + GenericWrite + GenericRead + + FileSystemRights2 + + FileSystemRights2 + + + None + + + AccessType + + Specifies whether the ACE allows or denies the rights in `-AccessRights`. The default is `Allow`. A `Deny` ACE takes precedence over `Allow` ACEs that grant the same rights. + + + Allow + Deny + + AccessControlType + + AccessControlType + + + Allow + + + AppliesTo + + Specifies the scope of the ACE in the wording of the Windows security dialog, for example `ThisFolderOnly`, `ThisFolderAndSubfolders`, or `SubfoldersAndFilesOnly`. The default is `ThisFolderSubfoldersAndFiles`. The cmdlet translates the value into the equivalent inheritance and propagation flags, so this parameter and the pair `-InheritanceFlags` and `-PropagationFlags` are two ways to describe the same ACE. The values ending in `OneLevel` limit inheritance to the direct children of the folder. + + + ThisFolderOnly + ThisFolderSubfoldersAndFiles + ThisFolderAndSubfolders + ThisFolderAndFiles + SubfoldersAndFilesOnly + SubfoldersOnly + FilesOnly + ThisFolderSubfoldersAndFilesOneLevel + ThisFolderAndSubfoldersOneLevel + ThisFolderAndFilesOneLevel + SubfoldersAndFilesOnlyOneLevel + SubfoldersOnlyOneLevel + FilesOnlyOneLevel + + ApplyTo + + ApplyTo + + + ThisFolderSubfoldersAndFiles + + + PassThru + + Indicates that the cmdlet writes the access control entries of every processed item, explicit and inherited, after the change. Without this switch the cmdlet produces no output. + + + SwitchParameter + + + False + + + + Add-NTFSAccess + + Path + + Specifies the path of one or more files or folders the ACE is added to. Relative paths are resolved against the current location. The parameter accepts pipeline input by value and by property name through its alias `FullName`. + + String[] + + String[] + + + None + + + Account + + Specifies one or more accounts or groups the ACE applies to. 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`. A name that cannot be translated into a SID raises an error, a SID that cannot be translated into a name is accepted. + + IdentityReference2[] + + IdentityReference2[] + + + None + + + AccessRights + + Specifies the rights the ACE grants or denies. The parameter accepts basic rights such as `Read`, `ReadAndExecute`, `Modify`, and `FullControl`, granular rights such as `CreateFiles`, `Traverse`, or `WriteAttributes`, and any combination of them. An `Allow` ACE always receives `Synchronize` in addition to the specified rights. For how the values relate to the Windows security dialog, see Concepts (../Concepts.md). + + + None + ReadData + ListDirectory + WriteData + CreateFiles + AppendData + CreateDirectories + ReadExtendedAttributes + WriteExtendedAttributes + ExecuteFile + Traverse + DeleteSubdirectoriesAndFiles + ReadAttributes + WriteAttributes + Write + Delete + ReadPermissions + Read + ReadAndExecute + Modify + ChangePermissions + TakeOwnership + Synchronize + FullControl + GenericAll + GenericExecute + GenericWrite + GenericRead + + FileSystemRights2 + + FileSystemRights2 + + + None + + + AccessType + + Specifies whether the ACE allows or denies the rights in `-AccessRights`. The default is `Allow`. A `Deny` ACE takes precedence over `Allow` ACEs that grant the same rights. + + + Allow + Deny + + AccessControlType + + AccessControlType + + + Allow + + + InheritanceFlags + + Specifies which kind of child objects inherit the ACE. `ContainerInherit` passes the ACE on to child folders, `ObjectInherit` passes it on to child files, and `None` keeps the ACE on the item itself. The default is `ContainerInherit, ObjectInherit`. Inheritance flags have no effect on files, where the ACE is always created with `None`. + For details about the flags, see the .NET documentation of the InheritanceFlags Enum (https://learn.microsoft.com/en-us/dotnet/api/system.security.accesscontrol.inheritanceflags). + + + None + ContainerInherit + ObjectInherit + + InheritanceFlags + + InheritanceFlags + + + ContainerInherit, ObjectInherit + + + PassThru + + Indicates that the cmdlet writes the access control entries of every processed item, explicit and inherited, after the change. Without this switch the cmdlet produces no output. + + + SwitchParameter + + + False + + + PropagationFlags + + Specifies how the ACE is propagated to child objects. `None` propagates the ACE to all levels that the inheritance flags allow, `InheritOnly` keeps the ACE from applying to the item it is defined on, and `NoPropagateInherit` limits inheritance to the direct children of the folder. The default is `None`, and propagation flags only have an effect in combination with `-InheritanceFlags`. + + + None + NoPropagateInherit + InheritOnly + + PropagationFlags + + PropagationFlags + + + None + + + + Add-NTFSAccess + + SecurityDescriptor + + Specifies one or more `Security2.FileSystemSecurity2` objects, as returned by `Get-NTFSSecurityDescriptor`, that the ACE is added to. The change is made in memory only; use `Set-NTFSSecurityDescriptor` to write it to the file system. + 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. + + FileSystemSecurity2[] + + FileSystemSecurity2[] + + + None + + + Account + + Specifies one or more accounts or groups the ACE applies to. 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`. A name that cannot be translated into a SID raises an error, a SID that cannot be translated into a name is accepted. + + IdentityReference2[] + + IdentityReference2[] + + + None + + + AccessRights + + Specifies the rights the ACE grants or denies. The parameter accepts basic rights such as `Read`, `ReadAndExecute`, `Modify`, and `FullControl`, granular rights such as `CreateFiles`, `Traverse`, or `WriteAttributes`, and any combination of them. An `Allow` ACE always receives `Synchronize` in addition to the specified rights. For how the values relate to the Windows security dialog, see Concepts (../Concepts.md). + + + None + ReadData + ListDirectory + WriteData + CreateFiles + AppendData + CreateDirectories + ReadExtendedAttributes + WriteExtendedAttributes + ExecuteFile + Traverse + DeleteSubdirectoriesAndFiles + ReadAttributes + WriteAttributes + Write + Delete + ReadPermissions + Read + ReadAndExecute + Modify + ChangePermissions + TakeOwnership + Synchronize + FullControl + GenericAll + GenericExecute + GenericWrite + GenericRead + + FileSystemRights2 + + FileSystemRights2 + + + None + + + AccessType + + Specifies whether the ACE allows or denies the rights in `-AccessRights`. The default is `Allow`. A `Deny` ACE takes precedence over `Allow` ACEs that grant the same rights. + + + Allow + Deny + + AccessControlType + + AccessControlType + + + Allow + + + InheritanceFlags + + Specifies which kind of child objects inherit the ACE. `ContainerInherit` passes the ACE on to child folders, `ObjectInherit` passes it on to child files, and `None` keeps the ACE on the item itself. The default is `ContainerInherit, ObjectInherit`. Inheritance flags have no effect on files, where the ACE is always created with `None`. + For details about the flags, see the .NET documentation of the InheritanceFlags Enum (https://learn.microsoft.com/en-us/dotnet/api/system.security.accesscontrol.inheritanceflags). + + + None + ContainerInherit + ObjectInherit + + InheritanceFlags + + InheritanceFlags + + + ContainerInherit, ObjectInherit + + + PassThru + + Indicates that the cmdlet writes the access control entries of every processed item, explicit and inherited, after the change. Without this switch the cmdlet produces no output. + + + SwitchParameter + + + False + + + PropagationFlags + + Specifies how the ACE is propagated to child objects. `None` propagates the ACE to all levels that the inheritance flags allow, `InheritOnly` keeps the ACE from applying to the item it is defined on, and `NoPropagateInherit` limits inheritance to the direct children of the folder. The default is `None`, and propagation flags only have an effect in combination with `-InheritanceFlags`. + + + None + NoPropagateInherit + InheritOnly + + PropagationFlags + + PropagationFlags + + + None + + + + + + AccessRights + + Specifies the rights the ACE grants or denies. The parameter accepts basic rights such as `Read`, `ReadAndExecute`, `Modify`, and `FullControl`, granular rights such as `CreateFiles`, `Traverse`, or `WriteAttributes`, and any combination of them. An `Allow` ACE always receives `Synchronize` in addition to the specified rights. For how the values relate to the Windows security dialog, see Concepts (../Concepts.md). + + FileSystemRights2 + + FileSystemRights2 + + + None + + + AccessType + + Specifies whether the ACE allows or denies the rights in `-AccessRights`. The default is `Allow`. A `Deny` ACE takes precedence over `Allow` ACEs that grant the same rights. + + AccessControlType + + AccessControlType + + + Allow + + + Account + + Specifies one or more accounts or groups the ACE applies to. 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`. A name that cannot be translated into a SID raises an error, a SID that cannot be translated into a name is accepted. + + IdentityReference2[] + + IdentityReference2[] + + + None + + + AppliesTo + + Specifies the scope of the ACE in the wording of the Windows security dialog, for example `ThisFolderOnly`, `ThisFolderAndSubfolders`, or `SubfoldersAndFilesOnly`. The default is `ThisFolderSubfoldersAndFiles`. The cmdlet translates the value into the equivalent inheritance and propagation flags, so this parameter and the pair `-InheritanceFlags` and `-PropagationFlags` are two ways to describe the same ACE. The values ending in `OneLevel` limit inheritance to the direct children of the folder. + + ApplyTo + + ApplyTo + + + ThisFolderSubfoldersAndFiles + + + InheritanceFlags + + Specifies which kind of child objects inherit the ACE. `ContainerInherit` passes the ACE on to child folders, `ObjectInherit` passes it on to child files, and `None` keeps the ACE on the item itself. The default is `ContainerInherit, ObjectInherit`. Inheritance flags have no effect on files, where the ACE is always created with `None`. + For details about the flags, see the .NET documentation of the InheritanceFlags Enum (https://learn.microsoft.com/en-us/dotnet/api/system.security.accesscontrol.inheritanceflags). + + InheritanceFlags + + InheritanceFlags + + + ContainerInherit, ObjectInherit + + + PassThru + + Indicates that the cmdlet writes the access control entries of every processed item, explicit and inherited, after the change. Without this switch the cmdlet produces no output. + + SwitchParameter + + SwitchParameter + + + False + + + Path + + Specifies the path of one or more files or folders the ACE is added to. Relative paths are resolved against the current location. The parameter accepts pipeline input by value and by property name through its alias `FullName`. + + String[] + + String[] + + + None + + + PropagationFlags + + Specifies how the ACE is propagated to child objects. `None` propagates the ACE to all levels that the inheritance flags allow, `InheritOnly` keeps the ACE from applying to the item it is defined on, and `NoPropagateInherit` limits inheritance to the direct children of the folder. The default is `None`, and propagation flags only have an effect in combination with `-InheritanceFlags`. + + PropagationFlags + + PropagationFlags + + + None + + + SecurityDescriptor + + Specifies one or more `Security2.FileSystemSecurity2` objects, as returned by `Get-NTFSSecurityDescriptor`, that the ACE is added to. The change is made in memory only; use `Set-NTFSSecurityDescriptor` to write it to the file system. + 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. + + FileSystemSecurity2[] + + FileSystemSecurity2[] + + + None + + + + + + 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 returned by `Get-NTFSSecurityDescriptor`. + + + + + Security2.IdentityReference2[] + + + The accounts the ACE is created for, bound from a property named `Account`, `IdentityReference`, or `ID`. The output of `Get-NTFSAccess` supplies `Account`. + + + + + Security2.FileSystemRights2 + + + The rights of the ACE, piped by the property `AccessRights` or `FileSystemRights`. + + + + + System.Security.AccessControl.AccessControlType + + + The type of the ACE, piped by the property `AccessType` or `AccessControlType`. + + + + + System.Security.AccessControl.InheritanceFlags + + + The inheritance flags of the ACE, piped by the property `InheritanceFlags` in the `Complex` parameter sets. + + + + + System.Security.AccessControl.PropagationFlags + + + The propagation flags of the ACE, piped by the property `PropagationFlags` in the `Complex` parameter sets. + + + + + Security2.ApplyTo + + + The scope of the ACE, piped by the property `AppliesTo` in the `Simple` parameter sets. + + + + + + + Security2.FileSystemAccessRule2 + + + With `-PassThru`, the cmdlet writes all access control entries of every processed item, explicit and inherited. Without `-PassThru` it writes nothing. + + + + + + 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. + If the ACL of an item cannot be written because access is denied, the cmdlet tries once more after making the current account the owner of the item, and restores the previous owner afterwards. Changing the owner of an item requires the Take Ownership and Restore privileges, so this fallback only succeeds in an elevated session of an account that holds them. + + + + + ----------- Example 1: Grant read access to a folder ----------- + PS C:\> Add-NTFSAccess -Path C:\Data -Account 'NT AUTHORITY\Authenticated Users' -AccessRights Read + + This command grants read access to the built-in group of authenticated users. The ACE applies to the folder, its subfolders, and its files, because `-AppliesTo` defaults to `ThisFolderSubfoldersAndFiles`. + + + + --- Example 2: Grant full control and show the resulting ACL --- + PS C:\> Add-NTFSAccess -Path C:\Data -Account 'CONTOSO\Domain Admins' -AccessRights FullControl -PassThru + + This command grants full control to a domain group. `-PassThru` writes all access control entries of the folder, explicit and inherited, after the change. + + + + ---------- Example 3: Deny a right on a single folder ---------- + PS C:\> Add-NTFSAccess -Path C:\Data -Account 'CONTOSO\Domain Users' -AccessRights CreateFiles -AccessType Deny -AppliesTo ThisFolderOnly + + This command denies the creation of files in `C:\Data` to the members of a domain group. The ACE is not inherited by subfolders or files, because `-AppliesTo` is set to `ThisFolderOnly`. + + + + -- Example 4: Restore explicit permissions from a CSV backup -- + PS C:\> Import-Csv -Path C:\Backup\acl.csv | Add-NTFSAccess + + This command restores the access control entries that `Get-NTFSAccess` exported to a CSV file. The columns `FullName`, `Account`, `AccessRights`, `AccessControlType`, `InheritanceFlags`, and `PropagationFlags` bind to the matching parameters, so every row recreates the ACE it was exported from. + + + + + + Online Version: + https://github.com/raandree/NTFSSecurity/blob/master/Docs/Cmdlets/Add-NTFSAccess.md + + + Get-NTFSAccess + + + + Remove-NTFSAccess + + + + Clear-NTFSAccess + + + + Get-NTFSEffectiveAccess + + + + Get-NTFSSecurityDescriptor + + + + Set-NTFSSecurityDescriptor + + + + + + + Add-NTFSAudit + Add + NTFSAudit + + Adds an audit entry to a file or folder. + + + + The `Add-NTFSAudit` cmdlet adds an audit entry to the system access control list (SACL) of a file or folder. Windows then writes an event to the security log when the audited account uses one of the audited access rights on the item. `-AuditFlags Success` audits successful attempts, `-AuditFlags Failure` audits failed attempts, and the default audits both. For what the individual access rights permit, see Concepts (../Concepts.md). + In the `PathSimple` and `PathComplex` parameter sets the cmdlet reads the security descriptor of every item in `-Path`, adds the entry, and writes the descriptor back right away. In the `SDSimple` and `SDComplex` parameter sets it adds the entry to an in-memory `Security2.FileSystemSecurity2` object that `Get-NTFSSecurityDescriptor` returned; that change only reaches the file system when you pass the object to `Set-NTFSSecurityDescriptor`. The simple sets describe the scope of the entry with the single `-AppliesTo` parameter, the complex sets with `-InheritanceFlags` and `-PropagationFlags`. + `PathComplex` is the default parameter set. Because that set requires `-Path`, a command that uses `-SecurityDescriptor` must also specify `-AppliesTo`, `-InheritanceFlags`, or `-PropagationFlags`; otherwise PowerShell cannot decide between `SDSimple` and `SDComplex` and reports that the parameter set cannot be resolved. + When you omit them, `-AuditFlags` is `Success, Failure`, `-InheritanceFlags` is `ContainerInherit, ObjectInherit`, `-PropagationFlags` is `None`, and `-AppliesTo` is `ThisFolderSubfoldersAndFiles`, so both the simple and the complex set audit the item, its subfolders, and its files by default. Inheritance applies to folders only: when the item is a file, the cmdlet stores the entry without inheritance and propagation flags. + `-Path` accepts pipeline input by value and by property name through its `FullName` alias, so the output of `Get-ChildItem`, `Get-ChildItem2`, and `Get-Item2` binds to it, and the remaining parameters bind by property name. The cmdlet writes no object unless you use `-PassThru`. + + + + Add-NTFSAudit + + Path + + Specifies the files or folders the audit entry is added to. Relative paths are resolved against the current location. The parameter accepts pipeline input by value and by property name through its `FullName` alias. + + String[] + + String[] + + + None + + + AccessRights + + Specifies the access rights to audit. The value accepts the basic rights such as `Read`, `Write`, `Modify`, and `FullControl` as well as the individual rights such as `Delete` or `WriteAttributes`, and it accepts a comma-separated list that combines them. For the meaning of each right, see Concepts (../Concepts.md). + + + None + ReadData + ListDirectory + WriteData + CreateFiles + AppendData + CreateDirectories + ReadExtendedAttributes + WriteExtendedAttributes + ExecuteFile + Traverse + DeleteSubdirectoriesAndFiles + ReadAttributes + WriteAttributes + Write + Delete + ReadPermissions + Read + ReadAndExecute + Modify + ChangePermissions + TakeOwnership + Synchronize + FullControl + GenericAll + GenericExecute + GenericWrite + GenericRead + + FileSystemRights2 + + FileSystemRights2 + + + None + + + Account + + Specifies the accounts whose access to the item is audited. The value is an account name such as `CONTOSO\JohnDoe`, `CONTOSO\Domain Users`, `BUILTIN\Users`, or `Everyone`, or a SID string such as `S-1-5-32-545`. When you pass several accounts, the cmdlet adds one audit entry per account. + + IdentityReference2[] + + IdentityReference2[] + + + None + + + AppliesTo + + Specifies the scope of the audit entry with a single value instead of the `-InheritanceFlags` and `-PropagationFlags` pair, in the same wording the Advanced Security Settings dialog uses. `ThisFolderOnly` audits the folder itself, `ThisFolderSubfoldersAndFiles` audits the folder and everything below it, `SubfoldersAndFilesOnly` audits the content but not the folder itself, and the values ending in `OneLevel` limit inheritance to the direct children. The default is `ThisFolderSubfoldersAndFiles`. + + + ThisFolderOnly + ThisFolderSubfoldersAndFiles + ThisFolderAndSubfolders + ThisFolderAndFiles + SubfoldersAndFilesOnly + SubfoldersOnly + FilesOnly + ThisFolderSubfoldersAndFilesOneLevel + ThisFolderAndSubfoldersOneLevel + ThisFolderAndFilesOneLevel + SubfoldersAndFilesOnlyOneLevel + SubfoldersOnlyOneLevel + FilesOnlyOneLevel + + ApplyTo + + ApplyTo + + + ThisFolderSubfoldersAndFiles + + + AuditFlags + + Specifies which access attempts are audited. `Success` audits attempts that succeeded, `Failure` audits attempts that were denied, and `Success, Failure` audits both. The default is `Success, Failure`. + + + None + Success + Failure + + AuditFlags + + AuditFlags + + + Success, Failure + + + PassThru + + Indicates that the cmdlet writes the audit entries of the processed item to the pipeline after the change. All entries are returned, explicit and inherited ones, not only the entry that was added. Without this switch the cmdlet returns nothing when the operation succeeds. See the OUTPUTS section for which entries each parameter set returns. + + + SwitchParameter + + + False + + + + Add-NTFSAudit + + SecurityDescriptor + + Specifies one or more security descriptors that `Get-NTFSSecurityDescriptor` returned. The cmdlet adds the audit entry to the system access control list (SACL) of the in-memory object; pass the object to `Set-NTFSSecurityDescriptor` to write the change to the file system. + + FileSystemSecurity2[] + + FileSystemSecurity2[] + + + None + + + AccessRights + + Specifies the access rights to audit. The value accepts the basic rights such as `Read`, `Write`, `Modify`, and `FullControl` as well as the individual rights such as `Delete` or `WriteAttributes`, and it accepts a comma-separated list that combines them. For the meaning of each right, see Concepts (../Concepts.md). + + + None + ReadData + ListDirectory + WriteData + CreateFiles + AppendData + CreateDirectories + ReadExtendedAttributes + WriteExtendedAttributes + ExecuteFile + Traverse + DeleteSubdirectoriesAndFiles + ReadAttributes + WriteAttributes + Write + Delete + ReadPermissions + Read + ReadAndExecute + Modify + ChangePermissions + TakeOwnership + Synchronize + FullControl + GenericAll + GenericExecute + GenericWrite + GenericRead + + FileSystemRights2 + + FileSystemRights2 + + + None + + + Account + + Specifies the accounts whose access to the item is audited. The value is an account name such as `CONTOSO\JohnDoe`, `CONTOSO\Domain Users`, `BUILTIN\Users`, or `Everyone`, or a SID string such as `S-1-5-32-545`. When you pass several accounts, the cmdlet adds one audit entry per account. + + IdentityReference2[] + + IdentityReference2[] + + + None + + + AppliesTo + + Specifies the scope of the audit entry with a single value instead of the `-InheritanceFlags` and `-PropagationFlags` pair, in the same wording the Advanced Security Settings dialog uses. `ThisFolderOnly` audits the folder itself, `ThisFolderSubfoldersAndFiles` audits the folder and everything below it, `SubfoldersAndFilesOnly` audits the content but not the folder itself, and the values ending in `OneLevel` limit inheritance to the direct children. The default is `ThisFolderSubfoldersAndFiles`. + + + ThisFolderOnly + ThisFolderSubfoldersAndFiles + ThisFolderAndSubfolders + ThisFolderAndFiles + SubfoldersAndFilesOnly + SubfoldersOnly + FilesOnly + ThisFolderSubfoldersAndFilesOneLevel + ThisFolderAndSubfoldersOneLevel + ThisFolderAndFilesOneLevel + SubfoldersAndFilesOnlyOneLevel + SubfoldersOnlyOneLevel + FilesOnlyOneLevel + + ApplyTo + + ApplyTo + + + ThisFolderSubfoldersAndFiles + + + AuditFlags + + Specifies which access attempts are audited. `Success` audits attempts that succeeded, `Failure` audits attempts that were denied, and `Success, Failure` audits both. The default is `Success, Failure`. + + + None + Success + Failure + + AuditFlags + + AuditFlags + + + Success, Failure + + + PassThru + + Indicates that the cmdlet writes the audit entries of the processed item to the pipeline after the change. All entries are returned, explicit and inherited ones, not only the entry that was added. Without this switch the cmdlet returns nothing when the operation succeeds. See the OUTPUTS section for which entries each parameter set returns. + + + SwitchParameter + + + False + + + + Add-NTFSAudit + + Path + + Specifies the files or folders the audit entry is added to. Relative paths are resolved against the current location. The parameter accepts pipeline input by value and by property name through its `FullName` alias. + + String[] + + String[] + + + None + + + AccessRights + + Specifies the access rights to audit. The value accepts the basic rights such as `Read`, `Write`, `Modify`, and `FullControl` as well as the individual rights such as `Delete` or `WriteAttributes`, and it accepts a comma-separated list that combines them. For the meaning of each right, see Concepts (../Concepts.md). + + + None + ReadData + ListDirectory + WriteData + CreateFiles + AppendData + CreateDirectories + ReadExtendedAttributes + WriteExtendedAttributes + ExecuteFile + Traverse + DeleteSubdirectoriesAndFiles + ReadAttributes + WriteAttributes + Write + Delete + ReadPermissions + Read + ReadAndExecute + Modify + ChangePermissions + TakeOwnership + Synchronize + FullControl + GenericAll + GenericExecute + GenericWrite + GenericRead + + FileSystemRights2 + + FileSystemRights2 + + + None + + + Account + + Specifies the accounts whose access to the item is audited. The value is an account name such as `CONTOSO\JohnDoe`, `CONTOSO\Domain Users`, `BUILTIN\Users`, or `Everyone`, or a SID string such as `S-1-5-32-545`. When you pass several accounts, the cmdlet adds one audit entry per account. + + IdentityReference2[] + + IdentityReference2[] + + + None + + + AuditFlags + + Specifies which access attempts are audited. `Success` audits attempts that succeeded, `Failure` audits attempts that were denied, and `Success, Failure` audits both. The default is `Success, Failure`. + + + None + Success + Failure + + AuditFlags + + AuditFlags + + + Success, Failure + + + InheritanceFlags + + Specifies which child items inherit the audit entry. `ContainerInherit` passes the entry on to child folders, `ObjectInherit` passes it on to child files, and `None` keeps the entry on the item itself. The values can be combined, and the default is `ContainerInherit, ObjectInherit`. Use `-PropagationFlags` to control whether the entry also applies to the item itself and how far it propagates. + + + None + ContainerInherit + ObjectInherit + + InheritanceFlags + + InheritanceFlags + + + ContainerInherit, ObjectInherit + + + PassThru + + Indicates that the cmdlet writes the audit entries of the processed item to the pipeline after the change. All entries are returned, explicit and inherited ones, not only the entry that was added. Without this switch the cmdlet returns nothing when the operation succeeds. See the OUTPUTS section for which entries each parameter set returns. + + + SwitchParameter + + + False + + + PropagationFlags + + Specifies how the inheritance selected with `-InheritanceFlags` propagates. `None` applies the entry to the item itself and to all inheriting child items, `InheritOnly` applies it to the inheriting child items but not to the item itself, and `NoPropagateInherit` limits inheritance to the direct children. The values `InheritOnly` and `NoPropagateInherit` can be combined, and the default is `None`. The parameter has no effect when `-InheritanceFlags` is `None`. + + + None + NoPropagateInherit + InheritOnly + + PropagationFlags + + PropagationFlags + + + None + + + + Add-NTFSAudit + + SecurityDescriptor + + Specifies one or more security descriptors that `Get-NTFSSecurityDescriptor` returned. The cmdlet adds the audit entry to the system access control list (SACL) of the in-memory object; pass the object to `Set-NTFSSecurityDescriptor` to write the change to the file system. + + FileSystemSecurity2[] + + FileSystemSecurity2[] + + + None + + + AccessRights + + Specifies the access rights to audit. The value accepts the basic rights such as `Read`, `Write`, `Modify`, and `FullControl` as well as the individual rights such as `Delete` or `WriteAttributes`, and it accepts a comma-separated list that combines them. For the meaning of each right, see Concepts (../Concepts.md). + + + None + ReadData + ListDirectory + WriteData + CreateFiles + AppendData + CreateDirectories + ReadExtendedAttributes + WriteExtendedAttributes + ExecuteFile + Traverse + DeleteSubdirectoriesAndFiles + ReadAttributes + WriteAttributes + Write + Delete + ReadPermissions + Read + ReadAndExecute + Modify + ChangePermissions + TakeOwnership + Synchronize + FullControl + GenericAll + GenericExecute + GenericWrite + GenericRead + + FileSystemRights2 + + FileSystemRights2 + + + None + + + Account + + Specifies the accounts whose access to the item is audited. The value is an account name such as `CONTOSO\JohnDoe`, `CONTOSO\Domain Users`, `BUILTIN\Users`, or `Everyone`, or a SID string such as `S-1-5-32-545`. When you pass several accounts, the cmdlet adds one audit entry per account. + + IdentityReference2[] + + IdentityReference2[] + + + None + + + AuditFlags + + Specifies which access attempts are audited. `Success` audits attempts that succeeded, `Failure` audits attempts that were denied, and `Success, Failure` audits both. The default is `Success, Failure`. + + + None + Success + Failure + + AuditFlags + + AuditFlags + + + Success, Failure + + + InheritanceFlags + + Specifies which child items inherit the audit entry. `ContainerInherit` passes the entry on to child folders, `ObjectInherit` passes it on to child files, and `None` keeps the entry on the item itself. The values can be combined, and the default is `ContainerInherit, ObjectInherit`. Use `-PropagationFlags` to control whether the entry also applies to the item itself and how far it propagates. + + + None + ContainerInherit + ObjectInherit + + InheritanceFlags + + InheritanceFlags + + + ContainerInherit, ObjectInherit + + + PassThru + + Indicates that the cmdlet writes the audit entries of the processed item to the pipeline after the change. All entries are returned, explicit and inherited ones, not only the entry that was added. Without this switch the cmdlet returns nothing when the operation succeeds. See the OUTPUTS section for which entries each parameter set returns. + + + SwitchParameter + + + False + + + PropagationFlags + + Specifies how the inheritance selected with `-InheritanceFlags` propagates. `None` applies the entry to the item itself and to all inheriting child items, `InheritOnly` applies it to the inheriting child items but not to the item itself, and `NoPropagateInherit` limits inheritance to the direct children. The values `InheritOnly` and `NoPropagateInherit` can be combined, and the default is `None`. The parameter has no effect when `-InheritanceFlags` is `None`. + + + None + NoPropagateInherit + InheritOnly + + PropagationFlags + + PropagationFlags + + + None + + + + + + AccessRights + + Specifies the access rights to audit. The value accepts the basic rights such as `Read`, `Write`, `Modify`, and `FullControl` as well as the individual rights such as `Delete` or `WriteAttributes`, and it accepts a comma-separated list that combines them. For the meaning of each right, see Concepts (../Concepts.md). + + FileSystemRights2 + + FileSystemRights2 + + + None + + + Account + + Specifies the accounts whose access to the item is audited. The value is an account name such as `CONTOSO\JohnDoe`, `CONTOSO\Domain Users`, `BUILTIN\Users`, or `Everyone`, or a SID string such as `S-1-5-32-545`. When you pass several accounts, the cmdlet adds one audit entry per account. + + IdentityReference2[] + + IdentityReference2[] + + + None + + + AppliesTo + + Specifies the scope of the audit entry with a single value instead of the `-InheritanceFlags` and `-PropagationFlags` pair, in the same wording the Advanced Security Settings dialog uses. `ThisFolderOnly` audits the folder itself, `ThisFolderSubfoldersAndFiles` audits the folder and everything below it, `SubfoldersAndFilesOnly` audits the content but not the folder itself, and the values ending in `OneLevel` limit inheritance to the direct children. The default is `ThisFolderSubfoldersAndFiles`. + + ApplyTo + + ApplyTo + + + ThisFolderSubfoldersAndFiles + + + AuditFlags + + Specifies which access attempts are audited. `Success` audits attempts that succeeded, `Failure` audits attempts that were denied, and `Success, Failure` audits both. The default is `Success, Failure`. + + AuditFlags + + AuditFlags + + + Success, Failure + + + InheritanceFlags + + Specifies which child items inherit the audit entry. `ContainerInherit` passes the entry on to child folders, `ObjectInherit` passes it on to child files, and `None` keeps the entry on the item itself. The values can be combined, and the default is `ContainerInherit, ObjectInherit`. Use `-PropagationFlags` to control whether the entry also applies to the item itself and how far it propagates. + + InheritanceFlags + + InheritanceFlags + + + ContainerInherit, ObjectInherit + + + PassThru + + Indicates that the cmdlet writes the audit entries of the processed item to the pipeline after the change. All entries are returned, explicit and inherited ones, not only the entry that was added. Without this switch the cmdlet returns nothing when the operation succeeds. See the OUTPUTS section for which entries each parameter set returns. + + SwitchParameter + + SwitchParameter + + + False + + + Path + + Specifies the files or folders the audit entry is added to. Relative paths are resolved against the current location. The parameter accepts pipeline input by value and by property name through its `FullName` alias. + + String[] + + String[] + + + None + + + PropagationFlags + + Specifies how the inheritance selected with `-InheritanceFlags` propagates. `None` applies the entry to the item itself and to all inheriting child items, `InheritOnly` applies it to the inheriting child items but not to the item itself, and `NoPropagateInherit` limits inheritance to the direct children. The values `InheritOnly` and `NoPropagateInherit` can be combined, and the default is `None`. The parameter has no effect when `-InheritanceFlags` is `None`. + + PropagationFlags + + PropagationFlags + + + None + + + SecurityDescriptor + + Specifies one or more security descriptors that `Get-NTFSSecurityDescriptor` returned. The cmdlet adds the audit entry to the system access control list (SACL) of the in-memory object; pass the object to `Set-NTFSSecurityDescriptor` to write the change to the file system. + + FileSystemSecurity2[] + + FileSystemSecurity2[] + + + None + + + + + + System.String[] + + + You can pipe paths to this cmdlet, or objects that have a `Path` or `FullName` property, such as the output of `Get-ChildItem`, `Get-ChildItem2`, and `Get-Item2`. + + + + + Security2.FileSystemSecurity2[] + + + You can pipe the security descriptors that `Get-NTFSSecurityDescriptor` returns to this cmdlet. + + + + + Security2.IdentityReference2[] + + + The accounts passed to `-Account` are converted to this type from an account name or a SID string. The parameter binds by property name through its own name and its aliases `IdentityReference` and `ID`, so the `Account` property of the entries this module returns supplies the value. + + + + + Security2.FileSystemRights2 + + + The value passed to `-AccessRights` is converted to this type. The parameter binds by property name, so an object with an `AccessRights` or `FileSystemRights` property supplies the value. + + + + + System.Security.AccessControl.AuditFlags + + + The value passed to `-AuditFlags` is converted to this type and binds by property name. + + + + + System.Security.AccessControl.InheritanceFlags + + + The value passed to `-InheritanceFlags` is converted to this type and binds by property name in the `PathComplex` and `SDComplex` parameter sets. + + + + + System.Security.AccessControl.PropagationFlags + + + The value passed to `-PropagationFlags` is converted to this type and binds by property name in the `PathComplex` and `SDComplex` parameter sets. + + + + + Security2.ApplyTo + + + The value passed to `-AppliesTo` is converted to this type and binds by property name in the `PathSimple` and `SDSimple` parameter sets. + + + + + + + Security2.FileSystemAccessRule2 + + + Without `-PassThru` the cmdlet writes nothing. With `-PassThru` the type depends on the parameter set: in the `Path` sets the cmdlet writes all audit entries of the item, explicit and inherited ones, as `Security2.FileSystemAuditRule2` objects, while in the `SecurityDescriptor` sets it writes the access entries of the descriptor as `Security2.FileSystemAccessRule2` objects. Use `Get-NTFSAudit` when you need the audit entries of a security descriptor. + + + + + + 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. + Writing the SACL requires the Security privilege (`SeSecurityPrivilege`, "Manage auditing and security log"), so run this cmdlet in an elevated session of an account that holds that privilege. Without it, the cmdlet writes a non-terminating `AddAceError` whose message states that a required privilege is not held by the client, and the item is left unchanged. + If the security descriptor cannot be read or written because access is denied, the cmdlet takes ownership of the item, repeats the operation, and restores the previous owner. If the second attempt fails as well, the cmdlet writes an error, and the ownership change is not rolled back. + The syntax shows `-Path`, `-Account`, and `-AccessRights` as positional parameters, but `-Account` and `-AccessRights` are both declared at position 2. A command that passes them positionally therefore fails with the error that positional parameters cannot be bound because no names were given, and `Get-Command Add-NTFSAudit -Syntax` leaves `-Account` out for the same reason. Pass `-Account` and `-AccessRights` by name, as the examples above do. + An audit entry alone does not create events. Windows writes the events to the security log only while the "Audit object access" policy, or the corresponding "Audit File System" advanced audit policy, is enabled for success, failure, or both. That policy is a Windows setting and is not managed by this module. + + + + + ---------- Example 1: Audit failed access to a folder ---------- + PS C:\> Add-NTFSAudit -Path C:\Data -Account 'CONTOSO\Domain Users' -AccessRights FullControl -AuditFlags Failure + + This command audits every failed attempt of the group `CONTOSO\Domain Users` to use one of the rights contained in `FullControl` on `C:\Data`. Because `-AppliesTo` and the inheritance parameters are omitted, the entry applies to the folder, its subfolders, and its files. + + + + ----- Example 2: Audit successful deletions in one folder ----- + PS C:\> Add-NTFSAudit -Path C:\Data -Account Everyone -AccessRights Delete, DeleteSubdirectoriesAndFiles -AuditFlags Success -AppliesTo ThisFolderOnly + + This command audits successful deletions performed by any account in the folder `C:\Data`. `-AppliesTo ThisFolderOnly` keeps the entry from being inherited by subfolders and files. + + + + ------ Example 3: Audit several folders from the pipeline ------ + PS C:\> Get-ChildItem2 -Path C:\Data -Directory | Add-NTFSAudit -Account 'BUILTIN\Users' -AccessRights ReadData -AuditFlags Success -PassThru + + This command adds the same audit entry to every subfolder of `C:\Data` and returns all audit entries of each folder afterwards, including the inherited ones, so that you can check the result. + + + + ---- Example 4: Add an audit entry to a security descriptor ---- + PS C:\> $sd = Get-NTFSSecurityDescriptor -Path C:\Data +PS C:\> Add-NTFSAudit -SecurityDescriptor $sd -Account 'CONTOSO\JohnDoe' -AccessRights Modify -AuditFlags Success, Failure -AppliesTo SubfoldersAndFilesOnly +PS C:\> Set-NTFSSecurityDescriptor -SecurityDescriptor $sd + + This command adds an audit entry for `CONTOSO\JohnDoe` to the in-memory security descriptor of `C:\Data` and then writes the descriptor back. The entry applies to the subfolders and files of `C:\Data` but not to the folder itself. + + + + + + Online Version: + https://github.com/raandree/NTFSSecurity/blob/master/Docs/Cmdlets/Add-NTFSAudit.md + + + Get-NTFSAudit + + + + Remove-NTFSAudit + + + + Clear-NTFSAudit + + + + Get-NTFSOrphanedAudit + + + + Add-NTFSAccess + + + + Set-NTFSSecurityDescriptor + + + + + + + Clear-NTFSAccess + Clear + NTFSAccess + + Removes all explicit access control entries from a file or folder. + + + + Removes every access control entry (ACE) that is defined on a file or a folder itself. Inherited entries are not touched and continue to apply, so an item whose permissions come from its parent folder keeps them. + `-DisableInheritance` additionally protects the item from its parents and discards the inherited entries instead of copying them into the item. An item that is cleared with `-DisableInheritance` therefore ends up with an empty DACL, which denies access to everyone; only its owner can still change the permissions. Grant the required rights with `Add-NTFSAccess` right after clearing, or re-enable inheritance with `Enable-NTFSAccessInheritance`. + In the `Path` parameter set the cmdlet reads the item from disk and writes the changed DACL back immediately; relative paths are resolved against the current location. In the `SD` parameter set it changes a `Security2.FileSystemSecurity2` object returned by `Get-NTFSSecurityDescriptor` in memory until `Set-NTFSSecurityDescriptor` writes it back. The cmdlet writes no output, and a failure on one item is reported as a non-terminating error while the remaining items are processed. + + + + Clear-NTFSAccess + + Path + + Specifies the path of one or more files or folders whose explicit access control entries are removed. Relative paths are resolved against the current location. The parameter accepts pipeline input by value and by property name through its alias `FullName`. + + String[] + + String[] + + + None + + + DisableInheritance + + Indicates that inheritance is disabled after the explicit entries are removed, and that the inherited entries are discarded rather than copied into the item. Without this switch the inherited entries remain in effect. + + + SwitchParameter + + + False + + + + Clear-NTFSAccess + + SecurityDescriptor + + Specifies one or more `Security2.FileSystemSecurity2` objects, as returned by `Get-NTFSSecurityDescriptor`, whose explicit access control entries are removed. The change is made in memory only; use `Set-NTFSSecurityDescriptor` to write it to the file system. + 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. + + FileSystemSecurity2[] + + FileSystemSecurity2[] + + + None + + + DisableInheritance + + Indicates that inheritance is disabled after the explicit entries are removed, and that the inherited entries are discarded rather than copied into the item. Without this switch the inherited entries remain in effect. + + + SwitchParameter + + + False + + + + + + DisableInheritance + + Indicates that inheritance is disabled after the explicit entries are removed, and that the inherited entries are discarded rather than copied into the item. Without this switch the inherited entries remain in effect. + + SwitchParameter + + SwitchParameter + + + False + + + Path + + Specifies the path of one or more files or folders whose explicit access control entries are removed. Relative paths are resolved against the current location. The parameter accepts pipeline input by value and by property name through its alias `FullName`. + + String[] + + String[] + + + None + + + SecurityDescriptor + + Specifies one or more `Security2.FileSystemSecurity2` objects, as returned by `Get-NTFSSecurityDescriptor`, whose explicit access control entries are removed. The change is made in memory only; use `Set-NTFSSecurityDescriptor` to write it to the file system. + 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. + + FileSystemSecurity2[] + + FileSystemSecurity2[] + + + None + + + + + + 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 returned by `Get-NTFSSecurityDescriptor`. + + + + + + + System.Object + + + The cmdlet writes nothing. Use `Get-NTFSAccess` to inspect the result. + + + + + + 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. + If the ACL of an item cannot be written because access is denied, the cmdlet tries once more after making the current account the owner of the item, and restores the previous owner afterwards. Changing the owner of an item requires the Take Ownership and Restore privileges, so this fallback only succeeds in an elevated session of an account that holds them. + + + + + ---- Example 1: Remove the explicit permissions of a folder ---- + PS C:\> Clear-NTFSAccess -Path C:\Data + + This command removes all access control entries that are defined on `C:\Data` itself. The entries that the folder inherits from its parent remain in effect. + + + + --- Example 2: Remove all permissions and break inheritance --- + PS C:\> Clear-NTFSAccess -Path C:\Data -DisableInheritance + + This command removes the explicit entries of `C:\Data` and disables inheritance without copying the inherited entries. The folder is left with an empty DACL and is inaccessible until new permissions are granted. + + + + ----- Example 3: Reset the permissions of several folders ----- + PS C:\> Get-ChildItem2 -Path C:\Data -Recurse -Directory | Clear-NTFSAccess + + This command removes the explicit entries of every subfolder of `C:\Data` so that all of them rely on the permissions inherited from `C:\Data`. + + + + ------------- Example 4: Rebuild an ACL in memory ------------- + PS C:\> $sd = Get-NTFSSecurityDescriptor -Path C:\Data +PS C:\> Clear-NTFSAccess -SecurityDescriptor $sd -DisableInheritance +PS C:\> Add-NTFSAccess -SecurityDescriptor $sd -Account 'BUILTIN\Administrators' -AccessRights FullControl -AppliesTo ThisFolderSubfoldersAndFiles +PS C:\> Set-NTFSSecurityDescriptor -SecurityDescriptor $sd + + These commands replace the complete ACL of `C:\Data` in one write. The security descriptor is changed in memory, and the file system is only touched by `Set-NTFSSecurityDescriptor`. + + + + + + Online Version: + https://github.com/raandree/NTFSSecurity/blob/master/Docs/Cmdlets/Clear-NTFSAccess.md + + + Add-NTFSAccess + + + + Get-NTFSAccess + + + + Remove-NTFSAccess + + + + Disable-NTFSAccessInheritance + + + + Enable-NTFSAccessInheritance + + + + Set-NTFSSecurityDescriptor + + + + + + + Clear-NTFSAudit + Clear + NTFSAudit + + Removes all explicit audit entries from a file or folder. + + + + The `Clear-NTFSAudit` cmdlet removes every audit entry that is set on a file or folder itself from its system access control list (SACL). Entries that the item inherits from a parent folder are left alone, because they are stored on that parent. Add `-DisableInheritance` to protect the item from its parent and to drop the inherited entries as well, which leaves the item without any auditing. + In the `Path` parameter set the cmdlet reads the security descriptor of every item in `-Path`, removes the entries, and writes the descriptor back right away. Relative paths are resolved against the current location, and the parameter accepts pipeline input by value and by property name through its `FullName` alias, so the output of `Get-ChildItem`, `Get-ChildItem2`, and `Get-Item2` binds to it. In the `SD` parameter set the cmdlet changes an in-memory `Security2.FileSystemSecurity2` object that `Get-NTFSSecurityDescriptor` returned, and the change reaches the file system only when you pass the object to `Set-NTFSSecurityDescriptor`. + To remove a single audit entry instead of all of them, use `Remove-NTFSAudit`. The cmdlet writes no object; use `Get-NTFSAudit` to check the result. + + + + Clear-NTFSAudit + + Path + + Specifies the files or folders whose audit entries are removed. Relative paths are resolved against the current location. The parameter accepts pipeline input by value and by property name through its `FullName` alias. + + String[] + + String[] + + + None + + + DisableInheritance + + Indicates that the item no longer inherits audit entries from its parent folder. The inherited entries are discarded rather than copied to the item, so the item is left with no audit entries at all. Without this switch the item keeps inheriting audit entries from its parent. + + + SwitchParameter + + + False + + + + Clear-NTFSAudit + + SecurityDescriptor + + Specifies one or more security descriptors that `Get-NTFSSecurityDescriptor` returned. The cmdlet removes the explicit audit entries from the system access control list (SACL) of the in-memory object; pass the object to `Set-NTFSSecurityDescriptor` to write the change to the file system. + + FileSystemSecurity2[] + + FileSystemSecurity2[] + + + None + + + DisableInheritance + + Indicates that the item no longer inherits audit entries from its parent folder. The inherited entries are discarded rather than copied to the item, so the item is left with no audit entries at all. Without this switch the item keeps inheriting audit entries from its parent. + + + SwitchParameter + + + False + + + + + + DisableInheritance + + Indicates that the item no longer inherits audit entries from its parent folder. The inherited entries are discarded rather than copied to the item, so the item is left with no audit entries at all. Without this switch the item keeps inheriting audit entries from its parent. + + SwitchParameter + + SwitchParameter + + + False + + + Path + + Specifies the files or folders whose audit entries are removed. Relative paths are resolved against the current location. The parameter accepts pipeline input by value and by property name through its `FullName` alias. + + String[] + + String[] + + + None + + + SecurityDescriptor + + Specifies one or more security descriptors that `Get-NTFSSecurityDescriptor` returned. The cmdlet removes the explicit audit entries from the system access control list (SACL) of the in-memory object; pass the object to `Set-NTFSSecurityDescriptor` to write the change to the file system. + + FileSystemSecurity2[] + + FileSystemSecurity2[] + + + None + + + + + + System.String[] + + + You can pipe paths to this cmdlet, or objects that have a `Path` or `FullName` property, such as the output of `Get-ChildItem`, `Get-ChildItem2`, and `Get-Item2`. + + + + + Security2.FileSystemSecurity2[] + + + You can pipe the security descriptors that `Get-NTFSSecurityDescriptor` returns to this cmdlet. + + + + + + + System.Object + + + This cmdlet writes nothing to the pipeline. Use `Get-NTFSAudit` to check which audit entries an item has after the operation. + + + + + + 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 and writing the SACL requires the Security privilege (`SeSecurityPrivilege`, "Manage auditing and security log"), so run this cmdlet in an elevated session of an account that holds that privilege. Without that privilege the cmdlet reads the security descriptor without its SACL, finds no audit entries to remove, and finishes without an error although nothing was changed. `-DisableInheritance` fails in that situation with a `ClearAclError` whose message states that a required privilege is not held by the client. + If the security descriptor cannot be read or written because access is denied, the cmdlet takes ownership of the item, repeats the operation, and restores the previous owner. If the second attempt fails as well, the cmdlet writes an error, and the ownership change is not rolled back. + + + + + --- Example 1: Remove the explicit audit entries of a folder --- + PS C:\> Clear-NTFSAudit -Path C:\Data + + This command removes every audit entry that is set on `C:\Data` itself. The entries that the folder inherits from its parent stay in place. + + + + --------- Example 2: Remove all auditing from a folder --------- + PS C:\> Clear-NTFSAudit -Path C:\Data -DisableInheritance + + This command removes the explicit audit entries of `C:\Data` and then stops the folder from inheriting audit entries, discarding the inherited entries instead of copying them to the folder. + + + + ----- Example 3: Clear the audit entries of a folder tree ----- + PS C:\> Get-ChildItem2 -Path C:\Data -Recurse | Clear-NTFSAudit + + This command pipes every item below `C:\Data` into `Clear-NTFSAudit` and removes the audit entries that are set on those items themselves. + + + + - Example 4: Clear the audit entries of a security descriptor - + PS C:\> $sd = Get-NTFSSecurityDescriptor -Path C:\Data +PS C:\> Clear-NTFSAudit -SecurityDescriptor $sd +PS C:\> Set-NTFSSecurityDescriptor -SecurityDescriptor $sd + + This command removes the explicit audit entries from the in-memory security descriptor of `C:\Data` and then writes the descriptor back to the file system. + + + + + + Online Version: + https://github.com/raandree/NTFSSecurity/blob/master/Docs/Cmdlets/Clear-NTFSAudit.md + + + Get-NTFSAudit + + + + Add-NTFSAudit + + + + Remove-NTFSAudit + + + + Disable-NTFSAuditInheritance + + + + Enable-NTFSAuditInheritance + + + + Clear-NTFSAccess + + + + + + + Copy-Item2 + Copy + Item2 + + Copies a file to another location, including paths longer than 260 characters. + + + + The `Copy-Item2` cmdlet copies the items in `-Path` to the location in `-Destination`. It is the long-path counterpart of the built-in `Copy-Item` cmdlet: it works through the AlphaFS library (`Alphaleonis.Win32.Filesystem`), so source and destination may be longer than the 260-character `MAX_PATH` limit. + How `-Destination` is interpreted depends on what is already there. If the value names an existing folder, the cmdlet keeps the name of the source item and copies it into that folder. In every other case the value is the full path of the new item, which lets you copy and rename in one step. `-Destination` is resolved against the current location once, when the cmdlet starts. + Without `-Force`, the cmdlet checks whether the destination file already exists and writes a `DestinationFileAlreadyExists` error instead of overwriting it. With `-Force`, an existing file is replaced. Relative paths and the `.` and `..` notations in `-Path` are resolved against the current location, and wildcard characters are not supported. + The cmdlet supports `-WhatIf` and `-Confirm`, and it writes nothing to the pipeline unless you specify `-PassThru $true`. + + + + Copy-Item2 + + Path + + Specifies the path of one or more items to copy. Relative paths are resolved against the current location, and wildcard characters are not supported. The parameter accepts pipeline input by value and by the property name `FullName`, so you can pipe the output of `Get-ChildItem2` or `Get-Item2` into this cmdlet. + + String[] + + String[] + + + None + + + Destination + + Specifies the target of the copy operation. If the value names an existing folder, the cmdlet copies the item into that folder under its current name; otherwise the value is the full path of the new item. The path is resolved against the current location once, when the cmdlet starts, so pass an absolute path when you supply `-Destination` through the pipeline. + + String + + String + + + None + + + Confirm + + Prompts you for confirmation before running the cmdlet. + + + SwitchParameter + + + False + + + Force + + Indicates that the cmdlet overwrites an existing destination file. Without `-Force`, an existing file causes the error `DestinationFileAlreadyExists` and the item is not copied. + + + SwitchParameter + + + False + + + PassThru + + Specifies whether the cmdlet returns an object for each item that it copied. This parameter is typed `Boolean` rather than a switch, so it needs an explicit value, as in `-PassThru $true`. By default, the cmdlet produces no output. After a successful file copy, the returned object describes the file at the destination path. + + Boolean + + Boolean + + + None + + + WhatIf + + Shows what would happen if the cmdlet runs. The cmdlet is not run. + + + SwitchParameter + + + False + + + + + + Confirm + + Prompts you for confirmation before running the cmdlet. + + SwitchParameter + + SwitchParameter + + + False + + + Destination + + Specifies the target of the copy operation. If the value names an existing folder, the cmdlet copies the item into that folder under its current name; otherwise the value is the full path of the new item. The path is resolved against the current location once, when the cmdlet starts, so pass an absolute path when you supply `-Destination` through the pipeline. + + String + + String + + + None + + + Force + + Indicates that the cmdlet overwrites an existing destination file. Without `-Force`, an existing file causes the error `DestinationFileAlreadyExists` and the item is not copied. + + SwitchParameter + + SwitchParameter + + + False + + + PassThru + + Specifies whether the cmdlet returns an object for each item that it copied. This parameter is typed `Boolean` rather than a switch, so it needs an explicit value, as in `-PassThru $true`. By default, the cmdlet produces no output. After a successful file copy, the returned object describes the file at the destination path. + + Boolean + + Boolean + + + None + + + Path + + Specifies the path of one or more items to copy. Relative paths are resolved against the current location, and wildcard characters are not supported. The parameter accepts pipeline input by value and by the property name `FullName`, so you can pipe the output of `Get-ChildItem2` or `Get-Item2` into this cmdlet. + + String[] + + String[] + + + None + + + WhatIf + + Shows what would happen if the cmdlet runs. The cmdlet is not run. + + SwitchParameter + + SwitchParameter + + + False + + + + + + System.String[] + + + You can pipe one or more paths to this cmdlet, either as strings or as objects that have a `FullName` property, such as the output of `Get-ChildItem2` or `Get-Item2`. + + + + + System.String + + + You can pipe an object that has a `Destination` property to supply the target of the copy operation. + + + + + + + System.Object + + + By default this cmdlet returns nothing. With `-PassThru $true` it returns an `Alphaleonis.Win32.Filesystem.FileInfo` or `Alphaleonis.Win32.Filesystem.DirectoryInfo` object for each item that it copied. + + + + + + `Copy-Item2` copies through the AlphaFS library (`Alphaleonis.Win32.Filesystem`), which is why it handles source and destination paths that exceed the 260-character `MAX_PATH` limit of the built-in `Copy-Item` cmdlet. + Copying a folder that contains files currently fails with a `CopyError` that reports a `DirectoryNotFoundException` for the first file in the folder. Copy files individually, for example by piping `Get-ChildItem2 -Recurse -File` into this cmdlet, and create the target folders beforehand. + If a path in `-Path` does not exist or the destination file exists and `-Force` is missing, the cmdlet writes a non-terminating error and skips the remaining paths that were passed in the same call. Items that arrive one by one through the pipeline are not affected, because each of them is processed separately. + + + + + ------------- Example 1: Copy a file into a folder ------------- + PS C:\> Copy-Item2 -Path C:\Data\report.docx -Destination C:\Data\Archive + + Copies `report.docx` into the existing folder `C:\Data\Archive`, where it keeps its name. The command fails if `C:\Data\Archive\report.docx` already exists. + + + + -------- Example 2: Copy and rename a file in one step -------- + PS C:\> Copy-Item2 -Path C:\Data\report.docx -Destination C:\Data\Archive\report-2026.docx -Force + + Copies the file under a new name and, because of `-Force`, replaces an existing `report-2026.docx`. + + + + ---------- Example 3: Copy files with very long paths ---------- + PS C:\> Get-ChildItem2 -Path C:\Data\Projects -Recurse -File -Filter '*.log' | Copy-Item2 -Destination C:\Data\Logs -Force + + Collects every log file below `C:\Data\Projects`, no matter how long its path is, and copies them all into `C:\Data\Logs`. Because each file keeps only its name, the files from the different source folders end up side by side in the target folder. + + + + ------------- Example 4: Preview a copy operation ------------- + PS C:\> Copy-Item2 -Path C:\Data\report.docx -Destination C:\Data\Archive -WhatIf + + Shows which operation the cmdlet would perform without copying anything. + + + + + + Online Version: + https://github.com/raandree/NTFSSecurity/blob/master/Docs/Cmdlets/Copy-Item2.md + + + Move-Item2 + + + + Remove-Item2 + + + + Get-ChildItem2 + + + + Get-Item2 + + + + Test-Path2 + + + + + + + Disable-NTFSAccessInheritance + Disable + NTFSAccessInheritance + + Blocks the inheritance of access rules on a file or folder. + + + + The `Disable-NTFSAccessInheritance` cmdlet protects the discretionary access control list (DACL) of a file or folder, so that the access rules of the parent folder no longer apply to the item. From then on, only the access rules stored in the item's own DACL grant or deny access to it. + By default, the rules that the item currently inherits are copied into its DACL before inheritance is blocked. The effective permissions therefore stay the same, and the copies become explicit rules that you can change or remove individually. The `-RemoveInheritedAccessRules` switch discards the inherited rules instead of copying them. If the item has no explicit rules of its own, that leaves an empty DACL, which denies access to everyone except the owner, so check the item with `Get-NTFSAccess` before you use the switch. + In the `Path` parameter set the cmdlet reads the access section of the item's security descriptor, changes it, and writes it back to disk immediately. In the `SecurityDescriptor` parameter set it changes the `Security2.FileSystemSecurity2` object in memory only; nothing reaches the file system until you pass that object to `Set-NTFSSecurityDescriptor`. + `-Path` accepts pipeline input by value and by property name through its `FullName` alias, so the output of `Get-ChildItem`, `Get-ChildItem2`, `Get-Item2`, and `Get-NTFSInheritance` binds to it. Relative paths are resolved against the current location. The cmdlet affects only the access rules; use `Disable-NTFSAuditInheritance` for the audit rules. + + + + Disable-NTFSAccessInheritance + + Path + + Specifies the path of one or more files or folders whose access inheritance is blocked. Relative paths are resolved against the current location. The parameter accepts pipeline input by value and by property name through its `FullName` alias, so the output of `Get-ChildItem`, `Get-ChildItem2`, `Get-Item2`, and `Get-NTFSInheritance` binds to it. The cmdlet does nothing when no path is supplied, either directly or from the pipeline. + + String[] + + String[] + + + None + + + PassThru + + Indicates that the cmdlet returns a `Security2.FileSystemInheritanceInfo` object for each processed item. By default, this cmdlet produces no output. The state is read after the change was attempted, so an object is also written when the change failed. + + + SwitchParameter + + + False + + + RemoveInheritedAccessRules + + Indicates that the access rules the item currently inherits are discarded. By default, when the switch is omitted, those rules are copied into the item's own DACL as explicit rules and the effective permissions stay the same. With the switch, the item keeps only the access rules that were already explicit on it, which can be none at all. + + + SwitchParameter + + + False + + + + Disable-NTFSAccessInheritance + + SecurityDescriptor + + The SecurityDescriptor parameter allows passing an security descriptor or an array or security descriptors. + 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. + This cmdlet changes the descriptor in memory only. Pass the object to `Set-NTFSSecurityDescriptor` to write the change to the file system. + + FileSystemSecurity2[] + + FileSystemSecurity2[] + + + None + + + PassThru + + Indicates that the cmdlet returns a `Security2.FileSystemInheritanceInfo` object for each processed item. By default, this cmdlet produces no output. The state is read after the change was attempted, so an object is also written when the change failed. + + + SwitchParameter + + + False + + + RemoveInheritedAccessRules + + Indicates that the access rules the item currently inherits are discarded. By default, when the switch is omitted, those rules are copied into the item's own DACL as explicit rules and the effective permissions stay the same. With the switch, the item keeps only the access rules that were already explicit on it, which can be none at all. + + + SwitchParameter + + + False + + + + + + PassThru + + Indicates that the cmdlet returns a `Security2.FileSystemInheritanceInfo` object for each processed item. By default, this cmdlet produces no output. The state is read after the change was attempted, so an object is also written when the change failed. + + SwitchParameter + + SwitchParameter + + + False + + + Path + + Specifies the path of one or more files or folders whose access inheritance is blocked. Relative paths are resolved against the current location. The parameter accepts pipeline input by value and by property name through its `FullName` alias, so the output of `Get-ChildItem`, `Get-ChildItem2`, `Get-Item2`, and `Get-NTFSInheritance` binds to it. The cmdlet does nothing when no path is supplied, either directly or from the pipeline. + + String[] + + String[] + + + None + + + RemoveInheritedAccessRules + + Indicates that the access rules the item currently inherits are discarded. By default, when the switch is omitted, those rules are copied into the item's own DACL as explicit rules and the effective permissions stay the same. With the switch, the item keeps only the access rules that were already explicit on it, which can be none at all. + + SwitchParameter + + SwitchParameter + + + False + + + SecurityDescriptor + + The SecurityDescriptor parameter allows passing an security descriptor or an array or security descriptors. + 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. + This cmdlet changes the descriptor in memory only. Pass the object to `Set-NTFSSecurityDescriptor` to write the change to the file system. + + FileSystemSecurity2[] + + FileSystemSecurity2[] + + + None + + + + + + System.String[] + + + You can pipe one or more path strings, or objects that have a `FullName` property such as the output of `Get-ChildItem2`, `Get-Item2`, and `Get-ChildItem`, to this cmdlet. + + + + + Security2.FileSystemSecurity2[] + + + You can pipe the security descriptors that `Get-NTFSSecurityDescriptor` returns to this cmdlet. + + + + + + + System.Object + + + By default this cmdlet returns no output. With `-PassThru` it writes one `Security2.FileSystemInheritanceInfo` object per item, which reports the `AccessInheritanceEnabled` and `AuditInheritanceEnabled` state after the change. + + + + + + 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. + Blocking access inheritance requires permission to change the DACL of the item, which the owner of an item always has. If the descriptor cannot be opened, the cmdlet takes ownership of the item, applies the change, and sets the previous owner back. That fallback only succeeds when the account can take ownership of the item and restore the original owner; otherwise the cmdlet writes an error and continues with the next item. + A path that does not exist produces a non-terminating error and the cmdlet continues with the remaining paths. + + + + + Example 1: Block inheritance and keep the current permissions + PS C:\> Disable-NTFSAccessInheritance -Path C:\Data\Projects + + This command protects the DACL of `C:\Data\Projects` and copies the access rules that the folder inherited from `C:\Data` into its own DACL. The effective permissions do not change, but later permission changes on `C:\Data` no longer reach the folder. + + + + - Example 2: Block inheritance and discard the inherited rules - + PS C:\> Disable-NTFSAccessInheritance -Path C:\Data\Projects -RemoveInheritedAccessRules -PassThru + + This command protects the DACL and removes the inherited access rules instead of copying them, which leaves only the rules that were already explicit on the folder. `-PassThru` returns the resulting state, in which `AccessInheritanceEnabled` is `$false`. + + + + ------- Example 3: Block inheritance on every subfolder ------- + PS C:\> Get-ChildItem2 -Path C:\Data -Directory | Disable-NTFSAccessInheritance -PassThru + + This command pipes every subfolder of `C:\Data` to the cmdlet, which binds the `FullName` property of each item to `-Path`. Each folder keeps its current permissions as explicit rules, and `-PassThru` reports the new state of each of them. + + + + ------ Example 4: Change a security descriptor in memory ------ + PS C:\> $sd = Get-NTFSSecurityDescriptor -Path C:\Data\Projects +PS C:\> Disable-NTFSAccessInheritance -SecurityDescriptor $sd +PS C:\> Set-NTFSSecurityDescriptor -SecurityDescriptor $sd + + The first two commands read the security descriptor and protect its DACL in memory, which does not change anything on disk. The third command writes the descriptor back and applies the change. + + + + + + Online Version: + https://github.com/raandree/NTFSSecurity/blob/master/Docs/Cmdlets/Disable-NTFSAccessInheritance.md + + + Enable-NTFSAccessInheritance + + + + Get-NTFSInheritance + + + + Set-NTFSInheritance + + + + Disable-NTFSAuditInheritance + + + + Get-NTFSAccess + + + + Set-NTFSSecurityDescriptor + + + + + + + Disable-NTFSAuditInheritance + Disable + NTFSAuditInheritance + + Blocks the inheritance of audit rules on a file or folder. + + + + The `Disable-NTFSAuditInheritance` cmdlet protects the system access control list (SACL) of a file or folder, so that the audit rules of the parent folder no longer apply to the item. From then on, only the audit rules stored in the item's own SACL decide which access attempts are written to the security event log. + By default, the audit rules that the item currently inherits are copied into its SACL before inheritance is blocked, so the auditing behavior stays the same. The `-RemoveInheritedAccessRules` switch discards the inherited audit rules instead of copying them, which leaves only the audit rules that were already explicit on the item. Despite its name, the switch acts on audit rules, not on access rules. + In the `Path` parameter set the cmdlet reads the audit section of the item's security descriptor, changes it, and writes it back to disk immediately. In the `SecurityDescriptor` parameter set it changes the `Security2.FileSystemSecurity2` object in memory only; nothing reaches the file system until you pass that object to `Set-NTFSSecurityDescriptor`. + Reading and writing the audit section requires the Security privilege, so run this cmdlet in an elevated session. `-Path` accepts pipeline input by value and by property name through its `FullName` alias, so the output of `Get-ChildItem`, `Get-ChildItem2`, `Get-Item2`, and `Get-NTFSInheritance` binds to it. The cmdlet affects only the audit rules; use `Disable-NTFSAccessInheritance` for the access rules. + + + + Disable-NTFSAuditInheritance + + Path + + Specifies the path of one or more files or folders whose audit inheritance is blocked. Relative paths are resolved against the current location. The parameter accepts pipeline input by value and by property name through its `FullName` alias, so the output of `Get-ChildItem`, `Get-ChildItem2`, `Get-Item2`, and `Get-NTFSInheritance` binds to it. The cmdlet does nothing when no path is supplied, either directly or from the pipeline. + + String[] + + String[] + + + None + + + PassThru + + Indicates that the cmdlet returns a `Security2.FileSystemInheritanceInfo` object for each processed item. By default, this cmdlet produces no output. The state is read after the change was attempted, so an object is also written when the change failed. + + + SwitchParameter + + + False + + + RemoveInheritedAccessRules + + Indicates that the audit rules the item currently inherits are discarded. Despite its name, the switch acts on the audit rules in the SACL, not on access rules. By default, when the switch is omitted, the inherited audit rules are copied into the item's own SACL as explicit rules and auditing continues unchanged. + + + SwitchParameter + + + False + + + + Disable-NTFSAuditInheritance + + SecurityDescriptor + + The SecurityDescriptor parameter allows passing an security descriptor or an array or security descriptors. + 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. + This cmdlet changes the descriptor in memory only. Pass the object to `Set-NTFSSecurityDescriptor` to write the change to the file system. + + FileSystemSecurity2[] + + FileSystemSecurity2[] + + + None + + + PassThru + + Indicates that the cmdlet returns a `Security2.FileSystemInheritanceInfo` object for each processed item. By default, this cmdlet produces no output. The state is read after the change was attempted, so an object is also written when the change failed. + + + SwitchParameter + + + False + + + RemoveInheritedAccessRules + + Indicates that the audit rules the item currently inherits are discarded. Despite its name, the switch acts on the audit rules in the SACL, not on access rules. By default, when the switch is omitted, the inherited audit rules are copied into the item's own SACL as explicit rules and auditing continues unchanged. + + + SwitchParameter + + + False + + + + + + PassThru + + Indicates that the cmdlet returns a `Security2.FileSystemInheritanceInfo` object for each processed item. By default, this cmdlet produces no output. The state is read after the change was attempted, so an object is also written when the change failed. + + SwitchParameter + + SwitchParameter + + + False + + + Path + + Specifies the path of one or more files or folders whose audit inheritance is blocked. Relative paths are resolved against the current location. The parameter accepts pipeline input by value and by property name through its `FullName` alias, so the output of `Get-ChildItem`, `Get-ChildItem2`, `Get-Item2`, and `Get-NTFSInheritance` binds to it. The cmdlet does nothing when no path is supplied, either directly or from the pipeline. + + String[] + + String[] + + + None + + + RemoveInheritedAccessRules + + Indicates that the audit rules the item currently inherits are discarded. Despite its name, the switch acts on the audit rules in the SACL, not on access rules. By default, when the switch is omitted, the inherited audit rules are copied into the item's own SACL as explicit rules and auditing continues unchanged. + + SwitchParameter + + SwitchParameter + + + False + + + SecurityDescriptor + + The SecurityDescriptor parameter allows passing an security descriptor or an array or security descriptors. + 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. + This cmdlet changes the descriptor in memory only. Pass the object to `Set-NTFSSecurityDescriptor` to write the change to the file system. + + FileSystemSecurity2[] + + FileSystemSecurity2[] + + + None + + + + + + System.String[] + + + You can pipe one or more path strings, or objects that have a `FullName` property such as the output of `Get-ChildItem2`, `Get-Item2`, and `Get-ChildItem`, to this cmdlet. + + + + + Security2.FileSystemSecurity2[] + + + You can pipe the security descriptors that `Get-NTFSSecurityDescriptor` returns to this cmdlet. + + + + + + + System.Object + + + By default this cmdlet returns no output. With `-PassThru` it writes one `Security2.FileSystemInheritanceInfo` object per item, which reports the `AccessInheritanceEnabled` and `AuditInheritanceEnabled` state after the change. + + + + + + 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. + The audit section of a security descriptor can only be read and written with the Security privilege (`SeSecurityPrivilege`), which an account can only use in an elevated session. Without it, the cmdlet writes a non-terminating error that reports Windows error 1314, "A required privilege is not held by the client", and the audit rules of the item stay unchanged. + If the descriptor cannot be opened because the account has no permission to the item, the cmdlet takes ownership of the item, applies the change, and sets the previous owner back. That fallback only succeeds when the account can take ownership of the item and restore the original owner; a missing Security privilege is not an access problem and is not repaired by it. + A path that does not exist produces a non-terminating error and the cmdlet continues with the remaining paths. + + + + + Example 1: Block audit inheritance and keep the current auditing + PS C:\> Disable-NTFSAuditInheritance -Path C:\Data\Projects + + This command protects the SACL of `C:\Data\Projects` and copies the audit rules that the folder inherited from `C:\Data` into its own SACL. Auditing continues to work the same way, but later changes to the audit rules of `C:\Data` no longer reach the folder. + + + + Example 2: Block audit inheritance and discard the inherited rules + PS C:\> Disable-NTFSAuditInheritance -Path C:\Data\Projects -RemoveInheritedAccessRules -PassThru + + This command protects the SACL and removes the inherited audit rules instead of copying them, so the folder is audited only by the rules that were already explicit on it. `-PassThru` returns the resulting state, in which `AuditInheritanceEnabled` is `$false`. + + + + ---- Example 3: Block audit inheritance on every subfolder ---- + PS C:\> Get-ChildItem2 -Path C:\Data -Directory | Disable-NTFSAuditInheritance + + This command pipes every subfolder of `C:\Data` to the cmdlet, which binds the `FullName` property of each item to `-Path`. Each folder keeps its current audit rules as explicit rules. + + + + ------ Example 4: Change a security descriptor in memory ------ + PS C:\> $sd = Get-NTFSSecurityDescriptor -Path C:\Data\Projects +PS C:\> Disable-NTFSAuditInheritance -SecurityDescriptor $sd +PS C:\> Set-NTFSSecurityDescriptor -SecurityDescriptor $sd + + The first two commands read the security descriptor and protect its SACL in memory, which does not change anything on disk. The third command writes the descriptor back and applies the change. + + + + + + Online Version: + https://github.com/raandree/NTFSSecurity/blob/master/Docs/Cmdlets/Disable-NTFSAuditInheritance.md + + + Enable-NTFSAuditInheritance + + + + Get-NTFSInheritance + + + + Set-NTFSInheritance + + + + Disable-NTFSAccessInheritance + + + + Get-NTFSAudit + + + + Set-NTFSSecurityDescriptor + + + + + + + Disable-Privileges + Disable + Privileges + + Disables the file system privileges in the access token of the current PowerShell process. + + + + The `Disable-Privileges` cmdlet disables the Take Ownership, Restore, Backup, and Security privileges in the access token of the current PowerShell process. It is the counterpart of `Enable-Privileges`, which leaves those privileges enabled for the rest of the session. + Before it changes anything, the cmdlet checks whether at least one of the Take Ownership, Restore, and Backup privileges is currently enabled. If none of them is, it writes a non-terminating error that reports that the privileges are not enabled and does nothing. This is what happens in a session that never enabled the privileges or that does not hold them at all. A privilege that cannot be disabled produces a warning, and the cmdlet continues with the remaining privileges. + The change affects nothing but the access token of the PowerShell process that runs the cmdlet. Disabling a privilege does not remove it from the account; it only takes it out of use until something enables it again, which the file system cmdlets of the module do on their own while they run. + + + + Disable-Privileges + + PassThru + + Indicates that the cmdlet returns the privileges of the current process after disabling them. Without this parameter, the cmdlet produces no output. + + + SwitchParameter + + + False + + + + + + PassThru + + Indicates that the cmdlet returns the privileges of the current process after disabling them. Without this parameter, the cmdlet produces no output. + + SwitchParameter + + SwitchParameter + + + False + + + + + + None + + + This cmdlet does not accept pipeline input. + + + + + + + ProcessPrivileges.PrivilegeAndAttributes + + + With `-PassThru`, the cmdlet writes the privilege collection of the current process. The pipeline enumerates it into one `ProcessPrivileges.PrivilegeAndAttributes` object per privilege, each with a `Privilege`, a `PrivilegeAttributes`, and a `PrivilegeState` property. Without `-PassThru`, the cmdlet writes nothing. + + + + + + When the module setting `EnablePrivileges` is `$true` (the default in the `PrivateData` section of NTFSSecurity.psd1), the file system cmdlets of the module try to enable the Backup, Restore, Take Ownership, and Security privileges while they run and disable the privileges they enabled when they finish. You therefore need `Disable-Privileges` only after an explicit `Enable-Privileges`. These privileges are only available in an elevated session of an account that holds them, such as a member of the local Administrators group. + + + + + --- Example 1: Disable the privileges in the current session --- + PS C:\> Disable-Privileges + + This command disables the Take Ownership, Restore, Backup, and Security privileges in the current PowerShell process. + + + + --- Example 2: Disable the privileges and return the result --- + PS C:\> Disable-Privileges -PassThru + + This command disables the privileges and returns all privileges of the current process, so you can confirm their new state right away. + + + + Example 3: Enable the privileges for a task and turn them off afterwards + PS C:\> Enable-Privileges +PS C:\> Set-NTFSOwner -Path C:\Data -Account 'BUILTIN\Administrators' +PS C:\> Disable-Privileges + + The privileges stay enabled while the owner of the folder is changed and are turned off again by the last command, which returns the session to its normal rights. + + + + Example 4: Check the state of the privileges after disabling them + PS C:\> Disable-Privileges +PS C:\> Get-Privileges | Where-Object { $_.Privilege -in 'Backup', 'Restore', 'TakeOwnership', 'Security' } + + The second command lists the four file system privileges with their current state, which shows that they are no longer enabled. + + + + + + Online Version: + https://github.com/raandree/NTFSSecurity/blob/master/Docs/Cmdlets/Disable-Privileges.md + + + Enable-Privileges + + + + Get-Privileges + + + + Set-NTFSOwner + + + + Get-NTFSSecurityDescriptor + + + + + + + Enable-NTFSAccessInheritance + Enable + NTFSAccessInheritance + + Restores the inheritance of access rules on a file or folder. + + + + The `Enable-NTFSAccessInheritance` cmdlet removes the protection from the discretionary access control list (DACL) of a file or folder, so that the item inherits access rules from its parent folder again. + By default, the access rules that are stored directly on the item are kept, and the inherited rules are added to them. An item that was processed by `Disable-NTFSAccessInheritance` therefore ends up with the inherited rules twice: once as the explicit copies that were created when inheritance was blocked, and once as true inherited rules. The `-RemoveExplicitAccessRules` switch deletes every access rule that is stored directly on the item, which leaves only the inherited rules and restores the permission model of the parent folder. + In the `Path` parameter set the cmdlet reads the access section of the item's security descriptor, changes it, and writes it back to disk immediately. In the `SecurityDescriptor` parameter set it changes the `Security2.FileSystemSecurity2` object in memory only; nothing reaches the file system until you pass that object to `Set-NTFSSecurityDescriptor`. + `-Path` accepts pipeline input by value and by property name through its `FullName` alias, so the output of `Get-ChildItem`, `Get-ChildItem2`, `Get-Item2`, and `Get-NTFSInheritance` binds to it. Relative paths are resolved against the current location. The cmdlet affects only the access rules; use `Enable-NTFSAuditInheritance` for the audit rules. + + + + Enable-NTFSAccessInheritance + + Path + + Specifies the path of one or more files or folders whose access inheritance is restored. Relative paths are resolved against the current location. The parameter accepts pipeline input by value and by property name through its `FullName` alias, so the output of `Get-ChildItem`, `Get-ChildItem2`, `Get-Item2`, and `Get-NTFSInheritance` binds to it. The cmdlet does nothing when no path is supplied, either directly or from the pipeline. + + String[] + + String[] + + + None + + + PassThru + + Indicates that the cmdlet returns a `Security2.FileSystemInheritanceInfo` object for each processed item. By default, this cmdlet produces no output. The state is read after the change was attempted, so an object is also written when the change failed. + + + SwitchParameter + + + False + + + RemoveExplicitAccessRules + + Indicates that every access rule stored directly on the item is removed when inheritance is restored, so that the item ends up with the inherited rules only. By default, when the switch is omitted, the explicit rules are kept and the inherited rules are added to them, which usually duplicates the rules that `Disable-NTFSAccessInheritance` copied earlier. + + + SwitchParameter + + + False + + + + Enable-NTFSAccessInheritance + + SecurityDescriptor + + The SecurityDescriptor parameter allows passing an security descriptor or an array or security descriptors. + 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. + This cmdlet changes the descriptor in memory only. Pass the object to `Set-NTFSSecurityDescriptor` to write the change to the file system. + + FileSystemSecurity2[] + + FileSystemSecurity2[] + + + None + + + PassThru + + Indicates that the cmdlet returns a `Security2.FileSystemInheritanceInfo` object for each processed item. By default, this cmdlet produces no output. The state is read after the change was attempted, so an object is also written when the change failed. + + + SwitchParameter + + + False + + + RemoveExplicitAccessRules + + Indicates that every access rule stored directly on the item is removed when inheritance is restored, so that the item ends up with the inherited rules only. By default, when the switch is omitted, the explicit rules are kept and the inherited rules are added to them, which usually duplicates the rules that `Disable-NTFSAccessInheritance` copied earlier. + + + SwitchParameter + + + False + + + + + + PassThru + + Indicates that the cmdlet returns a `Security2.FileSystemInheritanceInfo` object for each processed item. By default, this cmdlet produces no output. The state is read after the change was attempted, so an object is also written when the change failed. + + SwitchParameter + + SwitchParameter + + + False + + + Path + + Specifies the path of one or more files or folders whose access inheritance is restored. Relative paths are resolved against the current location. The parameter accepts pipeline input by value and by property name through its `FullName` alias, so the output of `Get-ChildItem`, `Get-ChildItem2`, `Get-Item2`, and `Get-NTFSInheritance` binds to it. The cmdlet does nothing when no path is supplied, either directly or from the pipeline. + + String[] + + String[] + + + None + + + RemoveExplicitAccessRules + + Indicates that every access rule stored directly on the item is removed when inheritance is restored, so that the item ends up with the inherited rules only. By default, when the switch is omitted, the explicit rules are kept and the inherited rules are added to them, which usually duplicates the rules that `Disable-NTFSAccessInheritance` copied earlier. + + SwitchParameter + + SwitchParameter + + + False + + + SecurityDescriptor + + The SecurityDescriptor parameter allows passing an security descriptor or an array or security descriptors. + 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. + This cmdlet changes the descriptor in memory only. Pass the object to `Set-NTFSSecurityDescriptor` to write the change to the file system. + + FileSystemSecurity2[] + + FileSystemSecurity2[] + + + None + + + + + + System.String[] + + + You can pipe one or more path strings, or objects that have a `FullName` property such as the output of `Get-ChildItem2`, `Get-Item2`, and `Get-ChildItem`, to this cmdlet. + + + + + Security2.FileSystemSecurity2[] + + + You can pipe the security descriptors that `Get-NTFSSecurityDescriptor` returns to this cmdlet. + + + + + + + System.Object + + + By default this cmdlet returns no output. With `-PassThru` it writes one `Security2.FileSystemInheritanceInfo` object per item, which reports the `AccessInheritanceEnabled` and `AuditInheritanceEnabled` state after the change. + + + + + + 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. + Restoring access inheritance requires permission to change the DACL of the item, which the owner of an item always has. If the descriptor cannot be opened, the cmdlet takes ownership of the item, applies the change, and sets the previous owner back. That fallback only succeeds when the account can take ownership of the item and restore the original owner; otherwise the cmdlet writes an error and continues with the next item. + A path that does not exist produces a non-terminating error and the cmdlet continues with the remaining paths. + + + + + -- Example 1: Restore inheritance and keep the explicit rules -- + PS C:\> Enable-NTFSAccessInheritance -Path C:\Data\Projects + + This command lets `C:\Data\Projects` inherit the access rules of `C:\Data` again. The rules that are stored directly on the folder stay in place and are added to the inherited ones. + + + + -- Example 2: Restore inheritance and drop the explicit rules -- + PS C:\> Enable-NTFSAccessInheritance -Path C:\Data\Projects -RemoveExplicitAccessRules -PassThru + + This command removes every access rule that is stored directly on the folder and lets it inherit from `C:\Data` again, so the folder ends up with exactly the permissions of its parent. `-PassThru` returns the resulting state, in which `AccessInheritanceEnabled` is `$true`. + + + + ------------ Example 3: Repair a whole folder tree ------------ + PS C:\> Get-ChildItem2 -Path C:\Data -Recurse | Get-NTFSInheritance | Where-Object { -not $_.AccessInheritanceEnabled } | Enable-NTFSAccessInheritance -RemoveExplicitAccessRules + + This command finds every item below `C:\Data` whose access inheritance is blocked and restores it. `Get-NTFSInheritance` writes objects with a `FullName` property, which binds to `-Path`. + + + + ------ Example 4: Change a security descriptor in memory ------ + PS C:\> $sd = Get-NTFSSecurityDescriptor -Path C:\Data\Projects +PS C:\> Enable-NTFSAccessInheritance -SecurityDescriptor $sd -RemoveExplicitAccessRules +PS C:\> Set-NTFSSecurityDescriptor -SecurityDescriptor $sd + + The first two commands read the security descriptor and restore inheritance in memory, which does not change anything on disk. The third command writes the descriptor back and applies the change. + + + + + + Online Version: + https://github.com/raandree/NTFSSecurity/blob/master/Docs/Cmdlets/Enable-NTFSAccessInheritance.md + + + Disable-NTFSAccessInheritance + + + + Get-NTFSInheritance + + + + Set-NTFSInheritance + + + + Enable-NTFSAuditInheritance + + + + Get-NTFSAccess + + + + Set-NTFSSecurityDescriptor + + + + + + + Enable-NTFSAuditInheritance + Enable + NTFSAuditInheritance + + Restores the inheritance of audit rules on a file or folder. + + + + The `Enable-NTFSAuditInheritance` cmdlet removes the protection from the system access control list (SACL) of a file or folder, so that the item inherits audit rules from its parent folder again. + By default, the audit rules that are stored directly on the item are kept, and the inherited rules are added to them. An item that was processed by `Disable-NTFSAuditInheritance` therefore ends up with the inherited audit rules twice: once as the explicit copies that were created when inheritance was blocked, and once as true inherited rules. The `-RemoveExplicitAccessRules` switch deletes every audit rule that is stored directly on the item, which leaves only the inherited ones. Despite its name, the switch acts on audit rules, not on access rules. + In the `Path` parameter set the cmdlet reads the audit section of the item's security descriptor, changes it, and writes it back to disk immediately. In the `SecurityDescriptor` parameter set it changes the `Security2.FileSystemSecurity2` object in memory only; nothing reaches the file system until you pass that object to `Set-NTFSSecurityDescriptor`. + Reading and writing the audit section requires the Security privilege, so run this cmdlet in an elevated session. `-Path` accepts pipeline input by value and by property name through its `FullName` alias, so the output of `Get-ChildItem`, `Get-ChildItem2`, `Get-Item2`, and `Get-NTFSInheritance` binds to it. The cmdlet affects only the audit rules; use `Enable-NTFSAccessInheritance` for the access rules. + + + + Enable-NTFSAuditInheritance + + Path + + Specifies the path of one or more files or folders whose audit inheritance is restored. Relative paths are resolved against the current location. The parameter accepts pipeline input by value and by property name through its `FullName` alias, so the output of `Get-ChildItem`, `Get-ChildItem2`, `Get-Item2`, and `Get-NTFSInheritance` binds to it. The cmdlet does nothing when no path is supplied, either directly or from the pipeline. + + String[] + + String[] + + + None + + + PassThru + + Indicates that the cmdlet returns a `Security2.FileSystemInheritanceInfo` object for each processed item. By default, this cmdlet produces no output. The state is read after the change was attempted, so an object is also written when the change failed. + + + SwitchParameter + + + False + + + RemoveExplicitAccessRules + + Indicates that every audit rule stored directly on the item is removed when inheritance is restored, so that the item ends up with the inherited audit rules only. Despite its name, the switch acts on the audit rules in the SACL, not on access rules. By default, when the switch is omitted, the explicit audit rules are kept and the inherited rules are added to them, which usually duplicates the rules that `Disable-NTFSAuditInheritance` copied earlier. + + + SwitchParameter + + + False + + + + Enable-NTFSAuditInheritance + + SecurityDescriptor + + The SecurityDescriptor parameter allows passing an security descriptor or an array or security descriptors. + 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. + This cmdlet changes the descriptor in memory only. Pass the object to `Set-NTFSSecurityDescriptor` to write the change to the file system. + + FileSystemSecurity2[] + + FileSystemSecurity2[] + + + None + + + PassThru + + Indicates that the cmdlet returns a `Security2.FileSystemInheritanceInfo` object for each processed item. By default, this cmdlet produces no output. The state is read after the change was attempted, so an object is also written when the change failed. + + + SwitchParameter + + + False + + + RemoveExplicitAccessRules + + Indicates that every audit rule stored directly on the item is removed when inheritance is restored, so that the item ends up with the inherited audit rules only. Despite its name, the switch acts on the audit rules in the SACL, not on access rules. By default, when the switch is omitted, the explicit audit rules are kept and the inherited rules are added to them, which usually duplicates the rules that `Disable-NTFSAuditInheritance` copied earlier. + + + SwitchParameter + + + False + + + + + + PassThru + + Indicates that the cmdlet returns a `Security2.FileSystemInheritanceInfo` object for each processed item. By default, this cmdlet produces no output. The state is read after the change was attempted, so an object is also written when the change failed. + + SwitchParameter + + SwitchParameter + + + False + + + Path + + Specifies the path of one or more files or folders whose audit inheritance is restored. Relative paths are resolved against the current location. The parameter accepts pipeline input by value and by property name through its `FullName` alias, so the output of `Get-ChildItem`, `Get-ChildItem2`, `Get-Item2`, and `Get-NTFSInheritance` binds to it. The cmdlet does nothing when no path is supplied, either directly or from the pipeline. + + String[] + + String[] + + + None + + + RemoveExplicitAccessRules + + Indicates that every audit rule stored directly on the item is removed when inheritance is restored, so that the item ends up with the inherited audit rules only. Despite its name, the switch acts on the audit rules in the SACL, not on access rules. By default, when the switch is omitted, the explicit audit rules are kept and the inherited rules are added to them, which usually duplicates the rules that `Disable-NTFSAuditInheritance` copied earlier. + + SwitchParameter + + SwitchParameter + + + False + + + SecurityDescriptor + + The SecurityDescriptor parameter allows passing an security descriptor or an array or security descriptors. + 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. + This cmdlet changes the descriptor in memory only. Pass the object to `Set-NTFSSecurityDescriptor` to write the change to the file system. + + FileSystemSecurity2[] + + FileSystemSecurity2[] + + + None + + + + + + System.String[] + + + You can pipe one or more path strings, or objects that have a `FullName` property such as the output of `Get-ChildItem2`, `Get-Item2`, and `Get-ChildItem`, to this cmdlet. + + + + + Security2.FileSystemSecurity2[] + + + You can pipe the security descriptors that `Get-NTFSSecurityDescriptor` returns to this cmdlet. + + + + + + + System.Object + + + By default this cmdlet returns no output. With `-PassThru` it writes one `Security2.FileSystemInheritanceInfo` object per item, which reports the `AccessInheritanceEnabled` and `AuditInheritanceEnabled` state after the change. + + + + + + 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. + The audit section of a security descriptor can only be read and written with the Security privilege (`SeSecurityPrivilege`), which an account can only use in an elevated session. Without it, the cmdlet writes a non-terminating error that reports Windows error 1314, "A required privilege is not held by the client", and the audit rules of the item stay unchanged. + If the descriptor cannot be opened because the account has no permission to the item, the cmdlet takes ownership of the item, applies the change, and sets the previous owner back. That fallback only succeeds when the account can take ownership of the item and restore the original owner; a missing Security privilege is not an access problem and is not repaired by it. + A path that does not exist produces a non-terminating error and the cmdlet continues with the remaining paths. + + + + + Example 1: Restore audit inheritance and keep the explicit rules + PS C:\> Enable-NTFSAuditInheritance -Path C:\Data\Projects + + This command lets `C:\Data\Projects` inherit the audit rules of `C:\Data` again. The audit rules that are stored directly on the folder stay in place and are added to the inherited ones. + + + + Example 2: Restore audit inheritance and drop the explicit rules + PS C:\> Enable-NTFSAuditInheritance -Path C:\Data\Projects -RemoveExplicitAccessRules -PassThru + + This command removes every audit rule that is stored directly on the folder and lets it inherit from `C:\Data` again, so the folder is audited exactly like its parent. `-PassThru` returns the resulting state, in which `AuditInheritanceEnabled` is `$true`. + + + + ------------ Example 3: Repair a whole folder tree ------------ + PS C:\> Get-ChildItem2 -Path C:\Data -Recurse | Get-NTFSInheritance | Where-Object { $_.AuditInheritanceEnabled -eq $false } | Enable-NTFSAuditInheritance -RemoveExplicitAccessRules + + This command finds every item below `C:\Data` whose audit inheritance is blocked and restores it. The comparison with `$false` is deliberate: `AuditInheritanceEnabled` is `$null` for items whose audit section could not be read, and those items are skipped instead of being processed. + + + + ------ Example 4: Change a security descriptor in memory ------ + PS C:\> $sd = Get-NTFSSecurityDescriptor -Path C:\Data\Projects +PS C:\> Enable-NTFSAuditInheritance -SecurityDescriptor $sd -RemoveExplicitAccessRules +PS C:\> Set-NTFSSecurityDescriptor -SecurityDescriptor $sd + + The first two commands read the security descriptor and restore audit inheritance in memory, which does not change anything on disk. The third command writes the descriptor back and applies the change. + + + + + + Online Version: + https://github.com/raandree/NTFSSecurity/blob/master/Docs/Cmdlets/Enable-NTFSAuditInheritance.md + + + Disable-NTFSAuditInheritance + + + + Get-NTFSInheritance + + + + Set-NTFSInheritance + + + + Enable-NTFSAccessInheritance + + + + Get-NTFSAudit + + + + Set-NTFSSecurityDescriptor + + + + + + + Enable-Privileges + Enable + Privileges + + Enables the file system privileges in the access token of the current PowerShell process. + + + + The `Enable-Privileges` cmdlet enables the Take Ownership, Restore, Backup, and Security privileges in the access token of the current PowerShell process. Together these privileges let the other cmdlets of the module read and change the security of files and folders that your account has no permissions on, take ownership of them, and work with audit entries. + The change affects nothing but the access token of the PowerShell process that runs the cmdlet. Other processes, other PowerShell sessions, and the computer configuration stay untouched, and the privileges are gone as soon as the process ends. + Unlike the other cmdlets of the module, `Enable-Privileges` leaves the privileges enabled after it finishes, which is the point of the cmdlet: the file system cmdlets enable the same privileges only for the duration of a single call. Calling `Enable-Privileges` is therefore useful when you want the privileges to stay enabled for a whole sequence of commands, or when you turned the automatic handling off by setting `EnablePrivileges` to `$false` in the `PrivateData` section of NTFSSecurity.psd1. When you call the cmdlet yourself, it enables the privileges regardless of that setting. + A privilege can only be enabled when it is present in the access token, which in practice means an elevated session of an account that holds the privilege, such as a member of the local Administrators group. When all four privileges are enabled, the cmdlet writes a verbose message that names them; otherwise it writes a non-terminating error that reports that the requested privileges could not be enabled and that the cmdlets of the module will only work on resources you have access to. + + + + Enable-Privileges + + PassThru + + Indicates that the cmdlet returns the privileges of the current process after enabling them. Without this parameter, the cmdlet produces no output. + + + SwitchParameter + + + False + + + + + + PassThru + + Indicates that the cmdlet returns the privileges of the current process after enabling them. Without this parameter, the cmdlet produces no output. + + SwitchParameter + + SwitchParameter + + + False + + + + + + None + + + This cmdlet does not accept pipeline input. + + + + + + + ProcessPrivileges.PrivilegeAndAttributes + + + With `-PassThru`, the cmdlet writes the privilege collection of the current process. The pipeline enumerates it into one `ProcessPrivileges.PrivilegeAndAttributes` object per privilege, each with a `Privilege`, a `PrivilegeAttributes`, and a `PrivilegeState` property. Without `-PassThru`, the cmdlet writes nothing. + + + + + + When the module setting `EnablePrivileges` is `$true` (the default in the `PrivateData` section of NTFSSecurity.psd1), the file system cmdlets of the module try to enable the Backup, Restore, Take Ownership, and Security privileges while they run and disable the privileges they enabled when they finish. `Enable-Privileges` enables the same privileges but keeps them enabled, so they remain available to every later command in the session until you run `Disable-Privileges` or close the session. These privileges are only available in an elevated session of an account that holds them, such as a member of the local Administrators group. + The cmdlet reads the `EnablePrivileges` entry from the `PrivateData` section of the module manifest. If that entry is missing or cannot be read as a Boolean value, the cmdlet throws a parse error that points to the manifest. + + + + + --- Example 1: Enable the privileges for the current session --- + PS C:\> Enable-Privileges + + This command enables the Take Ownership, Restore, Backup, and Security privileges in the current PowerShell process and leaves them enabled. + + + + ---- Example 2: Enable the privileges and check the result ---- + PS C:\> Enable-Privileges +PS C:\> Get-Privileges | Where-Object { $_.Privilege -in 'Backup', 'Restore', 'TakeOwnership', 'Security' } + + The second command lists the four file system privileges with their current state, which confirms whether the session now holds them in the enabled state. + + + + - Example 3: Enable the privileges and return them in one step - + PS C:\> Enable-Privileges -PassThru + + This command enables the privileges and returns all privileges of the current process, so you can see the result without a second call to `Get-Privileges`. + + + + Example 4: Work with enabled privileges and turn them off afterwards + PS C:\> Enable-Privileges +PS C:\> Get-ChildItem2 -Path C:\Data -Recurse | Get-NTFSOwner +PS C:\> Disable-Privileges + + The privileges stay enabled while the folder tree is read and are turned off again by the last command. Running `Disable-Privileges` when you are done keeps the session at its normal rights. + + + + + + Online Version: + https://github.com/raandree/NTFSSecurity/blob/master/Docs/Cmdlets/Enable-Privileges.md + + + Disable-Privileges + + + + Get-Privileges + + + + Set-NTFSOwner + + + + Get-NTFSSecurityDescriptor + + + + + + + Get-ChildItem2 + Get + ChildItem2 + + Gets the files and folders in one or more folders, including paths longer than 260 characters. + + + + The `Get-ChildItem2` cmdlet lists the files and folders in the folders that you specify with `-Path`. It returns an `Alphaleonis.Win32.Filesystem.FileInfo` object for every file and an `Alphaleonis.Win32.Filesystem.DirectoryInfo` object for every folder. The cmdlet is the long-path counterpart of the built-in `Get-ChildItem` cmdlet: it enumerates the file system through the AlphaFS library (`Alphaleonis.Win32.Filesystem`) instead of `System.IO`, so it also returns items whose path is longer than the 260-character `MAX_PATH` limit. + If you omit `-Path`, the cmdlet lists the current location. Relative paths and the `.` and `..` notations are resolved against the current location. Each path must name a folder, and wildcard characters are not supported. The parameter accepts pipeline input by value and by the property name `FullName`, so you can pipe folders from `Get-ChildItem2` or `Get-Item2` into another `Get-ChildItem2` call, and you can pipe the result into `Get-NTFSAccess` and the other NTFSSecurity cmdlets. + By default the cmdlet returns the immediate content of each folder and omits hidden items. Use `-Recurse` to walk the whole tree, `-Depth` to limit how deep the recursion goes, `-Filter` to restrict the result by name, `-Directory` or `-File` to restrict it by item type, and `-Force`, `-Hidden`, `-System`, `-ReadOnly`, or `-Attributes` to restrict it by file attributes. + Two settings in the `PrivateData` section of the module manifest change the objects that this cmdlet emits. `GetFileSystemModeProperty` adds the `Mode` property, which shows the directory, archive, read-only, hidden, and system attributes in `darhs` notation. `IdentifyHardLinks` adds a `HardLinkCount` property to every file object. Both are `$true` by default and are read once when the cmdlet starts. + A folder that the cmdlet cannot read produces a non-terminating error, and the enumeration continues with the next folder. If a folder cannot be opened while `-Recurse` looks for subfolders, the cmdlet reports the problem as a verbose message instead, so run the command with the `-Verbose` common parameter if you need to know which branches were skipped. + + + + Get-ChildItem2 + + Path + + Specifies the folders whose content you want to list. Relative paths are resolved against the current location, and wildcard characters are not supported. If you omit this parameter, the cmdlet lists the current location. A value that points to a file instead of a folder produces an error. + + String[] + + String[] + + + None + + + Filter + + Specifies a name pattern that an item must match to be returned. The pattern supports the ` ` and `?` wildcard characters, and the match ignores case. The default value is ` `, which returns every item. The pattern is applied to the name of each item, not to its path, and during a recursive listing it restricts only the returned items; the cmdlet still descends into every subfolder. + + String + + String + + + * + + + Attributes + + Specifies a set of file attributes. The cmdlet returns only the items that have all the attributes you list; separate several values with commas, as in `-Attributes Hidden, System`. When you use this parameter, the cmdlet ignores `-Force`, `-Hidden`, `-System`, and `-ReadOnly`, and it returns matching hidden items without `-Force`. + + + ReadOnly + Hidden + System + Directory + Archive + Device + Normal + Temporary + SparseFile + ReparsePoint + Compressed + Offline + NotContentIndexed + Encrypted + IntegrityStream + NoScrubData + + FileAttributes + + FileAttributes + + + None + + + Depth + + Specifies how many additional levels of subfolders a recursive listing covers. `-Depth` takes effect only together with `-Recurse`: `-Depth 0` limits the result to the content of the folders in `-Path`, `-Depth 1` adds one more level of subfolders, and so on. If you omit the parameter, `-Recurse` walks the entire tree. + + Int32 + + Int32 + + + None + + + Directory + + Indicates that the cmdlet returns only folders. If you specify `-Directory` and `-File` together, `-Directory` wins. The parameter restricts the returned items only; `-Recurse` still descends into every subfolder. + + + SwitchParameter + + + False + + + File + + Indicates that the cmdlet returns only files. The parameter is ignored if you also specify `-Directory`. + + + SwitchParameter + + + False + + + Force + + Indicates that the cmdlet also returns hidden items. Without `-Force`, hidden items are left out of the result. The parameter is ignored when you use `-Attributes`. + + + SwitchParameter + + + False + + + Hidden + + Indicates that the cmdlet returns only hidden items. You do not need `-Force` in addition, because `-Hidden` implies it. + + + SwitchParameter + + + False + + + ReadOnly + + Indicates that the cmdlet returns only items that have the read-only attribute. Hidden read-only items appear in the result only if you add `-Force`. + + + SwitchParameter + + + False + + + Recurse + + Indicates that the cmdlet lists the content of all subfolders as well. Without `-Recurse`, only the immediate content of each folder in `-Path` is returned. Use `-Depth` to limit how far the recursion goes. + + + SwitchParameter + + + False + + + SkipMountPoints + + Indicates that the cmdlet does not descend into volume mount points. The mount point itself is still returned as an item of its parent folder. The parameter takes effect only together with `-Recurse`. + + + SwitchParameter + + + False + + + SkipSymbolicLinks + + Indicates that the cmdlet does not descend into folders that are symbolic links. The link itself is still returned as an item of its parent folder. The parameter takes effect only together with `-Recurse`, and it protects a recursive listing against loops that symbolic links can create. + + + SwitchParameter + + + False + + + System + + Indicates that the cmdlet returns only items that have the system attribute. System files are often hidden as well, so combine this parameter with `-Force` or `-Hidden` to see them. + + + SwitchParameter + + + False + + + + + + Attributes + + Specifies a set of file attributes. The cmdlet returns only the items that have all the attributes you list; separate several values with commas, as in `-Attributes Hidden, System`. When you use this parameter, the cmdlet ignores `-Force`, `-Hidden`, `-System`, and `-ReadOnly`, and it returns matching hidden items without `-Force`. + + FileAttributes + + FileAttributes + + + None + + + Depth + + Specifies how many additional levels of subfolders a recursive listing covers. `-Depth` takes effect only together with `-Recurse`: `-Depth 0` limits the result to the content of the folders in `-Path`, `-Depth 1` adds one more level of subfolders, and so on. If you omit the parameter, `-Recurse` walks the entire tree. + + Int32 + + Int32 + + + None + + + Directory + + Indicates that the cmdlet returns only folders. If you specify `-Directory` and `-File` together, `-Directory` wins. The parameter restricts the returned items only; `-Recurse` still descends into every subfolder. + + SwitchParameter + + SwitchParameter + + + False + + + File + + Indicates that the cmdlet returns only files. The parameter is ignored if you also specify `-Directory`. + + SwitchParameter + + SwitchParameter + + + False + + + Filter + + Specifies a name pattern that an item must match to be returned. The pattern supports the ` ` and `?` wildcard characters, and the match ignores case. The default value is ` `, which returns every item. The pattern is applied to the name of each item, not to its path, and during a recursive listing it restricts only the returned items; the cmdlet still descends into every subfolder. + + String + + String + + + * + + + Force + + Indicates that the cmdlet also returns hidden items. Without `-Force`, hidden items are left out of the result. The parameter is ignored when you use `-Attributes`. + + SwitchParameter + + SwitchParameter + + + False + + + Hidden + + Indicates that the cmdlet returns only hidden items. You do not need `-Force` in addition, because `-Hidden` implies it. + + SwitchParameter + + SwitchParameter + + + False + + + Path + + Specifies the folders whose content you want to list. Relative paths are resolved against the current location, and wildcard characters are not supported. If you omit this parameter, the cmdlet lists the current location. A value that points to a file instead of a folder produces an error. + + String[] + + String[] + + + None + + + ReadOnly + + Indicates that the cmdlet returns only items that have the read-only attribute. Hidden read-only items appear in the result only if you add `-Force`. + + SwitchParameter + + SwitchParameter + + + False + + + Recurse + + Indicates that the cmdlet lists the content of all subfolders as well. Without `-Recurse`, only the immediate content of each folder in `-Path` is returned. Use `-Depth` to limit how far the recursion goes. + + SwitchParameter + + SwitchParameter + + + False + + + SkipMountPoints + + Indicates that the cmdlet does not descend into volume mount points. The mount point itself is still returned as an item of its parent folder. The parameter takes effect only together with `-Recurse`. + + SwitchParameter + + SwitchParameter + + + False + + + SkipSymbolicLinks + + Indicates that the cmdlet does not descend into folders that are symbolic links. The link itself is still returned as an item of its parent folder. The parameter takes effect only together with `-Recurse`, and it protects a recursive listing against loops that symbolic links can create. + + SwitchParameter + + SwitchParameter + + + False + + + System + + Indicates that the cmdlet returns only items that have the system attribute. System files are often hidden as well, so combine this parameter with `-Force` or `-Hidden` to see them. + + SwitchParameter + + SwitchParameter + + + False + + + + + + System.String[] + + + You can pipe one or more folder paths to this cmdlet, either as strings or as objects that have a `FullName` property, such as the output of `Get-ChildItem2` or `Get-Item2`. + + + + + + + Alphaleonis.Win32.Filesystem.FileInfo + + + The cmdlet returns this object for every file it finds. Depending on the module settings, the object carries the additional properties `Mode` and `HardLinkCount`. + + + + + Alphaleonis.Win32.Filesystem.DirectoryInfo + + + The cmdlet returns this object for every folder it finds. Depending on the module settings, the object carries the additional property `Mode`. + + + + + + `Get-ChildItem2` enumerates the file system through the AlphaFS library (`Alphaleonis.Win32.Filesystem`), which is why it returns items whose path exceeds the 260-character `MAX_PATH` limit that the built-in `Get-ChildItem` cmdlet is bound to. The objects are AlphaFS objects, not `System.IO` objects, and the other NTFSSecurity cmdlets accept them directly because their `-Path` parameters have the alias `FullName`. + The module defines the alias `dir2` for this cmdlet. + The `PrivateData` section of the module manifest `NTFSSecurity.psd1` contains two settings that this cmdlet reads when it starts. `GetFileSystemModeProperty` adds the calculated `Mode` property to every item. `IdentifyHardLinks` adds the `HardLinkCount` property to every file, which requires an extra call into the file system for each file and therefore slows down large listings noticeably. Set either value to `$false` in the manifest and import the module again if you prefer the faster enumeration over the additional properties. + A folder that cannot be read produces a non-terminating error with the ID `DirUnauthorizedAccessError` for an access denial or `DirUnspecifiedError` for any other failure, and a path that does not exist produces the error `FileNotFound`. In each case the cmdlet continues with the next path. Failures that occur while `-Recurse` collects the subfolders of a folder are reported as verbose messages only, not as errors. + + + + + ---- Example 1: Find files with a path longer than MAX_PATH ---- + PS C:\> Get-ChildItem2 -Path C:\Data -Recurse -File | Where-Object { $_.FullName.Length -gt 260 } + + Walks the whole folder tree below `C:\Data` and returns the files whose full path is too long for the built-in `Get-ChildItem` cmdlet. + + + + ------ Example 2: Read the permissions of every subfolder ------ + PS C:\> Get-ChildItem2 -Path C:\Data -Recurse -Directory | Get-NTFSAccess + + Lists every subfolder of `C:\Data` and pipes the objects to `Get-NTFSAccess`, which binds their `FullName` property to its own `-Path` parameter and returns the access control entries of each folder. + + + + ------ Example 3: Limit the depth of a recursive listing ------ + PS C:\> Get-ChildItem2 -Path C:\Data -Recurse -Depth 1 -Filter '*.log' + + Returns the log files in `C:\Data` and in its immediate subfolders. Without `-Depth`, the command would descend through the entire tree. + + + + ------------- Example 4: List hidden system files ------------- + PS C:\> dir2 -Path C:\Data -Attributes Hidden, System + + Uses the `dir2` alias and returns the items of `C:\Data` that have both the hidden and the system attribute. + + + + + + Online Version: + https://github.com/raandree/NTFSSecurity/blob/master/Docs/Cmdlets/Get-ChildItem2.md + + + Get-Item2 + + + + Copy-Item2 + + + + Move-Item2 + + + + Remove-Item2 + + + + Test-Path2 + + + + Get-NTFSAccess + + + + + + + Get-DiskSpace + Get + DiskSpace + + Gets size, free space, and cluster information for the volumes of a computer. + + + + The `Get-DiskSpace` cmdlet returns one `DiskSpaceInfo` object per volume. The object describes how large the volume is, how much space is free, and how the volume is organized into sectors and clusters. + When you omit `-DriveLetter`, the cmdlet enumerates all volumes of the computer, including volumes that have no drive letter, and returns the ones that report a total size greater than zero. Volumes that report a size of zero, such as an empty removable drive, are skipped silently, and a volume whose details cannot be read produces a warning instead of an object. + Each returned object exposes the following properties: + - `DriveName`: the volume the object describes. + - `TotalNumberOfBytes`, `TotalNumberOfFreeBytes`, and `FreeBytesAvailable`: the size of the volume, the free space on it, and the free space that is available to the account that runs the cmdlet, all as 64-bit byte counts. + - `TotalSizeUnitSize`, `UsedSpaceUnitSize`, and `AvailableFreeSpaceUnitSize`: the same figures formatted as readable strings. + - `UsedSpacePercent` and `AvailableFreeSpacePercent`: used and free space as formatted percentage strings. + - `BytesPerSector`, `SectorsPerCluster`, `ClusterSize`, `TotalNumberOfClusters`, and `NumberOfFreeClusters`: the sector and cluster layout of the volume. + + The percentage and unit-size properties are strings that are meant for display. Use the byte and cluster properties when you need to calculate or compare values. + The cmdlet only reads volume information and does not change anything on disk. `-DriveLetter` does not accept pipeline input. + + + + Get-DiskSpace + + DriveLetter + + Specifies one or more drives to query. Each value must be a single letter followed by a colon, such as `C:`; other forms, including `C` and `C:`, are rejected. When you omit this parameter, the cmdlet queries all volumes of the computer, including volumes without a drive letter. + + String[] + + String[] + + + None + + + + + + DriveLetter + + Specifies one or more drives to query. Each value must be a single letter followed by a colon, such as `C:`; other forms, including `C` and `C:`, are rejected. When you omit this parameter, the cmdlet queries all volumes of the computer, including volumes without a drive letter. + + String[] + + String[] + + + None + + + + + + None + + + This cmdlet does not accept pipeline input. Pass the drives to query with the `-DriveLetter` parameter. + + + + + + + Alphaleonis.Win32.Filesystem.DiskSpaceInfo + + + The cmdlet writes one `DiskSpaceInfo` object per queried volume that reports a total size greater than zero. The object carries the size, free space, percentage, and cluster properties that are listed in the description. + + + + + + A volume that cannot be queried, for example a drive that is not ready, produces a warning that names the volume. Use `-WarningAction SilentlyContinue` to suppress those warnings when you query all volumes. + Because the cmdlet enumerates volumes rather than drive letters when `-DriveLetter` is omitted, the result can contain volumes that are mounted into a folder or that have no mount point at all. + + + + + -------- Example 1: Get the disk space of every volume -------- + PS C:\> Get-DiskSpace + + This command returns one object for every volume of the computer, including volumes that are mounted without a drive letter. + + + + ------- Example 2: Get the disk space of a single drive ------- + PS C:\> Get-DiskSpace -DriveLetter C: + + This command returns the size and free space of drive C. The drive letter must be written as a letter followed by a colon. + + + + ------- Example 3: Show a readable summary of two drives ------- + PS C:\> Get-DiskSpace -DriveLetter C:, D: | Select-Object -Property DriveName, TotalSizeUnitSize, AvailableFreeSpaceUnitSize, AvailableFreeSpacePercent + + This command returns the formatted size and free space strings of drives C and D, which are easier to read than the raw byte counts. + + + + -------- Example 4: Find volumes with little free space -------- + PS C:\> Get-DiskSpace | Where-Object { $_.TotalNumberOfFreeBytes -lt 10GB } + + This command returns every volume that has less than 10 GB of free space. The filter uses `TotalNumberOfFreeBytes` because the percentage properties are formatted strings and cannot be compared numerically. + + + + + + Online Version: + https://github.com/raandree/NTFSSecurity/blob/master/Docs/Cmdlets/Get-DiskSpace.md + + + Get-ChildItem2 + + + + Get-Item2 + + + + Get-FileHash2 + + + + + + + Get-FileHash2 + Get + FileHash2 + + Gets the hash value of one or more files. + + + + The `Get-FileHash2` cmdlet calculates the hash value of each file that `-Path` points to and returns the file object with the result attached. The returned object is the file object of the file, extended with a `Hash` property that holds the hash as an uppercase hexadecimal string and an `Algorithm` property that names the algorithm that was used. The module's formatting data displays those objects as a table with the `Algorithm`, `Hash`, and `FullName` columns. + `-Algorithm` selects the hash algorithm and accepts `SHA1`, `SHA256`, `SHA384`, `SHA512`, `MACTripleDES`, `MD5`, and `RIPEMD160`. The default is `SHA256`. + The cmdlet hashes files only. A path that points to a folder is skipped, and because the cmdlet stops processing the current input when it meets one, a folder in the middle of a `-Path` array suppresses the results of the paths that follow it in the same array. Pass only file paths, or filter folders out before you pipe items into the cmdlet. A path that does not exist produces a non-terminating `ReadFileError`. + `-Path` accepts pipeline input by value and by property name through its `FullName` alias, so you can pipe the output of `Get-ChildItem2`, `Get-Item2`, or `Get-ChildItem` into the cmdlet; folders that arrive through the pipeline are skipped individually. Because the cmdlet reads files through the AlphaFS library, it also hashes files whose path exceeds the 260-character `MAX_PATH` limit. Relative paths are resolved against the current location. + + + + Get-FileHash2 + + Path + + Specifies the path of one or more files to hash. Folders are skipped. Relative paths are resolved against the current location. The parameter accepts pipeline input by value and by property name through its `FullName` alias. + + String[] + + String[] + + + None + + + Algorithm + + Specifies the hash algorithm to use. The accepted values are `SHA1`, `SHA256`, `SHA384`, `SHA512`, `MACTripleDES`, `MD5`, and `RIPEMD160`. When you omit this parameter, the cmdlet uses `SHA256`. + + + SHA1 + SHA256 + SHA384 + SHA512 + MACTripleDES + MD5 + RIPEMD160 + + HashAlgorithms + + HashAlgorithms + + + SHA256 + + + + + + Algorithm + + Specifies the hash algorithm to use. The accepted values are `SHA1`, `SHA256`, `SHA384`, `SHA512`, `MACTripleDES`, `MD5`, and `RIPEMD160`. When you omit this parameter, the cmdlet uses `SHA256`. + + HashAlgorithms + + HashAlgorithms + + + SHA256 + + + Path + + Specifies the path of one or more files to hash. Folders are skipped. Relative paths are resolved against the current location. The parameter accepts pipeline input by value and by property name through its `FullName` alias. + + String[] + + String[] + + + None + + + + + + System.String[] + + + You can pipe one or more path strings, or objects that have a `FullName` property such as the output of `Get-ChildItem2` and `Get-Item2`, to this cmdlet. + + + + + Security2.FileSystem.FileInfo.HashAlgorithms + + + You can supply the `-Algorithm` value through a pipeline object that has an `Algorithm` property. + + + + + + + Security2.FileSystemAccessRule2 + + + The cmdlet does not return access rules. For every hashed file it writes the file object of that file, decorated with the type name `Alphaleonis.Win32.Filesystem.FileInfo+Hash` and extended with the `Hash` and `Algorithm` note properties, so all regular file properties such as `FullName`, `Name`, and `Length` remain available. + + + + + + The cmdlet works only in Windows PowerShell. In PowerShell 7, it fails for every algorithm with the error `Could not load type 'System.Security.Cryptography.RIPEMD160'`, because .NET no longer includes the RIPEMD-160 implementation that the cmdlet references. In PowerShell 7, use the built-in `Get-FileHash` cmdlet instead. + If the file cannot be opened because access is denied, the cmdlet takes ownership of the file with the account that runs it, calculates the hash, and restores the previous owner afterward. That fallback fails with a `GetHashError` when the account is not allowed to change the owner of the file. + The hash is returned as an uppercase hexadecimal string without separators, which differs from the lowercase output of some other hashing tools. Compare hash values case-insensitively. + `MACTripleDES` is a keyed message authentication code that is created with a key that is generated for each call, so its result is not reproducible across invocations and is not suitable for comparing files. + + + + + ----------- Example 1: Get the SHA256 hash of a file ----------- + PS C:\> Get-FileHash2 -Path C:\Data\Report.txt + + This command calculates the hash of `Report.txt` with the default `SHA256` algorithm and returns the file object with the `Algorithm` and `Hash` properties attached. + + + + ------------ Example 2: Get the MD5 hash of a file ------------ + PS C:\> Get-FileHash2 -Path C:\Data\Report.txt -Algorithm MD5 + + This command calculates the `MD5` hash of the same file. `MD5` and `SHA1` are fast but are no longer considered collision resistant, so use them for change detection rather than for security decisions. + + + + --------- Example 3: Hash every file in a folder tree --------- + PS C:\> Get-ChildItem2 -Path C:\Data -Recurse | Get-FileHash2 -Algorithm SHA1 | Select-Object -Property Algorithm, Hash, FullName + + This command pipes all items below `C:\Data` into `Get-FileHash2`. The cmdlet binds the `FullName` property of each item to `-Path`, hashes the files, and skips the folders. + + + + --------- Example 4: Find files with identical content --------- + PS C:\> Get-ChildItem2 -Path C:\Data -Recurse | Get-FileHash2 | Group-Object -Property Hash | Where-Object { $_.Count -gt 1 } + + This command groups the files below `C:\Data` by hash value and returns the groups that contain more than one file, which identifies files whose content is identical. + + + + + + Online Version: + https://github.com/raandree/NTFSSecurity/blob/master/Docs/Cmdlets/Get-FileHash2.md + + + Get-ChildItem2 + + + + Get-Item2 + + + + Test-Path2 + + + + Copy-Item2 + + + + + + + Get-Item2 + Get + Item2 + + Gets the file or folder at a specified path, including paths longer than 260 characters. + + + + The `Get-Item2` cmdlet gets the item at a location and returns an `Alphaleonis.Win32.Filesystem.FileInfo` object for a file or an `Alphaleonis.Win32.Filesystem.DirectoryInfo` object for a folder. It is the long-path counterpart of the built-in `Get-Item` cmdlet: it works through the AlphaFS library (`Alphaleonis.Win32.Filesystem`) instead of `System.IO`, so it also reaches items whose path is longer than the 260-character `MAX_PATH` limit. + If you omit `-Path`, the cmdlet returns the item for the current location. Relative paths and the `.` and `..` notations are resolved against the current location as well. Wildcard characters are not supported, so each value of `-Path` must name one existing file or folder. For a path that does not exist, the cmdlet writes a non-terminating error and continues with the remaining paths. + Every returned object carries an additional `Mode` property that reports the directory, archive, read-only, hidden, and system attributes in the same `darhs` notation that `Get-ChildItem` uses. Because the objects expose a `FullName` property and the `-Path` parameters of the NTFSSecurity cmdlets have the alias `FullName`, you can pipe the result straight into cmdlets such as `Get-NTFSAccess`, `Add-NTFSAccess`, or `Get-NTFSOwner`. + + + + Get-Item2 + + Path + + Specifies the path of one or more files or folders. Relative paths are resolved against the current location, and wildcard characters are not supported. If you omit this parameter, the cmdlet returns the item for the current location. + + String[] + + String[] + + + None + + + + + + Path + + Specifies the path of one or more files or folders. Relative paths are resolved against the current location, and wildcard characters are not supported. If you omit this parameter, the cmdlet returns the item for the current location. + + String[] + + String[] + + + None + + + + + + System.String[] + + + You can pipe one or more paths to this cmdlet, either as strings or as objects that have a `FullName` property, such as the output of `Get-ChildItem2` or `Get-Item2`. + + + + + + + Alphaleonis.Win32.Filesystem.FileInfo + + + The cmdlet returns this object for every path that points to a file, extended with a `Mode` property. + + + + + Alphaleonis.Win32.Filesystem.DirectoryInfo + + + The cmdlet returns this object for every path that points to a folder, extended with a `Mode` property. + + + + + + `Get-Item2` builds on the AlphaFS library (`Alphaleonis.Win32.Filesystem`), which is why it reaches files and folders whose path exceeds the 260-character `MAX_PATH` limit that the built-in `Get-Item` cmdlet is bound to. The objects it returns are AlphaFS objects, not `System.IO` objects, and the other NTFSSecurity cmdlets accept them directly through the `FullName` alias of their `-Path` parameters. + The module defines the alias `gi2` for this cmdlet. + `Get-Item2` always adds the `Mode` property. The `GetFileSystemModeProperty` setting in the `PrivateData` section of the module manifest controls only `Get-ChildItem2`. + + + + + ------------------- Example 1: Get a folder ------------------- + PS C:\> Get-Item2 -Path C:\Data + + Returns the `DirectoryInfo` object for the `C:\Data` folder. + + + + --- Example 2: Read the permissions of a deeply nested file --- + PS C:\> Get-Item2 -Path C:\Data\Projects\Archive\2026\Q1\Reports\Regional\Summary.docx | Get-NTFSAccess + + Gets the file and pipes it to `Get-NTFSAccess`, which binds the `FullName` property of the object to its own `-Path` parameter. The command also works when the full path is longer than 260 characters. + + + + -------- Example 3: Get several items from the pipeline -------- + PS C:\> 'C:\Data', 'C:\Data\Reports' | Get-Item2 | Select-Object Mode, LastWriteTime, FullName + + Pipes two paths into the cmdlet and shows the attribute mode, the last write time, and the full path of each item. + + + + ---- Example 4: Use the alias and the positional parameter ---- + PS C:\> gi2 C:\Data\report.docx + + Uses the `gi2` alias and passes the path positionally to get a single file. + + + + + + Online Version: + https://github.com/raandree/NTFSSecurity/blob/master/Docs/Cmdlets/Get-Item2.md + + + Get-ChildItem2 + + + + Copy-Item2 + + + + Move-Item2 + + + + Remove-Item2 + + + + Test-Path2 + + + + Get-NTFSAccess + + + + + + + Get-NTFSAccess + Get + NTFSAccess + + Gets the access control entries (ACEs) of a file, a folder, or a security descriptor. + + + + Reads the discretionary access control list (DACL) of a file or a folder and writes one `Security2.FileSystemAccessRule2` object for every access control entry (ACE) it contains. Each object carries the account, the rights, the access type, the inheritance and propagation flags, whether the ACE is inherited, and the path of the item it was read from. + In the `Path` parameter set the cmdlet reads the item from disk; relative paths are resolved against the current location, and when `-Path` is omitted the current location is used. In the `SD` parameter set it reads the ACEs from a `Security2.FileSystemSecurity2` object returned by `Get-NTFSSecurityDescriptor`, which also reflects changes that have not been written back yet. + By default both explicit and inherited entries are returned. `-ExcludeInherited` limits the result to the entries defined on the item itself, `-ExcludeExplicit` limits it to the entries the item inherits from its parents, and combining both returns nothing. `-Account` filters the result to a single account; an entry matches when the account resolves to the same SID. + When the module setting `GetInheritedFrom` is `$true`, which is the default in the `PrivateData` section of NTFSSecurity.psd1, the `InheritedFrom` property of every inherited entry contains the path of the folder the entry originates from. The default table view shows the account, the rights, the scope of the ACE in the wording of the Windows security dialog, the access type, and the inheritance information; setting `ShowAccountSid` to `$true` adds the SID to the account column. + + + + Get-NTFSAccess + + Path + + Specifies the path of one or more files or folders whose access control entries are read. Relative paths are resolved against the current location, and the current location is used when the parameter is omitted. The parameter accepts pipeline input by value and by property name through its alias `FullName`. + + String[] + + String[] + + + None + + + Account + + Specifies the account whose access control entries are returned. 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`. When the parameter is omitted, the entries of all accounts are returned. + + IdentityReference2 + + IdentityReference2 + + + None + + + ExcludeExplicit + + Indicates that the access control entries defined on the item itself are omitted and only the inherited entries are returned. + + + SwitchParameter + + + False + + + ExcludeInherited + + Indicates that the inherited access control entries are omitted and only the entries defined on the item itself are returned. + + + SwitchParameter + + + False + + + + Get-NTFSAccess + + SecurityDescriptor + + Specifies one or more `Security2.FileSystemSecurity2` objects, as returned by `Get-NTFSSecurityDescriptor`, whose access control entries are read. This includes changes that were made to the object in memory and not written back yet. + 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. + + FileSystemSecurity2[] + + FileSystemSecurity2[] + + + None + + + Account + + Specifies the account whose access control entries are returned. 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`. When the parameter is omitted, the entries of all accounts are returned. + + IdentityReference2 + + IdentityReference2 + + + None + + + ExcludeExplicit + + Indicates that the access control entries defined on the item itself are omitted and only the inherited entries are returned. + + + SwitchParameter + + + False + + + ExcludeInherited + + Indicates that the inherited access control entries are omitted and only the entries defined on the item itself are returned. + + + SwitchParameter + + + False + + + + + + Account + + Specifies the account whose access control entries are returned. 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`. When the parameter is omitted, the entries of all accounts are returned. + + IdentityReference2 + + IdentityReference2 + + + None + + + ExcludeExplicit + + Indicates that the access control entries defined on the item itself are omitted and only the inherited entries are returned. + + SwitchParameter + + SwitchParameter + + + False + + + ExcludeInherited + + Indicates that the inherited access control entries are omitted and only the entries defined on the item itself are returned. + + SwitchParameter + + SwitchParameter + + + False + + + Path + + Specifies the path of one or more files or folders whose access control entries are read. Relative paths are resolved against the current location, and the current location is used when the parameter is omitted. The parameter accepts pipeline input by value and by property name through its alias `FullName`. + + String[] + + String[] + + + None + + + SecurityDescriptor + + Specifies one or more `Security2.FileSystemSecurity2` objects, as returned by `Get-NTFSSecurityDescriptor`, whose access control entries are read. This includes changes that were made to the object in memory and not written back yet. + 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. + + FileSystemSecurity2[] + + FileSystemSecurity2[] + + + None + + + + + + 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 returned by `Get-NTFSSecurityDescriptor`. + + + + + Security2.IdentityReference2 + + + The account to filter on. The parameter does not take pipeline input; it is listed here because it accepts the remaining arguments of the command line. + + + + + + + Security2.FileSystemAccessRule2 + + + One object per access control entry, with the account, the rights, the access type, the inheritance and propagation flags, the `IsInherited` and `InheritedFrom` properties, and the path of the item. + + + + + + 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. + If the ACL of an item cannot be read because access is denied, the cmdlet tries once more after making the current account the owner of the item, and restores the previous owner afterwards. Changing the owner of an item requires the Take Ownership and Restore privileges, so this fallback only succeeds in an elevated session of an account that holds them. + Entries whose account cannot be translated into a name are returned with their SID. Use `Get-NTFSOrphanedAccess` to list only those entries. + + + + + ---- Example 1: Get all access control entries of a folder ---- + PS C:\> Get-NTFSAccess -Path C:\Data + + This command returns the explicit and the inherited access control entries of `C:\Data`. + + + + Example 2: Get only the permissions defined on the item itself + PS C:\> Get-NTFSAccess -Path C:\Data -ExcludeInherited + + This command returns the explicit access control entries of `C:\Data` and omits everything the folder inherits from its parents. + + + + Example 3: Find the permissions of one account in a folder tree + PS C:\> Get-ChildItem2 -Path C:\Data -Recurse -Directory | Get-NTFSAccess -Account 'CONTOSO\JohnDoe' -ExcludeInherited + + This command searches all subfolders of `C:\Data` for access control entries that were defined for a single account. `Get-ChildItem` and `Get-Item2` can be used in the same way, because the `FullName` property of their output binds to `-Path`. + + + + Example 4: Export the explicit permissions of a folder tree to a CSV file + PS C:\> Get-ChildItem2 -Path C:\Data -Recurse | Get-NTFSAccess -ExcludeInherited | Export-Csv -Path C:\Backup\acl.csv -NoTypeInformation + + This command writes a backup of all explicit access control entries below `C:\Data`. `Import-Csv C:\Backup\acl.csv | Add-NTFSAccess` recreates them, because the exported columns bind to the parameters of `Add-NTFSAccess`. + + + + + + Online Version: + https://github.com/raandree/NTFSSecurity/blob/master/Docs/Cmdlets/Get-NTFSAccess.md + + + Add-NTFSAccess + + + + Remove-NTFSAccess + + + + Get-NTFSOrphanedAccess + + + + Get-NTFSSimpleAccess + + + + Get-NTFSEffectiveAccess + + + + Get-NTFSSecurityDescriptor + + + + + + + Get-NTFSAudit + Get + NTFSAudit + + Gets the audit entries of a file or folder. + + + + The `Get-NTFSAudit` cmdlet returns the audit entries that are stored in the system access control list (SACL) of a file or folder. Each entry is a `Security2.FileSystemAuditRule2` object that reports the audited account, the audited access rights, the audit flags (`Success`, `Failure`, or both), the inheritance and propagation flags, whether the entry is inherited, and the item it is inherited from. The access rights are the same values that `Add-NTFSAccess` and `Add-NTFSAudit` use; for what each right permits, see Concepts (../Concepts.md). + In the `Path` parameter set the cmdlet reads the security descriptor of every item in `-Path`. Relative paths are resolved against the current location, and when you omit `-Path` the cmdlet uses the current location. The parameter accepts pipeline input by value and by property name through its `FullName` alias, so the output of `Get-ChildItem`, `Get-ChildItem2`, and `Get-Item2` binds to it. In the `SD` parameter set the cmdlet reads the audit entries from an in-memory `Security2.FileSystemSecurity2` object that `Get-NTFSSecurityDescriptor` returned instead of reading the item again. + By default the cmdlet returns explicit and inherited entries. Use `-ExcludeInherited` to return only the entries that are set on the item itself, and `-ExcludeExplicit` to return only the entries that the item inherits from a parent folder. `-Account` filters the result to a single account; the comparison is made on the security identifier (SID), so an account name and its SID select the same entries. + The `InheritedFrom` property is filled only when the module setting `GetInheritedFrom` is `$true`, which is the default in the `PrivateData` section of `NTFSSecurity.psd1`. + + + + Get-NTFSAudit + + Path + + Specifies the files or folders whose audit entries are returned. Relative paths are resolved against the current location, and when you omit the parameter the cmdlet uses the current location. The parameter accepts pipeline input by value and by property name through its `FullName` alias. + + String[] + + String[] + + + None + + + Account + + Specifies the account whose audit entries are returned. The value is an account name such as `CONTOSO\JohnDoe`, `BUILTIN\Users`, or `Everyone`, or a SID string such as `S-1-5-32-545`. Entries are matched by SID, and when you omit the parameter the entries of all accounts are returned. + + IdentityReference2 + + IdentityReference2 + + + None + + + ExcludeExplicit + + Indicates that the entries that are set on the item itself are left out, so that only the inherited entries are returned. By default the cmdlet returns explicit and inherited entries. + + + SwitchParameter + + + False + + + ExcludeInherited + + Indicates that the entries the item inherits from a parent folder are left out, so that only the explicit entries are returned. By default the cmdlet returns explicit and inherited entries. + + + SwitchParameter + + + False + + + + Get-NTFSAudit + + SecurityDescriptor + + Specifies one or more security descriptors that `Get-NTFSSecurityDescriptor` returned. The cmdlet reads the audit entries from the system access control list (SACL) of the in-memory object instead of reading the item from disk again. + + FileSystemSecurity2[] + + FileSystemSecurity2[] + + + None + + + Account + + Specifies the account whose audit entries are returned. The value is an account name such as `CONTOSO\JohnDoe`, `BUILTIN\Users`, or `Everyone`, or a SID string such as `S-1-5-32-545`. Entries are matched by SID, and when you omit the parameter the entries of all accounts are returned. + + IdentityReference2 + + IdentityReference2 + + + None + + + ExcludeExplicit + + Indicates that the entries that are set on the item itself are left out, so that only the inherited entries are returned. By default the cmdlet returns explicit and inherited entries. + + + SwitchParameter + + + False + + + ExcludeInherited + + Indicates that the entries the item inherits from a parent folder are left out, so that only the explicit entries are returned. By default the cmdlet returns explicit and inherited entries. + + + SwitchParameter + + + False + + + + + + Account + + Specifies the account whose audit entries are returned. The value is an account name such as `CONTOSO\JohnDoe`, `BUILTIN\Users`, or `Everyone`, or a SID string such as `S-1-5-32-545`. Entries are matched by SID, and when you omit the parameter the entries of all accounts are returned. + + IdentityReference2 + + IdentityReference2 + + + None + + + ExcludeExplicit + + Indicates that the entries that are set on the item itself are left out, so that only the inherited entries are returned. By default the cmdlet returns explicit and inherited entries. + + SwitchParameter + + SwitchParameter + + + False + + + ExcludeInherited + + Indicates that the entries the item inherits from a parent folder are left out, so that only the explicit entries are returned. By default the cmdlet returns explicit and inherited entries. + + SwitchParameter + + SwitchParameter + + + False + + + Path + + Specifies the files or folders whose audit entries are returned. Relative paths are resolved against the current location, and when you omit the parameter the cmdlet uses the current location. The parameter accepts pipeline input by value and by property name through its `FullName` alias. + + String[] + + String[] + + + None + + + SecurityDescriptor + + Specifies one or more security descriptors that `Get-NTFSSecurityDescriptor` returned. The cmdlet reads the audit entries from the system access control list (SACL) of the in-memory object instead of reading the item from disk again. + + FileSystemSecurity2[] + + FileSystemSecurity2[] + + + None + + + + + + System.String[] + + + You can pipe paths to this cmdlet, or objects that have a `Path` or `FullName` property, such as the output of `Get-ChildItem`, `Get-ChildItem2`, and `Get-Item2`. + + + + + Security2.FileSystemSecurity2[] + + + You can pipe the security descriptors that `Get-NTFSSecurityDescriptor` returns to this cmdlet. + + + + + Security2.IdentityReference2 + + + You can pass an account name or a SID string to `-Account`, which the cmdlet converts to this type. The parameter does not accept pipeline input. + + + + + + + Security2.FileSystemAuditRule2 + + + The cmdlet returns one object per audit entry, with the audited account, the audited access rights, the audit flags, the inheritance and propagation flags, the `IsInherited` flag, and the `InheritedFrom` path. When an item has no audit entries, or when the SACL cannot be read, the cmdlet returns nothing for that item. + + + + + + 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 the SACL requires the Security privilege (`SeSecurityPrivilege`, "Manage auditing and security log"), so run this cmdlet in an elevated session of an account that holds that privilege. Without it the cmdlet falls back to reading the security descriptor without its SACL; it then returns no audit entries and reports no error, which looks the same as an item that is not audited at all. + If the security descriptor cannot be read because access is denied, the cmdlet takes ownership of the item, reads the descriptor again, and restores the previous owner. If the second attempt fails as well, the cmdlet writes an error, and the ownership change is not rolled back. + + + + + --------- Example 1: Get the audit entries of a folder --------- + PS C:\> Get-NTFSAudit -Path C:\Data + + This command returns every audit entry of the folder `C:\Data`, including the entries that the folder inherits from its parent. + + + + - Example 2: List the explicit audit entries of a folder tree - + PS C:\> Get-ChildItem2 -Path C:\Data -Recurse | Get-NTFSAudit -ExcludeInherited + + This command pipes every item below `C:\Data` into `Get-NTFSAudit` and returns only the audit entries that are set on the items themselves. + + + + -------- Example 3: Filter the audit entries by account -------- + PS C:\> Get-NTFSAudit -Path C:\Data -Account 'CONTOSO\JohnDoe' + + This command returns only the entries that audit the account `CONTOSO\JohnDoe`. Passing the SID of the account instead of its name returns the same entries. + + + + - Example 4: Read the audit entries from a security descriptor - + PS C:\> $sd = Get-NTFSSecurityDescriptor -Path C:\Data +PS C:\> Get-NTFSAudit -SecurityDescriptor $sd + + This command reads the security descriptor of `C:\Data` once and then lists its audit entries from the in-memory object. + + + + + + Online Version: + https://github.com/raandree/NTFSSecurity/blob/master/Docs/Cmdlets/Get-NTFSAudit.md + + + Add-NTFSAudit + + + + Remove-NTFSAudit + + + + Clear-NTFSAudit + + + + Get-NTFSOrphanedAudit + + + + Get-NTFSSecurityDescriptor + + + + + + + Get-NTFSEffectiveAccess + Get + NTFSEffectiveAccess + + Gets the rights an account effectively has on a file or folder. + + + + 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. Reading effective access relies on the Security privilege, and the cmdlet warns when the account does not hold it or the privilege is disabled. + Although `-Path` is optional, the cmdlet writes nothing when the parameter is omitted; pass a path or pipe items in. The `SecurityDescriptor` parameter set is accepted by the parameter binder but produces no output, so use `-Path` to query effective access. + + + + Get-NTFSEffectiveAccess + + 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`. The cmdlet writes nothing when no path is supplied. + + String[] + + String[] + + + None + + + 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. + + IdentityReference2 + + IdentityReference2 + + + Current user + + + ExcludeNoneAccessEntries + + Indicates that items on which the account has no rights at all are left out of the result. In this release the switch does not suppress anything: the cmdlet writes a result for every item it processes, even when the calculated access mask is `None`. + + + SwitchParameter + + + 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. + + String + + String + + + localhost + + + + Get-NTFSEffectiveAccess + + SecurityDescriptor + + This parameter is accepted by the parameter binder but has no effect. The cmdlet produces no output in this parameter set; use `-Path` instead. + 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. + + FileSystemSecurity2[] + + FileSystemSecurity2[] + + + None + + + 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. + + IdentityReference2 + + IdentityReference2 + + + Current user + + + ExcludeNoneAccessEntries + + Indicates that items on which the account has no rights at all are left out of the result. In this release the switch does not suppress anything: the cmdlet writes a result for every item it processes, even when the calculated access mask is `None`. + + + SwitchParameter + + + 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. + + String + + String + + + localhost + + + + + + 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. + + IdentityReference2 + + IdentityReference2 + + + Current user + + + ExcludeNoneAccessEntries + + Indicates that items on which the account has no rights at all are left out of the result. In this release the switch does not suppress anything: the cmdlet writes a result for every item it processes, even when the calculated access mask is `None`. + + SwitchParameter + + SwitchParameter + + + 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`. The cmdlet writes nothing when no path is supplied. + + String[] + + String[] + + + None + + + SecurityDescriptor + + This parameter is accepted by the parameter binder but has no effect. The cmdlet produces no output in this parameter set; use `-Path` instead. + 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. + + FileSystemSecurity2[] + + FileSystemSecurity2[] + + + None + + + 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. + + String + + String + + + localhost + + + + + + System.String[] + + + One or more paths of files or folders, piped by value or by the property `FullName`. + + + + + Security2.FileSystemSecurity2[] + + + Security descriptors are accepted by the parameter binder but produce no result in this cmdlet. + + + + + Security2.IdentityReference2 + + + The account the effective access is calculated for, piped by the property `Account`, `NTAccount`, or `IdentityReference`. + + + + + + + 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. + + + + + + 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. + + + + + --- Example 1: Get the effective access of the current user --- + 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 ---- + 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 --- + 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 + 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. + + + + + + Online Version: + https://github.com/raandree/NTFSSecurity/blob/master/Docs/Cmdlets/Get-NTFSEffectiveAccess.md + + + Get-NTFSAccess + + + + Get-NTFSSimpleAccess + + + + Get-NTFSInheritance + + + + Enable-Privileges + + + + Get-Privileges + + + + + + + Get-NTFSHardLink + Get + NTFSHardLink + + Gets all hard links that refer to the same file as the specified path. + + + + On an NTFS volume, a file is a block of data that one or more directory entries, called hard links, refer to. The `Get-NTFSHardLink` cmdlet asks the file system for every hard link of the file that `-Path` points to and writes a file object for each of them, including the name that you passed in. + A file that has only one name returns a single object. A file that has additional hard links returns one object per name, which lets you find all the places on the volume from which the same data is reachable. The file system reports the links relative to the root of the volume, and the cmdlet combines them with the root of the path you specify, so the result contains full paths. All hard links of a file are always on the same volume as the file. + `-Path` must point to a file. A folder causes an error, because NTFS does not support hard links to folders. If you omit `-Path`, the cmdlet falls back to the current location, which is a folder and therefore produces the same error, so always pass the path of a file. + The parameter accepts an array of paths and takes pipeline input by value and by property name through its `FullName` alias. `Get-ChildItem2` adds a `HardLinkCount` property to each file as long as the `IdentifyHardLinks` entry in the `PrivateData` section of the module manifest is `$true`, which lets you select the files that have more than one name before you resolve them. + + + + Get-NTFSHardLink + + Path + + Specifies the path of one or more files whose hard links you want to resolve. The path must point to a file; folders cause an error. Relative paths are resolved against the current location. The parameter accepts pipeline input by value and by property name through its `FullName` alias. + + String[] + + String[] + + + None + + + + + + Path + + Specifies the path of one or more files whose hard links you want to resolve. The path must point to a file; folders cause an error. Relative paths are resolved against the current location. The parameter accepts pipeline input by value and by property name through its `FullName` alias. + + String[] + + String[] + + + None + + + + + + System.String[] + + + You can pipe one or more file path strings, or objects that have a `FullName` property such as the output of `Get-ChildItem2` and `Get-Item2`, to this cmdlet. + + + + + + + Alphaleonis.Win32.Filesystem.FileInfo + + + The cmdlet writes one file object per hard link of the file, extended with a `Mode` property that renders the file attributes in the same notation as `Get-ChildItem2`. + + + + + Alphaleonis.Win32.Filesystem.DirectoryInfo + + + The cmdlet never writes folder objects, because it rejects folders with the error `The item must be a file`. + + + + + + Hard links exist only within a single NTFS volume. Every object that this cmdlet returns therefore refers to a path on the volume of the file that you passed in. + Because all hard links of a file share the same data, they also share the file content, the file size, and the time stamps. The security descriptor is stored with the file as well, so changing permissions through one name changes them for every name. + The cmdlet resolves paths through the AlphaFS library and therefore also works with paths that exceed the 260-character `MAX_PATH` limit. + + + + + -------------- Example 1: Get all names of a file -------------- + PS C:\> Get-NTFSHardLink -Path C:\Data\Report.txt + + This command returns one object for every hard link of `Report.txt`, including `Report.txt` itself. If the file has no additional links, the command returns that single file. + + + + ------- Example 2: List the full paths of all hard links ------- + PS C:\> Get-NTFSHardLink -Path C:\Data\Report.txt | Select-Object -ExpandProperty FullName + + This command returns the full path of every name under which the data of `Report.txt` is reachable on the volume. + + + + Example 3: Resolve the hard links of all multi-link files in a folder + PS C:\> Get-ChildItem2 -Path C:\Data -Recurse | Where-Object { $_.HardLinkCount -gt 1 } | Get-NTFSHardLink + + This command uses the `HardLinkCount` property that `Get-ChildItem2` adds to files to select the files that have more than one name, and then resolves all names of each of them. + + + + ------------- Example 4: Count the names of a file ------------- + PS C:\> (Get-NTFSHardLink -Path C:\Data\Report.txt).Count + + This command returns the number of hard links that refer to the data of `Report.txt`. A result of `1` means that deleting the file releases its data. + + + + + + Online Version: + https://github.com/raandree/NTFSSecurity/blob/master/Docs/Cmdlets/Get-NTFSHardLink.md + + + New-NTFSHardLink + + + + New-NTFSSymbolicLink + + + + Get-ChildItem2 + + + + Get-Item2 + + + + + + + Get-NTFSInheritance + Get + NTFSInheritance + + Gets the inheritance state of the access rules and the audit rules of a file or folder. + + + + The `Get-NTFSInheritance` cmdlet reports whether a file or folder inherits access rules from its parent folder and whether it inherits audit rules. For each item it writes one `Security2.FileSystemInheritanceInfo` object with the `Name`, `FullName`, `AccessInheritanceEnabled`, and `AuditInheritanceEnabled` properties, plus the underlying file system object in the `Item` property. The default table view shows `Name`, `AccessInheritanceEnabled`, and `AuditInheritanceEnabled`. + `AccessInheritanceEnabled` is `$false` when the discretionary access control list (DACL) of the item is protected, which is the state that `Disable-NTFSAccessInheritance` produces. `AuditInheritanceEnabled` reports the same for the system access control list (SACL), which holds the audit rules. When the audit section cannot be read because the session does not hold the Security privilege, `AuditInheritanceEnabled` is `$null` and its column stays empty; the access value is still reported and no error is written. + In the `Path` parameter set the cmdlet reads the security descriptor of each item from disk. In the `SecurityDescriptor` parameter set it reads the state from the `Security2.FileSystemSecurity2` objects that `Get-NTFSSecurityDescriptor` returns, without touching the file system. Note that a descriptor that was retrieved without its audit section reports `AuditInheritanceEnabled` as `$true`, because the protection flag of a section that was never read is not set. + `-Path` accepts pipeline input by value and by property name through its `FullName` alias, so the output of `Get-ChildItem`, `Get-ChildItem2`, and `Get-Item2` binds to it. Relative paths are resolved against the current location, and when no path is supplied at all, the cmdlet reports the current location. + + + + Get-NTFSInheritance + + Path + + Specifies the path of one or more files or folders to report on. Relative paths are resolved against the current location, and the current location is used when the parameter is omitted and no item arrives from the pipeline. The parameter accepts pipeline input by value and by property name through its `FullName` alias, so the output of `Get-ChildItem`, `Get-ChildItem2`, and `Get-Item2` binds to it. + + String[] + + String[] + + + None + + + + Get-NTFSInheritance + + SecurityDescriptor + + The SecurityDescriptor parameter allows passing an security descriptor or an array or security descriptors. + 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. + This cmdlet reads the inheritance state from the descriptor in memory and does not access the file system for it. + + FileSystemSecurity2[] + + FileSystemSecurity2[] + + + None + + + + + + Path + + Specifies the path of one or more files or folders to report on. Relative paths are resolved against the current location, and the current location is used when the parameter is omitted and no item arrives from the pipeline. The parameter accepts pipeline input by value and by property name through its `FullName` alias, so the output of `Get-ChildItem`, `Get-ChildItem2`, and `Get-Item2` binds to it. + + String[] + + String[] + + + None + + + SecurityDescriptor + + The SecurityDescriptor parameter allows passing an security descriptor or an array or security descriptors. + 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. + This cmdlet reads the inheritance state from the descriptor in memory and does not access the file system for it. + + FileSystemSecurity2[] + + FileSystemSecurity2[] + + + None + + + + + + System.String[] + + + You can pipe one or more path strings, or objects that have a `FullName` property such as the output of `Get-ChildItem2`, `Get-Item2`, and `Get-ChildItem`, to this cmdlet. + + + + + Security2.FileSystemSecurity2[] + + + You can pipe the security descriptors that `Get-NTFSSecurityDescriptor` returns to this cmdlet. + + + + + + + Security2.FileSystemInheritanceInfo + + + For each item the cmdlet writes one object with the `Name`, `FullName`, `Item`, `AccessInheritanceEnabled`, and `AuditInheritanceEnabled` properties. `AccessInheritanceEnabled` and `AuditInheritanceEnabled` are `$true` when the item inherits the rules of the corresponding section from its parent folder, and `AuditInheritanceEnabled` is `$null` when the audit section could not be read. + + + + + + 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 the audit section (SACL) of an item requires the Security privilege (`SeSecurityPrivilege`), which an account can only use in an elevated session. Without it, the cmdlet still reports the access state and sets `AuditInheritanceEnabled` to `$null` instead of writing an error. + If the security descriptor of an item cannot be opened because the account has no permission to it, the cmdlet takes ownership of the item, reads the state, and sets the previous owner back. That fallback only succeeds when the account can take ownership of the item and restore the original owner; otherwise the cmdlet writes an error and continues with the next item. + A path that does not exist produces a non-terminating error and the cmdlet continues with the remaining paths. + + + + + ------- Example 1: Get the inheritance state of a folder ------- + PS C:\> Get-NTFSInheritance -Path C:\Data\Projects + + This command reports whether `C:\Data\Projects` inherits access rules and audit rules from `C:\Data`. In a session that does not hold the Security privilege, the `AuditInheritanceEnabled` column stays empty. + + + + Example 2: Find the items whose access inheritance is blocked + PS C:\> Get-ChildItem2 -Path C:\Data -Recurse | Get-NTFSInheritance | Where-Object { -not $_.AccessInheritanceEnabled } + + This command walks the whole tree below `C:\Data` and returns only the items whose DACL is protected. These are the places where the permission model of the tree is interrupted and permissions have to be maintained separately. + + + + ------------ Example 3: Report the current location ------------ + PS C:\> Get-NTFSInheritance + + This command reports the inheritance state of the current location, because `-Path` is omitted and no item arrives from the pipeline. + + + + ----- Example 4: Read the state from a security descriptor ----- + PS C:\> Get-NTFSSecurityDescriptor -Path C:\Data\Projects | Get-NTFSInheritance + + This command reads the security descriptor once and reports its inheritance state from memory. The access value is always accurate; the audit value is only meaningful when the descriptor was retrieved with its audit section, which requires the Security privilege. + + + + + + Online Version: + https://github.com/raandree/NTFSSecurity/blob/master/Docs/Cmdlets/Get-NTFSInheritance.md + + + Set-NTFSInheritance + + + + Enable-NTFSAccessInheritance + + + + Disable-NTFSAccessInheritance + + + + Enable-NTFSAuditInheritance + + + + Disable-NTFSAuditInheritance + + + + Get-NTFSSecurityDescriptor + + + + + + + Get-NTFSOrphanedAccess + Get + NTFSOrphanedAccess + + Gets the access control entries whose account cannot be resolved to a name. + + + + Reads the discretionary access control list (DACL) of a file or a folder like `Get-NTFSAccess` and returns only the access control entries whose account name is empty. The account name of an entry is empty when Windows cannot translate the SID stored in the entry into an account name, which is what remains after the account the entry was created for has been deleted. + An entry counts as orphaned only as long as the name resolution fails, and the cmdlet cannot tell a deleted account from an account that cannot be looked up right now. A domain controller that is unreachable, a broken trust, or a SID from a domain the computer does not know make intact entries look orphaned as well. Confirm that the accounts are really gone before you remove anything, and run the search from a computer that can resolve all domains involved. + Relative paths are resolved against the current location, and the current location is searched when `-Path` is omitted. By default both explicit and inherited entries are returned, which means that the same orphaned entry appears on every item that inherits it; `-ExcludeInherited` reports it only on the item where it is defined. With `-Verbose`, the cmdlet reports the number of orphaned entries per item and the total at the end. + The `-Account` and `-SecurityDescriptor` parameters are inherited from `Get-NTFSAccess` and have no effect on this cmdlet. Entries are never filtered by account, and a security descriptor passed to `-SecurityDescriptor` is ignored; the cmdlet reads the current location instead. + + + + Get-NTFSOrphanedAccess + + Path + + Specifies the path of one or more files or folders that are searched for orphaned access control entries. Relative paths are resolved against the current location, and the current location is used when the parameter is omitted. The parameter accepts pipeline input by value and by property name through its alias `FullName`. + + String[] + + String[] + + + None + + + Account + + This parameter is inherited from `Get-NTFSAccess` and has no effect. The cmdlet always returns the entries of all accounts that cannot be resolved. + + IdentityReference2 + + IdentityReference2 + + + None + + + ExcludeExplicit + + Indicates that the access control entries defined on the item itself are omitted and only the inherited entries are searched. + + + SwitchParameter + + + False + + + ExcludeInherited + + Indicates that the inherited access control entries are omitted and only the entries defined on the item itself are searched. Use this switch to report an orphaned entry once instead of on every item that inherits it. + + + SwitchParameter + + + False + + + + Get-NTFSOrphanedAccess + + SecurityDescriptor + + This parameter is inherited from `Get-NTFSAccess` and has no effect. A security descriptor passed here is ignored, and the cmdlet searches the path in `-Path` or the current location instead. + 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. + + FileSystemSecurity2[] + + FileSystemSecurity2[] + + + None + + + Account + + This parameter is inherited from `Get-NTFSAccess` and has no effect. The cmdlet always returns the entries of all accounts that cannot be resolved. + + IdentityReference2 + + IdentityReference2 + + + None + + + ExcludeExplicit + + Indicates that the access control entries defined on the item itself are omitted and only the inherited entries are searched. + + + SwitchParameter + + + False + + + ExcludeInherited + + Indicates that the inherited access control entries are omitted and only the entries defined on the item itself are searched. Use this switch to report an orphaned entry once instead of on every item that inherits it. + + + SwitchParameter + + + False + + + + + + Account + + This parameter is inherited from `Get-NTFSAccess` and has no effect. The cmdlet always returns the entries of all accounts that cannot be resolved. + + IdentityReference2 + + IdentityReference2 + + + None + + + ExcludeExplicit + + Indicates that the access control entries defined on the item itself are omitted and only the inherited entries are searched. + + SwitchParameter + + SwitchParameter + + + False + + + ExcludeInherited + + Indicates that the inherited access control entries are omitted and only the entries defined on the item itself are searched. Use this switch to report an orphaned entry once instead of on every item that inherits it. + + SwitchParameter + + SwitchParameter + + + False + + + Path + + Specifies the path of one or more files or folders that are searched for orphaned access control entries. Relative paths are resolved against the current location, and the current location is used when the parameter is omitted. The parameter accepts pipeline input by value and by property name through its alias `FullName`. + + String[] + + String[] + + + None + + + SecurityDescriptor + + This parameter is inherited from `Get-NTFSAccess` and has no effect. A security descriptor passed here is ignored, and the cmdlet searches the path in `-Path` or the current location instead. + 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. + + FileSystemSecurity2[] + + FileSystemSecurity2[] + + + None + + + + + + System.String[] + + + One or more paths of files or folders, piped by value or by the property `FullName`. + + + + + Security2.FileSystemSecurity2[] + + + Security descriptors are accepted by the parameter binder but ignored by this cmdlet. + + + + + Security2.IdentityReference2 + + + An account is accepted by the parameter binder but ignored by this cmdlet. + + + + + + + Security2.FileSystemAccessRule2 + + + One object per orphaned access control entry. The `Account` property holds the unresolved SID and reports an empty account name. + + + + + + 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. + If the ACL of an item cannot be read because access is denied, the cmdlet tries once more after making the current account the owner of the item, and restores the previous owner afterwards. Changing the owner of an item requires the Take Ownership and Restore privileges, so this fallback only succeeds in an elevated session of an account that holds them. + + + + + --------- Example 1: Find orphaned entries in a folder --------- + PS C:\> Get-NTFSOrphanedAccess -Path C:\Data + + This command returns the access control entries of `C:\Data` whose SID cannot be resolved, including the entries the folder inherits from its parent. + + + + ----- Example 2: Search a folder tree for orphaned entries ----- + PS C:\> Get-ChildItem2 -Path C:\Data -Recurse | Get-NTFSOrphanedAccess -ExcludeInherited + + This command searches all files and folders below `C:\Data` and reports every orphaned entry on the item where it is defined. Without `-ExcludeInherited` the same entry would also be reported on every item that inherits it. + + + + -------------- Example 3: Remove orphaned entries -------------- + PS C:\> Get-ChildItem2 -Path C:\Data -Recurse | Get-NTFSOrphanedAccess -ExcludeInherited | Remove-NTFSAccess + + This command deletes the orphaned entries from the items they are defined on. The piped objects supply the path, the SID, the rights, the access type, and the flags, so each entry is matched exactly as it exists. + + + + + + Online Version: + https://github.com/raandree/NTFSSecurity/blob/master/Docs/Cmdlets/Get-NTFSOrphanedAccess.md + + + Get-NTFSAccess + + + + Remove-NTFSAccess + + + + Get-NTFSOrphanedAudit + + + + Get-NTFSSimpleAccess + + + + Get-ChildItem2 + + + + + + + Get-NTFSOrphanedAudit + Get + NTFSOrphanedAudit + + Gets the audit entries whose account cannot be resolved. + + + + The `Get-NTFSOrphanedAudit` cmdlet returns the audit entries of a file or folder whose account cannot be translated into a name. An entry is called orphaned when its security identifier (SID) is still stored in the system access control list (SACL) but Windows cannot map that SID to a user or group, which usually happens after the account was deleted. Orphaned entries are shown with their SID instead of a name, and they keep auditing a security principal that no longer exists. + An entry is reported as orphaned whenever the name resolution fails at that moment, not only when the account is really gone. A domain account whose domain controller cannot be reached, an account from a domain whose trust relationship is broken, and an account from a forest the computer currently cannot contact all look exactly like a deleted account. Verify that an account no longer exists before you remove its entries with `Remove-NTFSAudit`. + The cmdlet is built on `Get-NTFSAudit` and reads the SACL of every item in `-Path`, using the current location when you omit the parameter. `-Path` accepts pipeline input by value and by property name through its `FullName` alias, so the output of `Get-ChildItem`, `Get-ChildItem2`, and `Get-Item2` binds to it. `-ExcludeExplicit` and `-ExcludeInherited` narrow the entries that are examined, and `-Verbose` reports how many orphaned entries each item has and their total. + `Get-NTFSOrphanedAudit` inherits the `-Account` and `-SecurityDescriptor` parameters from `Get-NTFSAudit`, but it does not evaluate them. The entries are always read from the items in `-Path`, so a command that passes `-SecurityDescriptor` examines the current location instead of the descriptor. + + + + Get-NTFSOrphanedAudit + + Path + + Specifies the files or folders that are examined. Relative paths are resolved against the current location, and when you omit the parameter the cmdlet uses the current location. The parameter accepts pipeline input by value and by property name through its `FullName` alias. + + String[] + + String[] + + + None + + + Account + + Specifies an account in the base cmdlet `Get-NTFSAudit`. `Get-NTFSOrphanedAudit` inherits the parameter but does not evaluate it, so the result always contains the entries of every account whose SID cannot be resolved. + + IdentityReference2 + + IdentityReference2 + + + None + + + ExcludeExplicit + + Indicates that the entries that are set on the item itself are left out, so that only inherited entries are examined. By default the cmdlet examines explicit and inherited entries. + + + SwitchParameter + + + False + + + ExcludeInherited + + Indicates that the entries the item inherits from a parent folder are left out, so that only the explicit entries are examined. By default the cmdlet examines explicit and inherited entries. + + + SwitchParameter + + + False + + + + Get-NTFSOrphanedAudit + + SecurityDescriptor + + Specifies one or more security descriptors in the base cmdlet `Get-NTFSAudit`. `Get-NTFSOrphanedAudit` inherits the parameter but does not read from it; the cmdlet always examines the items in `-Path` and therefore the current location when `-Path` is omitted. Use `Get-NTFSAudit -SecurityDescriptor` to inspect the audit entries of a security descriptor. + + FileSystemSecurity2[] + + FileSystemSecurity2[] + + + None + + + Account + + Specifies an account in the base cmdlet `Get-NTFSAudit`. `Get-NTFSOrphanedAudit` inherits the parameter but does not evaluate it, so the result always contains the entries of every account whose SID cannot be resolved. + + IdentityReference2 + + IdentityReference2 + + + None + + + ExcludeExplicit + + Indicates that the entries that are set on the item itself are left out, so that only inherited entries are examined. By default the cmdlet examines explicit and inherited entries. + + + SwitchParameter + + + False + + + ExcludeInherited + + Indicates that the entries the item inherits from a parent folder are left out, so that only the explicit entries are examined. By default the cmdlet examines explicit and inherited entries. + + + SwitchParameter + + + False + + + + + + Account + + Specifies an account in the base cmdlet `Get-NTFSAudit`. `Get-NTFSOrphanedAudit` inherits the parameter but does not evaluate it, so the result always contains the entries of every account whose SID cannot be resolved. + + IdentityReference2 + + IdentityReference2 + + + None + + + ExcludeExplicit + + Indicates that the entries that are set on the item itself are left out, so that only inherited entries are examined. By default the cmdlet examines explicit and inherited entries. + + SwitchParameter + + SwitchParameter + + + False + + + ExcludeInherited + + Indicates that the entries the item inherits from a parent folder are left out, so that only the explicit entries are examined. By default the cmdlet examines explicit and inherited entries. + + SwitchParameter + + SwitchParameter + + + False + + + Path + + Specifies the files or folders that are examined. Relative paths are resolved against the current location, and when you omit the parameter the cmdlet uses the current location. The parameter accepts pipeline input by value and by property name through its `FullName` alias. + + String[] + + String[] + + + None + + + SecurityDescriptor + + Specifies one or more security descriptors in the base cmdlet `Get-NTFSAudit`. `Get-NTFSOrphanedAudit` inherits the parameter but does not read from it; the cmdlet always examines the items in `-Path` and therefore the current location when `-Path` is omitted. Use `Get-NTFSAudit -SecurityDescriptor` to inspect the audit entries of a security descriptor. + + FileSystemSecurity2[] + + FileSystemSecurity2[] + + + None + + + + + + System.String[] + + + You can pipe paths to this cmdlet, or objects that have a `Path` or `FullName` property, such as the output of `Get-ChildItem`, `Get-ChildItem2`, and `Get-Item2`. + + + + + Security2.FileSystemSecurity2[] + + + Security descriptors bind to the inherited `-SecurityDescriptor` parameter, but this cmdlet does not read their audit entries. + + + + + Security2.IdentityReference2 + + + An account name or a SID string binds to the inherited `-Account` parameter, which this cmdlet does not evaluate. + + + + + + + Security2.FileSystemAuditRule2 + + + The cmdlet returns the audit entries whose account SID cannot be translated into a name, each with the item, the unresolved account, the audited access rights, the audit flags, and the inheritance information. The entries of an item are written as a single collection rather than one object per entry, so store the result in a variable before you filter or format it; an item without orphaned entries still produces one empty collection, and a command placed directly after this cmdlet in the pipeline receives the collection instead of the individual entries. + + + + + + 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 the SACL requires the Security privilege (`SeSecurityPrivilege`, "Manage auditing and security log"), so run this cmdlet in an elevated session of an account that holds that privilege. Without it the cmdlet reads the security descriptor without its SACL and reports no orphaned entries at all, which looks the same as a tree that has none. + If an item cannot be read, the cmdlet writes a warning and continues with the next item. Unlike `Get-NTFSAudit`, it does not try to take ownership of the item when access is denied. + + + + + --- Example 1: Find orphaned audit entries in a folder tree --- + PS C:\> Get-ChildItem2 -Path C:\Data -Recurse | Get-NTFSOrphanedAudit + + This command examines every item below `C:\Data` and returns the audit entries whose account cannot be resolved. + + + + Example 2: Find orphaned entries that are set on the item itself + PS C:\> Get-NTFSOrphanedAudit -Path C:\Data -ExcludeInherited + + This command skips the audit entries that `C:\Data` inherits from its parent and reports only the orphaned entries that are set on the folder itself. Those are the entries that can be removed on this item. + + + + ----- Example 3: Collect the orphaned entries for a report ----- + PS C:\> $orphaned = Get-NTFSOrphanedAudit -Path C:\Data -Verbose +PS C:\> $orphaned | Select-Object FullName, Account, AccessRights, AuditFlags + + This command stores the result in a variable and then lists the item, the unresolved SID, the audited rights, and the audit flags of every orphaned entry. Storing the result first is necessary because the cmdlet writes one collection per item rather than one object per entry. + + + + ------------ Example 4: Check the current location ------------ + PS C:\> Get-NTFSOrphanedAudit + + This command examines the current location, because `-Path` is omitted. + + + + + + Online Version: + https://github.com/raandree/NTFSSecurity/blob/master/Docs/Cmdlets/Get-NTFSOrphanedAudit.md + + + Get-NTFSAudit + + + + Remove-NTFSAudit + + + + Clear-NTFSAudit + + + + Add-NTFSAudit + + + + Get-NTFSOrphanedAccess + + + + + + + Get-NTFSOwner + Get + NTFSOwner + + Gets the owner of a file or folder. + + + + The `Get-NTFSOwner` cmdlet reads the owner from the security descriptor of a file or folder and returns a `Security2.FileSystemOwner` object. That object exposes the item in the `Item` property, its full path in `FullName`, and the owning account in both the `Owner` and the `Account` property. + The `Path` parameter set reads the owner from the file system. The `SecurityDescriptor` parameter set reads the owner from a security descriptor that `Get-NTFSSecurityDescriptor` returned. The second form also shows an owner that `Set-NTFSOwner` changed in memory but that has not been written back with `Set-NTFSSecurityDescriptor` yet. + The `Path` parameter 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. Unlike `Get-NTFSSecurityDescriptor`, this cmdlet does not fall back to the current location: when you omit `-Path`, it returns nothing. + Every path is processed on its own. When a path does not exist or its owner cannot be read, the cmdlet writes a non-terminating error and continues with the next path. + + + + Get-NTFSOwner + + Path + + Specifies the path of one or more files or folders whose owner you want to read. Relative paths are resolved against the current location. When you omit this parameter, the cmdlet returns nothing. + + String[] + + String[] + + + None + + + + Get-NTFSOwner + + SecurityDescriptor + + Specifies one or more security descriptors that `Get-NTFSSecurityDescriptor` returned. The cmdlet reads the owner from the descriptor in memory instead of from the file system, which includes an owner that `Set-NTFSOwner -SecurityDescriptor` changed but that has not been written back yet. + + FileSystemSecurity2[] + + FileSystemSecurity2[] + + + None + + + + + + Path + + Specifies the path of one or more files or folders whose owner you want to read. Relative paths are resolved against the current location. When you omit this parameter, the cmdlet returns nothing. + + String[] + + String[] + + + None + + + SecurityDescriptor + + Specifies one or more security descriptors that `Get-NTFSSecurityDescriptor` returned. The cmdlet reads the owner from the descriptor in memory instead of from the file system, which includes an owner that `Set-NTFSOwner -SecurityDescriptor` changed but that has not been written back yet. + + FileSystemSecurity2[] + + FileSystemSecurity2[] + + + None + + + + + + 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. + + + + + Security2.FileSystemSecurity2[] + + + You can pipe security descriptors that `Get-NTFSSecurityDescriptor` returned to this cmdlet. + + + + + + + Security2.FileSystemOwner + + + The cmdlet returns one object per item. It contains the item itself in `Item`, an `Alphaleonis.Win32.Filesystem.FileInfo` or `DirectoryInfo`, the path of the item in `FullName`, and the owning account in `Owner` and `Account`, both of type `Security2.IdentityReference2`. + + + + + + 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. + The module also adds an `Owner` script property to `System.IO.FileInfo` and `System.IO.DirectoryInfo`, so `(Get-Item C:\Data).Owner` returns the owning account as a `Security2.IdentityReference2` object as well. + + + + + ------------- Example 1: Get the owner of a folder ------------- + PS C:\> Get-NTFSOwner -Path C:\Data + + This command reads the owner of the `C:\Data` folder and returns a single `FileSystemOwner` object. + + + + --- Example 2: Get the owner of every item in a folder tree --- + PS C:\> Get-ChildItem2 -Path C:\Data -Recurse | Get-NTFSOwner + + This command pipes every file and folder below `C:\Data` to `Get-NTFSOwner`. The items bind to `-Path` through the `FullName` alias, so the cmdlet returns one result per item. + + + + -- Example 3: Find items that a specific account does not own -- + PS C:\> Get-ChildItem2 -Path C:\Data -Recurse | Get-NTFSOwner | Where-Object { $_.Account.AccountName -ne 'CONTOSO\JohnDoe' } + + This command returns the items below `C:\Data` whose owner is not `CONTOSO\JohnDoe`. The `AccountName` property holds the resolved account name; compare the `Sid` property instead when an account cannot be resolved. + + + + Example 4: Read the owner from a security descriptor in memory + PS C:\> $sd = Get-NTFSSecurityDescriptor -Path C:\Data +PS C:\> Get-NTFSOwner -SecurityDescriptor $sd + + The first command reads the security descriptor of `C:\Data` into a variable. The second command returns the owner that is stored in that descriptor without reading the file system again. + + + + + + Online Version: + https://github.com/raandree/NTFSSecurity/blob/master/Docs/Cmdlets/Get-NTFSOwner.md + + + Set-NTFSOwner + + + + Get-NTFSSecurityDescriptor + + + + Get-NTFSAccess + + + + Get-ChildItem2 + + + + + + + Get-NTFSSecurityDescriptor + Get + NTFSSecurityDescriptor + + Gets the security descriptor of a file or folder. + + + + 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. 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. `-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. + + + + Get-NTFSSecurityDescriptor + + 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. + + String[] + + String[] + + + None + + + + + + 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. + + String[] + + String[] + + + None + + + + + + 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. + + + + + + + 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`. + + + + + + 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. + + + + + ------ 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. + + + + + + Online Version: + https://github.com/raandree/NTFSSecurity/blob/master/Docs/Cmdlets/Get-NTFSSecurityDescriptor.md + + + Set-NTFSSecurityDescriptor + + + + Get-NTFSAccess + + + + Add-NTFSAccess + + + + Get-NTFSOwner + + + + Get-NTFSInheritance + + + + + + + Get-NTFSSimpleAccess + Get + NTFSSimpleAccess + + Gets the permissions of folders reduced to read, write, and delete. + + + + Reads the access control entries of folders and writes them as `Security2.SimpleFileSystemAccessRule` objects whose rights are reduced to the three values `Read`, `Write`, and `Delete`. Reading rights such as `ReadAttributes` or `Traverse` become `Read`, changing rights such as `CreateFiles`, `WriteAttributes`, `ChangePermissions`, or `TakeOwnership` become `Write`, and `Delete` and `DeleteSubdirectoriesAndFiles` become `Delete`; `FullControl` becomes all three. The result answers who may read, change, or delete in a folder without the detail of the full ACL. + The second simplification is that repetitions are left out. The first folder the cmdlet processes is reported with all of its entries, and for every folder that follows only the entries are reported that its parent folder does not already cover. An entry is covered when the parent has an entry for the same account and access type that includes at least the same simple rights. This makes a recursive listing show where permissions actually change instead of repeating the inherited ones on every level, and it requires the parent folder to be processed before its children, which `Get-ChildItem`, `Get-ChildItem2`, and `Get-Item2` do by default. + `-IncludeRootFolder` is on by default and adds the parent folder of the first path as the baseline for the comparison, which is why the first result usually belongs to the folder above the one that was asked for. Use `-IncludeRootFolder:$false` to start the comparison at the first path itself. + The cmdlet only processes folders; a path that points to a file is skipped silently. Relative paths are resolved against the current location, and the current location is used when `-Path` is omitted. `-ExcludeInherited` and `-ExcludeExplicit` work as in `Get-NTFSAccess`, while `-Account` and `-SecurityDescriptor` are inherited from that cmdlet and have no effect here. + + + + Get-NTFSSimpleAccess + + Path + + Specifies the path of one or more folders whose permissions are reported. Paths that point to a file are skipped. Relative paths are resolved against the current location, and the current location is used when the parameter is omitted. The parameter accepts pipeline input by value and by property name through its alias `FullName`. + + String[] + + String[] + + + None + + + Account + + This parameter is inherited from `Get-NTFSAccess` and has no effect. The cmdlet always returns the entries of all accounts. + + IdentityReference2 + + IdentityReference2 + + + None + + + ExcludeExplicit + + Indicates that the access control entries defined on the folder itself are omitted and only the inherited entries are reported. + + + SwitchParameter + + + False + + + ExcludeInherited + + Indicates that the inherited access control entries are omitted and only the entries defined on the folder itself are reported. + + + SwitchParameter + + + False + + + IncludeRootFolder + + Indicates that the parent folder of the first path is reported as well and serves as the baseline the following folders are compared against. This behavior is on by default; use `-IncludeRootFolder:$false` to start with the first path itself. + + + SwitchParameter + + + False + + + + Get-NTFSSimpleAccess + + SecurityDescriptor + + This parameter is inherited from `Get-NTFSAccess` and has no effect. A security descriptor passed here is ignored, and the cmdlet reads the path in `-Path` or the current location instead. + 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. + + FileSystemSecurity2[] + + FileSystemSecurity2[] + + + None + + + Account + + This parameter is inherited from `Get-NTFSAccess` and has no effect. The cmdlet always returns the entries of all accounts. + + IdentityReference2 + + IdentityReference2 + + + None + + + ExcludeExplicit + + Indicates that the access control entries defined on the folder itself are omitted and only the inherited entries are reported. + + + SwitchParameter + + + False + + + ExcludeInherited + + Indicates that the inherited access control entries are omitted and only the entries defined on the folder itself are reported. + + + SwitchParameter + + + False + + + IncludeRootFolder + + Indicates that the parent folder of the first path is reported as well and serves as the baseline the following folders are compared against. This behavior is on by default; use `-IncludeRootFolder:$false` to start with the first path itself. + + + SwitchParameter + + + False + + + + + + Account + + This parameter is inherited from `Get-NTFSAccess` and has no effect. The cmdlet always returns the entries of all accounts. + + IdentityReference2 + + IdentityReference2 + + + None + + + ExcludeExplicit + + Indicates that the access control entries defined on the folder itself are omitted and only the inherited entries are reported. + + SwitchParameter + + SwitchParameter + + + False + + + ExcludeInherited + + Indicates that the inherited access control entries are omitted and only the entries defined on the folder itself are reported. + + SwitchParameter + + SwitchParameter + + + False + + + IncludeRootFolder + + Indicates that the parent folder of the first path is reported as well and serves as the baseline the following folders are compared against. This behavior is on by default; use `-IncludeRootFolder:$false` to start with the first path itself. + + SwitchParameter + + SwitchParameter + + + False + + + Path + + Specifies the path of one or more folders whose permissions are reported. Paths that point to a file are skipped. Relative paths are resolved against the current location, and the current location is used when the parameter is omitted. The parameter accepts pipeline input by value and by property name through its alias `FullName`. + + String[] + + String[] + + + None + + + SecurityDescriptor + + This parameter is inherited from `Get-NTFSAccess` and has no effect. A security descriptor passed here is ignored, and the cmdlet reads the path in `-Path` or the current location instead. + 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. + + FileSystemSecurity2[] + + FileSystemSecurity2[] + + + None + + + + + + System.String[] + + + One or more paths of folders, piped by value or by the property `FullName`. + + + + + Security2.FileSystemSecurity2[] + + + Security descriptors are accepted by the parameter binder but ignored by this cmdlet. + + + + + Security2.IdentityReference2 + + + An account is accepted by the parameter binder but ignored by this cmdlet. + + + + + + + Security2.SimpleFileSystemAccessRule + + + One object per reported entry, with the folder in `FullName` and `Name`, the account in `Identity`, the access type in `AccessControlType`, and the simplified rights `Read`, `Write`, and `Delete` in `AccessRights`. + + + + + + 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. + The simplified rights hide which exact rights an account holds. Use `Get-NTFSAccess` when you need the full access control entry, and `Get-NTFSEffectiveAccess` when you need the rights that result from all entries together. + + + + + ------ Example 1: Get the simple permissions of a folder ------ + PS C:\> Get-NTFSSimpleAccess -Path C:\Data + + This command shows who may read, write, or delete in `C:\Data`. The permissions of the parent folder are shown first, because `-IncludeRootFolder` is on by default. + + + + ----- Example 2: Find the folders whose permissions differ ----- + PS C:\> Get-ChildItem2 -Path C:\Data -Recurse -Directory | Get-NTFSSimpleAccess + + This command walks the folder tree below `C:\Data` and reports only the entries that a folder does not already inherit in the same form from its parent, which reveals where permissions were added or broken. + + + + Example 3: Report only the permissions defined on the folder itself + PS C:\> Get-NTFSSimpleAccess -Path C:\Data -ExcludeInherited -IncludeRootFolder:$false + + This command shows the explicit entries of `C:\Data` in simplified form and leaves both the inherited entries and the parent folder out of the result. + + + + + + Online Version: + https://github.com/raandree/NTFSSecurity/blob/master/Docs/Cmdlets/Get-NTFSSimpleAccess.md + + + Get-NTFSAccess + + + + Get-NTFSEffectiveAccess + + + + Get-NTFSInheritance + + + + Get-ChildItem2 + + + + + + + Get-Privileges + Get + Privileges + + Gets the privileges in the access token of the current PowerShell process. + + + + The `Get-Privileges` cmdlet reads the access token of the current PowerShell process and returns one `ProcessPrivileges.PrivilegeAndAttributes` object for every privilege the token contains. Each object names the privilege in the `Privilege` property, the raw token attributes in `PrivilegeAttributes`, and the resulting state in `PrivilegeState`, which is `Enabled`, `Disabled`, or `Removed`. + The cmdlet only reads; it never changes a privilege. Use it to check whether the four privileges that NTFSSecurity depends on (Backup, Restore, Take Ownership, and Security) are available before you run the file system cmdlets, and to confirm the result of `Enable-Privileges` and `Disable-Privileges`. + Only privileges that the account holds in this session appear in the list; privileges the account does not have are not listed at all. Because Windows removes the administrative privileges from the token of a session that is not elevated, a standard session returns a much shorter list than an elevated one. + + + + Get-Privileges + + + + + + + None + + + This cmdlet does not accept pipeline input. + + + + + + + ProcessPrivileges.PrivilegeAndAttributes + + + The cmdlet returns one object per privilege in the token of the current process. `Privilege` names the privilege, `PrivilegeAttributes` holds the token attributes as a combination of `Disabled`, `EnabledByDefault`, `Enabled`, `Removed`, and `UsedForAccess`, and `PrivilegeState` reduces those attributes to `Enabled`, `Disabled`, or `Removed`. + + + + + + This cmdlet reads the access token of the current PowerShell process only. It reports no privileges of other processes or sessions, and it changes nothing. Use `Enable-Privileges` and `Disable-Privileges` to change the state of the file system privileges. + Unlike the file system cmdlets of the module, `Get-Privileges` is not affected by the `EnablePrivileges` setting in the `PrivateData` section of NTFSSecurity.psd1 and never enables a privilege on its own. + + + + + ---- Example 1: List the privileges of the current session ---- + PS C:\> Get-Privileges + + This command returns every privilege in the access token of the current PowerShell process together with its state. + + + + Example 2: List only the privileges that are currently enabled + PS C:\> Get-Privileges | Where-Object { $_.PrivilegeState -eq 'Enabled' } + + This command filters the result down to the privileges that are in use, which is a short list in a session that has not enabled anything. + + + + ---- Example 3: Check the privileges that NTFSSecurity uses ---- + PS C:\> Get-Privileges | Where-Object { $_.Privilege -in 'Backup', 'Restore', 'TakeOwnership', 'Security' } + + This command shows the four file system privileges. An empty result means that the session does not hold them, which is the normal case outside an elevated session. + + + + -- Example 4: Test a single privilege before taking ownership -- + PS C:\> (Get-Privileges | Where-Object { $_.Privilege -eq 'TakeOwnership' }).PrivilegeState + + This command returns the state of the Take Ownership privilege alone and returns nothing when the session does not hold it. + + + + + + Online Version: + https://github.com/raandree/NTFSSecurity/blob/master/Docs/Cmdlets/Get-Privileges.md + + + Enable-Privileges + + + + Disable-Privileges + + + + Set-NTFSOwner + + + + Get-NTFSSecurityDescriptor + + + + + + + Move-Item2 + Move + Item2 + + Moves a file or folder to another location, including paths longer than 260 characters. + + + + The `Move-Item2` cmdlet moves the items in `-Path` to the location in `-Destination`. It is the long-path counterpart of the built-in `Move-Item` cmdlet: it works through the AlphaFS library (`Alphaleonis.Win32.Filesystem`), so source and destination may be longer than the 260-character `MAX_PATH` limit. Files and folders can both be moved, and a folder is moved with everything it contains. + How `-Destination` is interpreted depends on what is already there. If the value names an existing folder, the cmdlet keeps the name of the source item and moves it into that folder. In every other case the value is the full path of the new item, which lets you move and rename in one step, or rename an item in place. `-Destination` is resolved against the current location once, when the cmdlet starts. + Without `-Force`, the cmdlet checks whether the destination file already exists and writes a `DestinationFileAlreadyExists` error instead of overwriting it; the move itself then runs with the `CopyAllowed` option, which allows a file to move to a different volume. With `-Force`, the move runs with the `ReplaceExisting` option and overwrites an existing destination item. + The cmdlet supports `-WhatIf` and `-Confirm`, and it writes nothing to the pipeline unless you specify `-PassThru $true`. + + + + Move-Item2 + + Path + + Specifies the path of one or more items to move. Relative paths are resolved against the current location, and wildcard characters are not supported. The parameter accepts pipeline input by value and by the property name `FullName`, so you can pipe the output of `Get-ChildItem2` or `Get-Item2` into this cmdlet. + + String[] + + String[] + + + None + + + Destination + + Specifies the target of the move operation. If the value names an existing folder, the cmdlet moves the item into that folder under its current name; otherwise the value is the full path of the new item. The path is resolved against the current location once, when the cmdlet starts, so pass an absolute path when you supply `-Destination` through the pipeline. + + String + + String + + + None + + + Confirm + + Prompts you for confirmation before running the cmdlet. + + + SwitchParameter + + + False + + + Force + + Indicates that the cmdlet replaces an existing destination item. Without `-Force`, an existing destination file causes the error `DestinationFileAlreadyExists` and the item is not moved. + + + SwitchParameter + + + False + + + PassThru + + Specifies whether the cmdlet returns an object for each item that it moved. This parameter is typed `Boolean` rather than a switch, so it needs an explicit value, as in `-PassThru $true`. By default, the cmdlet produces no output. The returned object describes the item at its new location. + + Boolean + + Boolean + + + None + + + WhatIf + + Shows what would happen if the cmdlet runs. The cmdlet is not run. + + + SwitchParameter + + + False + + + + + + Confirm + + Prompts you for confirmation before running the cmdlet. + + SwitchParameter + + SwitchParameter + + + False + + + Destination + + Specifies the target of the move operation. If the value names an existing folder, the cmdlet moves the item into that folder under its current name; otherwise the value is the full path of the new item. The path is resolved against the current location once, when the cmdlet starts, so pass an absolute path when you supply `-Destination` through the pipeline. + + String + + String + + + None + + + Force + + Indicates that the cmdlet replaces an existing destination item. Without `-Force`, an existing destination file causes the error `DestinationFileAlreadyExists` and the item is not moved. + + SwitchParameter + + SwitchParameter + + + False + + + PassThru + + Specifies whether the cmdlet returns an object for each item that it moved. This parameter is typed `Boolean` rather than a switch, so it needs an explicit value, as in `-PassThru $true`. By default, the cmdlet produces no output. The returned object describes the item at its new location. + + Boolean + + Boolean + + + None + + + Path + + Specifies the path of one or more items to move. Relative paths are resolved against the current location, and wildcard characters are not supported. The parameter accepts pipeline input by value and by the property name `FullName`, so you can pipe the output of `Get-ChildItem2` or `Get-Item2` into this cmdlet. + + String[] + + String[] + + + None + + + WhatIf + + Shows what would happen if the cmdlet runs. The cmdlet is not run. + + SwitchParameter + + SwitchParameter + + + False + + + + + + System.String[] + + + You can pipe one or more paths to this cmdlet, either as strings or as objects that have a `FullName` property, such as the output of `Get-ChildItem2` or `Get-Item2`. + + + + + System.String + + + You can pipe an object that has a `Destination` property to supply the target of the move operation. + + + + + + + System.Object + + + By default this cmdlet returns nothing. With `-PassThru $true` it returns an `Alphaleonis.Win32.Filesystem.FileInfo` or `Alphaleonis.Win32.Filesystem.DirectoryInfo` object for each item that it moved, pointing at the new location. + + + + + + `Move-Item2` moves through the AlphaFS library (`Alphaleonis.Win32.Filesystem`), which is why it handles source and destination paths that exceed the 260-character `MAX_PATH` limit of the built-in `Move-Item` cmdlet. + The cmdlet chooses between two mutually exclusive move options. Without `-Force` it moves with `CopyAllowed`, which permits a file to cross volume boundaries because Windows then copies and deletes it. With `-Force` it moves with `ReplaceExisting`, which overwrites the destination but does not request `CopyAllowed`, so a move across volumes can fail when `-Force` is specified. + If a path in `-Path` does not exist or the destination file exists and `-Force` is missing, the cmdlet writes a non-terminating error and skips the remaining paths that were passed in the same call. Items that arrive one by one through the pipeline are not affected, because each of them is processed separately. + + + + + ------------- Example 1: Move a file into a folder ------------- + PS C:\> Move-Item2 -Path C:\Data\report.docx -Destination C:\Data\Archive + + Moves `report.docx` into the existing folder `C:\Data\Archive`, where it keeps its name. + + + + ------------------ Example 2: Rename an item ------------------ + PS C:\> Move-Item2 -Path C:\Data\Archive\report.docx -Destination C:\Data\Archive\report-2026.docx + + Moves the file to a new path inside the same folder, which renames it. + + + + -------- Example 3: Move a folder with a very long path -------- + PS C:\> Move-Item2 -Path C:\Data\Projects\Archive\2026\Q1\Reports\Regional\Northwest -Destination C:\Data\Archive\Northwest -PassThru $true + + Moves the folder and everything it contains, even when the paths below it exceed 260 characters, and returns the folder object at its new location. + + + + ------------- Example 4: Preview a move operation ------------- + PS C:\> Get-ChildItem2 -Path C:\Data -File -Filter '*.tmp' | Move-Item2 -Destination C:\Data\Temp -WhatIf + + Shows which temporary files the cmdlet would move into `C:\Data\Temp` without moving anything. Remove `-WhatIf` to carry the operation out. + + + + + + Online Version: + https://github.com/raandree/NTFSSecurity/blob/master/Docs/Cmdlets/Move-Item2.md + + + Copy-Item2 + + + + Remove-Item2 + + + + Get-ChildItem2 + + + + Get-Item2 + + + + Test-Path2 + + + + + + + New-NTFSHardLink + New + NTFSHardLink + + Creates a hard link to an existing file. + + + + The `New-NTFSHardLink` cmdlet gives an existing file an additional name. `-Path` is the new hard link that the cmdlet creates, and `-Target` is the existing file that the new link refers to. Read the command as "create Path , which points to Target ". + The cmdlet validates both ends before it creates the link. `-Path` must not exist yet, so the cmdlet never overwrites an existing file, and `-Target` must exist and must be a file. A folder as `-Target` is rejected, because NTFS supports hard links for files only. Relative paths are resolved against the current location. + After the link is created, both names refer to the same data on the volume. Writing through one name changes what the other name returns, and the file is only released when its last name is deleted. + By default the cmdlet produces no output. With `-PassThru` it returns one object for every hard link that the file has after the operation, which includes the original name and the new link, not just the link that was created. + + + + New-NTFSHardLink + + Path + + Specifies the path of the new hard link that the cmdlet creates. The path must not exist yet, and it must be on the same NTFS volume as `-Target`. Relative paths are resolved against the current location. + + String + + String + + + None + + + Target + + Specifies the path of the existing file that the new link refers to. The target must exist and must be a file; folders are rejected, because NTFS supports hard links for files only. + + String + + String + + + None + + + PassThru + + Indicates that the cmdlet returns an object for every hard link of the file after the new link has been created, including the names that already existed. By default, this cmdlet produces no output. + + + SwitchParameter + + + False + + + + + + PassThru + + Indicates that the cmdlet returns an object for every hard link of the file after the new link has been created, including the names that already existed. By default, this cmdlet produces no output. + + SwitchParameter + + SwitchParameter + + + False + + + Path + + Specifies the path of the new hard link that the cmdlet creates. The path must not exist yet, and it must be on the same NTFS volume as `-Target`. Relative paths are resolved against the current location. + + String + + String + + + None + + + Target + + Specifies the path of the existing file that the new link refers to. The target must exist and must be a file; folders are rejected, because NTFS supports hard links for files only. + + String + + String + + + None + + + + + + System.String + + + You can pass the path of the new link and the path of the target as strings. + + + + + + + Alphaleonis.Win32.Filesystem.FileInfo + + + With `-PassThru`, the cmdlet writes one file object per hard link of the file, extended with a `Mode` property that renders the file attributes in the same notation as `Get-ChildItem2`. Without `-PassThru`, the cmdlet writes nothing. + + + + + Alphaleonis.Win32.Filesystem.DirectoryInfo + + + The cmdlet never writes folder objects, because hard links are supported for files only. + + + + + + Windows supports hard links only for files on the same NTFS volume. A link that points to a file on another volume, or a target on a file system that does not implement hard links, cannot be created. + The cmdlet does not overwrite anything. If `-Path` already exists, or if `-Target` is missing or is a folder, the cmdlet reports an error and leaves the file system unchanged. + Because all names of a file share the same data, the number of hard links is a property of the file, not of an individual name. Use `Get-NTFSHardLink` to list them, and delete a link with `Remove-Item2` or `Remove-Item`, which removes only that name as long as other names remain. + + + + + ------------- Example 1: Give a file a second name ------------- + PS C:\> New-NTFSHardLink -Path C:\Data\Report-Current.txt -Target C:\Data\Report-2026.txt + + This command creates the new hard link `Report-Current.txt` for the existing file `Report-2026.txt`. Both names now refer to the same data, and no second copy of the content is stored. + + + + --- Example 2: Create a hard link with positional parameters --- + PS C:\> New-NTFSHardLink C:\Data\Archive\Report.txt C:\Data\Report.txt + + This command uses the positional form of the parameters. The first position is `-Path`, the new link, and the second position is `-Target`, the existing file. Both paths are on drive C, as a hard link and its target must be on the same volume. + + + + --- Example 3: Create a link and list all names of the file --- + PS C:\> New-NTFSHardLink -Path C:\Data\Report-Current.txt -Target C:\Data\Report-2026.txt -PassThru + + This command creates the link and then returns one object for every hard link of the file, so the output contains both `Report-2026.txt` and the new `Report-Current.txt`. + + + + ----------------- Example 4: Verify the result ----------------- + PS C:\> Get-NTFSHardLink -Path C:\Data\Report-2026.txt | Select-Object -ExpandProperty FullName + + This command lists all names of the file after the link was created, which is the same information that `-PassThru` returns. + + + + + + Online Version: + https://github.com/raandree/NTFSSecurity/blob/master/Docs/Cmdlets/New-NTFSHardLink.md + + + Get-NTFSHardLink + + + + New-NTFSSymbolicLink + + + + Get-ChildItem2 + + + + Remove-Item2 + + + + + + + New-NTFSSymbolicLink + New + NTFSSymbolicLink + + Creates a symbolic link to an existing file or folder. + + + + The `New-NTFSSymbolicLink` cmdlet creates a symbolic link that redirects to another file or folder. `-Path` is the new link that the cmdlet creates, and `-Target` is the existing item that the link points to. Read the command as "create Path , which points to Target ". + The cmdlet inspects the target first and creates a file symbolic link when the target is a file and a directory symbolic link when the target is a folder, so you do not select the link type yourself. `-Target` must exist when the link is created, and `-Path` must not exist yet, so the cmdlet never overwrites an existing item. + Relative paths are resolved against the current location before the link is created, which means that the link always stores an absolute target path. + By default the cmdlet produces no output. With `-PassThru` it returns a file object for the new link, including for a link that points to a folder. + + + + New-NTFSSymbolicLink + + Path + + Specifies the path of the new symbolic link that the cmdlet creates. The path must not exist yet. Relative paths are resolved against the current location. + + String + + String + + + None + + + Target + + Specifies the path of the existing file or folder that the new link points to. The target must exist when the link is created and determines whether the cmdlet creates a file symbolic link or a directory symbolic link. Relative paths are resolved against the current location, so the link stores an absolute target path. + + String + + String + + + None + + + PassThru + + Indicates that the cmdlet returns an object for the new link. By default, this cmdlet produces no output. The returned object is a file object even when the link points to a folder. + + + SwitchParameter + + + False + + + + + + PassThru + + Indicates that the cmdlet returns an object for the new link. By default, this cmdlet produces no output. The returned object is a file object even when the link points to a folder. + + SwitchParameter + + SwitchParameter + + + False + + + Path + + Specifies the path of the new symbolic link that the cmdlet creates. The path must not exist yet. Relative paths are resolved against the current location. + + String + + String + + + None + + + Target + + Specifies the path of the existing file or folder that the new link points to. The target must exist when the link is created and determines whether the cmdlet creates a file symbolic link or a directory symbolic link. Relative paths are resolved against the current location, so the link stores an absolute target path. + + String + + String + + + None + + + + + + System.String + + + You can pass the path of the new link and the path of the target as strings. + + + + + + + Alphaleonis.Win32.Filesystem.FileInfo + + + With `-PassThru`, the cmdlet writes a file object for the new link. The cmdlet writes that object type for a link to a folder as well. Without `-PassThru`, the cmdlet writes nothing. + + + + + Alphaleonis.Win32.Filesystem.DirectoryInfo + + + The cmdlet does not write folder objects. A directory symbolic link is also returned as a file object. + + + + + + Creating a symbolic link on Windows requires the "Create symbolic links" user right, `SeCreateSymbolicLinkPrivilege`, which is granted to the Administrators group by default. Without that right, Windows rejects the operation with error 1314, "A required privilege is not held by the client", so run the cmdlet from an elevated session or grant the right to the account. On a computer that runs in Windows Developer Mode, Windows also allows accounts without that right to create symbolic links. + Unlike a hard link, a symbolic link is a separate file system entry that stores a path, so it can point to an item on another volume and the link and its target can be managed independently. The cmdlet still requires the target to exist at the moment the link is created. If the target is removed later, the link remains and stops resolving. + Deleting a symbolic link removes the link only and leaves the target untouched. Delete a directory symbolic link as a link rather than recursively, so that the content of the target folder is not affected. + + + + + --------- Example 1: Create a symbolic link to a file --------- + PS C:\> New-NTFSSymbolicLink -Path C:\Data\Report-Current.txt -Target C:\Data\Archive\Report-2026.txt + + This command creates the symbolic link `Report-Current.txt`, which redirects to the existing file `Report-2026.txt`. Because the target is a file, the cmdlet creates a file symbolic link. + + + + -------- Example 2: Create a symbolic link to a folder -------- + PS C:\> New-NTFSSymbolicLink -Path C:\Data\Current -Target C:\Data\Archive\2026 + + This command creates the symbolic link `C:\Data\Current`, which redirects to the existing folder `C:\Data\Archive\2026`. Because the target is a folder, the cmdlet creates a directory symbolic link, and paths below `C:\Data\Current` resolve to the corresponding items in the target folder. + + + + ------------ Example 3: Create a link and return it ------------ + PS C:\> New-NTFSSymbolicLink -Path C:\Data\Current -Target C:\Data\Archive\2026 -PassThru + + This command creates the link and returns an object for the new link, which you can use to confirm the result in a script. + + + + ----------- Example 4: Verify that the link resolves ----------- + PS C:\> Test-Path2 -Path C:\Data\Current\Report.txt -PathType Leaf + + This command tests a path that leads through the symbolic link. It returns `$true` when the link resolves and the file exists in the target folder. + + + + + + Online Version: + https://github.com/raandree/NTFSSecurity/blob/master/Docs/Cmdlets/New-NTFSSymbolicLink.md + + + New-NTFSHardLink + + + + Get-NTFSHardLink + + + + Get-ChildItem2 + + + + Test-Path2 + + + + + + + Remove-Item2 + Remove + Item2 + + Deletes a file or folder, including paths longer than 260 characters. + + + + The `Remove-Item2` cmdlet deletes the files and folders in `-Path`. It is the long-path counterpart of the built-in `Remove-Item` cmdlet: it works through the AlphaFS library (`Alphaleonis.Win32.Filesystem`), so it also deletes items whose path exceeds the 260-character `MAX_PATH` limit. The items are deleted permanently and are not moved to the Recycle Bin. + Relative paths and the `.` and `..` notations are resolved against the current location, and wildcard characters are not supported. `-Path` has no default value: if you omit it, the cmdlet does nothing. Use `-Recurse` to delete a folder that is not empty and `-Force` to delete items that have the read-only attribute. + The cmdlet supports `-WhatIf` and `-Confirm`, and it writes nothing to the pipeline unless you specify `-PassThru`. + + + + Remove-Item2 + + Path + + Specifies the path of one or more items to delete. Relative paths are resolved against the current location, and wildcard characters are not supported. The parameter has no default value, so the cmdlet deletes nothing if you omit it. It accepts pipeline input by value and by the property name `FullName`, so you can pipe the output of `Get-ChildItem2` or `Get-Item2` into this cmdlet. + + String[] + + String[] + + + None + + + Confirm + + Prompts you for confirmation before running the cmdlet. + + + SwitchParameter + + + False + + + Force + + Indicates that the cmdlet also deletes items that have the read-only attribute. Without `-Force`, a read-only item causes a `DeleteError`. Combine `-Force` with `-Recurse` to delete a folder that contains read-only files. + + + SwitchParameter + + + False + + + PassThru + + Indicates that the cmdlet returns an object for each item that it deleted. By default, the cmdlet produces no output. The object describes a path that no longer exists, so use it for logging rather than for further file operations. In NTFSSecurity 4.2.6 and earlier, this parameter is spelled `-PassThur`. + + + SwitchParameter + + + False + + + Recurse + + Indicates that the cmdlet deletes a folder together with everything it contains. Without `-Recurse`, a folder that is not empty causes a `DeleteError`. The parameter has no effect on files. + + + SwitchParameter + + + False + + + WhatIf + + Shows what would happen if the cmdlet runs. The cmdlet is not run. + + + SwitchParameter + + + False + + + + + + Confirm + + Prompts you for confirmation before running the cmdlet. + + SwitchParameter + + SwitchParameter + + + False + + + Force + + Indicates that the cmdlet also deletes items that have the read-only attribute. Without `-Force`, a read-only item causes a `DeleteError`. Combine `-Force` with `-Recurse` to delete a folder that contains read-only files. + + SwitchParameter + + SwitchParameter + + + False + + + PassThru + + Indicates that the cmdlet returns an object for each item that it deleted. By default, the cmdlet produces no output. The object describes a path that no longer exists, so use it for logging rather than for further file operations. In NTFSSecurity 4.2.6 and earlier, this parameter is spelled `-PassThur`. + + SwitchParameter + + SwitchParameter + + + False + + + Path + + Specifies the path of one or more items to delete. Relative paths are resolved against the current location, and wildcard characters are not supported. The parameter has no default value, so the cmdlet deletes nothing if you omit it. It accepts pipeline input by value and by the property name `FullName`, so you can pipe the output of `Get-ChildItem2` or `Get-Item2` into this cmdlet. + + String[] + + String[] + + + None + + + Recurse + + Indicates that the cmdlet deletes a folder together with everything it contains. Without `-Recurse`, a folder that is not empty causes a `DeleteError`. The parameter has no effect on files. + + SwitchParameter + + SwitchParameter + + + False + + + WhatIf + + Shows what would happen if the cmdlet runs. The cmdlet is not run. + + SwitchParameter + + SwitchParameter + + + False + + + + + + System.String[] + + + You can pipe one or more paths to this cmdlet, either as strings or as objects that have a `FullName` property, such as the output of `Get-ChildItem2` or `Get-Item2`. + + + + + + + System.Object + + + By default this cmdlet returns nothing. With `-PassThru` it returns an `Alphaleonis.Win32.Filesystem.FileInfo` or `Alphaleonis.Win32.Filesystem.DirectoryInfo` object for each item that it deleted. + + + + + + `Remove-Item2` deletes through the AlphaFS library (`Alphaleonis.Win32.Filesystem`), which is why it reaches items whose path exceeds the 260-character `MAX_PATH` limit of the built-in `Remove-Item` cmdlet. Deletion is permanent; the cmdlet does not use the Recycle Bin. + The module defines the aliases `rm2` and `del2` for this cmdlet. + A path that does not exist causes the error `FileNotFound`, and a deletion that the file system rejects causes a `DeleteError`. In both cases the cmdlet skips the remaining paths that were passed in the same call. Items that arrive one by one through the pipeline are not affected, because each of them is processed separately. + + + + + ------------------- Example 1: Delete a file ------------------- + PS C:\> Remove-Item2 -Path C:\Data\report.docx + + Deletes a single file. If the file is read-only, the command fails with a `DeleteError` until you add `-Force`. + + + + ----- Example 2: Delete a folder tree with very long paths ----- + PS C:\> Remove-Item2 -Path C:\Data\Projects\Archive -Recurse -Force + + Deletes the folder with everything it contains, including read-only files and files whose path is too long for the built-in `Remove-Item` cmdlet. + + + + ----------- Example 3: Preview what would be deleted ----------- + PS C:\> Get-ChildItem2 -Path C:\Data -Recurse -File -Filter '*.tmp' | Remove-Item2 -WhatIf + + Lists every temporary file below `C:\Data` and shows which of them the cmdlet would delete. Remove `-WhatIf` to delete them. + + + + ------ Example 4: Delete items and keep a record of them ------ + PS C:\> rm2 -Path C:\Data\Logs\old.log -PassThru | Select-Object -ExpandProperty FullName + + Uses the `rm2` alias and returns the object of the deleted file, from which the command takes the full path for a log. Since the item no longer exists, only its path information is still meaningful; properties such as `Length` are empty. + + + + + + Online Version: + https://github.com/raandree/NTFSSecurity/blob/master/Docs/Cmdlets/Remove-Item2.md + + + Copy-Item2 + + + + Move-Item2 + + + + Get-ChildItem2 + + + + Get-Item2 + + + + Test-Path2 + + + + + + + Remove-NTFSAccess + Remove + NTFSAccess + + Removes rights from the access control entries (ACEs) of a file, a folder, or a security descriptor. + + + + Removes the rights in `-AccessRights` from the access control entries (ACEs) of a file or a folder. An entry is addressed by the account in `-Account`, the access type in `-AccessType`, and the inheritance and propagation flags, which are given either as `-AppliesTo` or as `-InheritanceFlags` and `-PropagationFlags`. + Only the specified rights are taken away: when an entry grants more than `-AccessRights` names, the remaining rights stay in place, and the entry disappears only when all of its rights are removed. An `Allow` entry is always matched with the `Synchronize` right added to the specified rights. The flags must describe the entry as it exists on the item; when they do not, Windows splits the entry instead of removing the rights, so use the values that `Get-NTFSAccess` reports for the entry you want to change. + Inherited entries cannot be removed from the item that inherits them. Remove them from the folder named in the `InheritedFrom` property, or run `Disable-NTFSAccessInheritance` on the item first, which copies the inherited entries into it as explicit ones that this cmdlet can then remove. + The cmdlet has four parameter sets. The `Path` sets read the item from disk and write the changed DACL back immediately, while the `SD` sets change a `Security2.FileSystemSecurity2` object returned by `Get-NTFSSecurityDescriptor` in memory until `Set-NTFSSecurityDescriptor` writes it back. The `Simple` sets take `-AppliesTo`, the `Complex` sets take `-InheritanceFlags` and `-PropagationFlags`, and `PathComplex` is the default. A command that works on a security descriptor, whether it is passed to `-SecurityDescriptor` or piped in, must therefore name `-AppliesTo` or `-InheritanceFlags` and `-PropagationFlags`; without one of them PowerShell cannot choose between the two `SD` sets and reports that the parameter set cannot be resolved. All relevant parameters bind by property name, so the output of `Get-NTFSAccess` and `Get-NTFSOrphanedAccess` can be piped directly into this cmdlet. The cmdlet writes no output unless `-PassThru` is used. + + + + Remove-NTFSAccess + + Path + + Specifies the path of one or more files or folders whose access control entries are changed. Relative paths are resolved against the current location. The parameter accepts pipeline input by value and by property name through its alias `FullName`. + + String[] + + String[] + + + None + + + Account + + Specifies one or more accounts or groups whose entries are changed. 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-21-1234567890-1234567890-1234567890-1001`, which is how the entries of deleted accounts are addressed. + + IdentityReference2[] + + IdentityReference2[] + + + None + + + AccessRights + + Specifies the rights to remove from the matching access control entry. The parameter accepts basic rights such as `Read`, `ReadAndExecute`, `Modify`, and `FullControl`, granular rights such as `CreateFiles`, `Traverse`, or `WriteAttributes`, and any combination of them. Rights that the entry grants but that are not listed here remain in place. For how the values relate to the Windows security dialog, see Concepts (../Concepts.md). + + + None + ReadData + ListDirectory + WriteData + CreateFiles + AppendData + CreateDirectories + ReadExtendedAttributes + WriteExtendedAttributes + ExecuteFile + Traverse + DeleteSubdirectoriesAndFiles + ReadAttributes + WriteAttributes + Write + Delete + ReadPermissions + Read + ReadAndExecute + Modify + ChangePermissions + TakeOwnership + Synchronize + FullControl + GenericAll + GenericExecute + GenericWrite + GenericRead + + FileSystemRights2 + + FileSystemRights2 + + + None + + + AccessType + + Specifies whether an `Allow` or a `Deny` entry is addressed. The default is `Allow`. An entry of the other type is not touched. + + + Allow + Deny + + AccessControlType + + AccessControlType + + + Allow + + + AppliesTo + + Specifies the scope of the entry that is addressed, in the wording of the Windows security dialog, for example `ThisFolderOnly`, `ThisFolderAndSubfolders`, or `SubfoldersAndFilesOnly`. The cmdlet translates the value into the equivalent inheritance and propagation flags, so this parameter and the pair `-InheritanceFlags` and `-PropagationFlags` are two ways to describe the same entry. Use the scope that `Get-NTFSAccess` shows in the "Applies to" column of the entry. + + + ThisFolderOnly + ThisFolderSubfoldersAndFiles + ThisFolderAndSubfolders + ThisFolderAndFiles + SubfoldersAndFilesOnly + SubfoldersOnly + FilesOnly + ThisFolderSubfoldersAndFilesOneLevel + ThisFolderAndSubfoldersOneLevel + ThisFolderAndFilesOneLevel + SubfoldersAndFilesOnlyOneLevel + SubfoldersOnlyOneLevel + FilesOnlyOneLevel + + ApplyTo + + ApplyTo + + + None + + + PassThru + + Indicates that the cmdlet writes the access control entries of every processed item, explicit and inherited, after the change. Without this switch the cmdlet produces no output. + + + SwitchParameter + + + False + + + + Remove-NTFSAccess + + SecurityDescriptor + + Specifies one or more `Security2.FileSystemSecurity2` objects, as returned by `Get-NTFSSecurityDescriptor`, whose access control entries are changed. The change is made in memory only; use `Set-NTFSSecurityDescriptor` to write it to the file system. + 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. + + FileSystemSecurity2[] + + FileSystemSecurity2[] + + + None + + + Account + + Specifies one or more accounts or groups whose entries are changed. 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-21-1234567890-1234567890-1234567890-1001`, which is how the entries of deleted accounts are addressed. + + IdentityReference2[] + + IdentityReference2[] + + + None + + + AccessRights + + Specifies the rights to remove from the matching access control entry. The parameter accepts basic rights such as `Read`, `ReadAndExecute`, `Modify`, and `FullControl`, granular rights such as `CreateFiles`, `Traverse`, or `WriteAttributes`, and any combination of them. Rights that the entry grants but that are not listed here remain in place. For how the values relate to the Windows security dialog, see Concepts (../Concepts.md). + + + None + ReadData + ListDirectory + WriteData + CreateFiles + AppendData + CreateDirectories + ReadExtendedAttributes + WriteExtendedAttributes + ExecuteFile + Traverse + DeleteSubdirectoriesAndFiles + ReadAttributes + WriteAttributes + Write + Delete + ReadPermissions + Read + ReadAndExecute + Modify + ChangePermissions + TakeOwnership + Synchronize + FullControl + GenericAll + GenericExecute + GenericWrite + GenericRead + + FileSystemRights2 + + FileSystemRights2 + + + None + + + AccessType + + Specifies whether an `Allow` or a `Deny` entry is addressed. The default is `Allow`. An entry of the other type is not touched. + + + Allow + Deny + + AccessControlType + + AccessControlType + + + Allow + + + AppliesTo + + Specifies the scope of the entry that is addressed, in the wording of the Windows security dialog, for example `ThisFolderOnly`, `ThisFolderAndSubfolders`, or `SubfoldersAndFilesOnly`. The cmdlet translates the value into the equivalent inheritance and propagation flags, so this parameter and the pair `-InheritanceFlags` and `-PropagationFlags` are two ways to describe the same entry. Use the scope that `Get-NTFSAccess` shows in the "Applies to" column of the entry. + + + ThisFolderOnly + ThisFolderSubfoldersAndFiles + ThisFolderAndSubfolders + ThisFolderAndFiles + SubfoldersAndFilesOnly + SubfoldersOnly + FilesOnly + ThisFolderSubfoldersAndFilesOneLevel + ThisFolderAndSubfoldersOneLevel + ThisFolderAndFilesOneLevel + SubfoldersAndFilesOnlyOneLevel + SubfoldersOnlyOneLevel + FilesOnlyOneLevel + + ApplyTo + + ApplyTo + + + None + + + PassThru + + Indicates that the cmdlet writes the access control entries of every processed item, explicit and inherited, after the change. Without this switch the cmdlet produces no output. + + + SwitchParameter + + + False + + + + Remove-NTFSAccess + + Path + + Specifies the path of one or more files or folders whose access control entries are changed. Relative paths are resolved against the current location. The parameter accepts pipeline input by value and by property name through its alias `FullName`. + + String[] + + String[] + + + None + + + Account + + Specifies one or more accounts or groups whose entries are changed. 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-21-1234567890-1234567890-1234567890-1001`, which is how the entries of deleted accounts are addressed. + + IdentityReference2[] + + IdentityReference2[] + + + None + + + AccessRights + + Specifies the rights to remove from the matching access control entry. The parameter accepts basic rights such as `Read`, `ReadAndExecute`, `Modify`, and `FullControl`, granular rights such as `CreateFiles`, `Traverse`, or `WriteAttributes`, and any combination of them. Rights that the entry grants but that are not listed here remain in place. For how the values relate to the Windows security dialog, see Concepts (../Concepts.md). + + + None + ReadData + ListDirectory + WriteData + CreateFiles + AppendData + CreateDirectories + ReadExtendedAttributes + WriteExtendedAttributes + ExecuteFile + Traverse + DeleteSubdirectoriesAndFiles + ReadAttributes + WriteAttributes + Write + Delete + ReadPermissions + Read + ReadAndExecute + Modify + ChangePermissions + TakeOwnership + Synchronize + FullControl + GenericAll + GenericExecute + GenericWrite + GenericRead + + FileSystemRights2 + + FileSystemRights2 + + + None + + + AccessType + + Specifies whether an `Allow` or a `Deny` entry is addressed. The default is `Allow`. An entry of the other type is not touched. + + + Allow + Deny + + AccessControlType + + AccessControlType + + + Allow + + + InheritanceFlags + + Specifies the inheritance flags of the entry that is addressed. `ContainerInherit` marks an entry that child folders inherit, `ObjectInherit` marks an entry that child files inherit, and `None` marks an entry that is not inherited at all. The default is `ContainerInherit, ObjectInherit`, which is the scope `ThisFolderSubfoldersAndFiles`. Entries on files always carry `None`. + + + None + ContainerInherit + ObjectInherit + + InheritanceFlags + + InheritanceFlags + + + ContainerInherit, ObjectInherit + + + PassThru + + Indicates that the cmdlet writes the access control entries of every processed item, explicit and inherited, after the change. Without this switch the cmdlet produces no output. + + + SwitchParameter + + + False + + + PropagationFlags + + Specifies the propagation flags of the entry that is addressed. `None` marks an entry that is inherited by all levels allowed by its inheritance flags, `InheritOnly` marks an entry that does not apply to the item it is defined on, and `NoPropagateInherit` marks an entry that is only inherited by the direct children of the folder. The default is `None`. + + + None + NoPropagateInherit + InheritOnly + + PropagationFlags + + PropagationFlags + + + None + + + + Remove-NTFSAccess + + SecurityDescriptor + + Specifies one or more `Security2.FileSystemSecurity2` objects, as returned by `Get-NTFSSecurityDescriptor`, whose access control entries are changed. The change is made in memory only; use `Set-NTFSSecurityDescriptor` to write it to the file system. + 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. + + FileSystemSecurity2[] + + FileSystemSecurity2[] + + + None + + + Account + + Specifies one or more accounts or groups whose entries are changed. 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-21-1234567890-1234567890-1234567890-1001`, which is how the entries of deleted accounts are addressed. + + IdentityReference2[] + + IdentityReference2[] + + + None + + + AccessRights + + Specifies the rights to remove from the matching access control entry. The parameter accepts basic rights such as `Read`, `ReadAndExecute`, `Modify`, and `FullControl`, granular rights such as `CreateFiles`, `Traverse`, or `WriteAttributes`, and any combination of them. Rights that the entry grants but that are not listed here remain in place. For how the values relate to the Windows security dialog, see Concepts (../Concepts.md). + + + None + ReadData + ListDirectory + WriteData + CreateFiles + AppendData + CreateDirectories + ReadExtendedAttributes + WriteExtendedAttributes + ExecuteFile + Traverse + DeleteSubdirectoriesAndFiles + ReadAttributes + WriteAttributes + Write + Delete + ReadPermissions + Read + ReadAndExecute + Modify + ChangePermissions + TakeOwnership + Synchronize + FullControl + GenericAll + GenericExecute + GenericWrite + GenericRead + + FileSystemRights2 + + FileSystemRights2 + + + None + + + AccessType + + Specifies whether an `Allow` or a `Deny` entry is addressed. The default is `Allow`. An entry of the other type is not touched. + + + Allow + Deny + + AccessControlType + + AccessControlType + + + Allow + + + InheritanceFlags + + Specifies the inheritance flags of the entry that is addressed. `ContainerInherit` marks an entry that child folders inherit, `ObjectInherit` marks an entry that child files inherit, and `None` marks an entry that is not inherited at all. The default is `ContainerInherit, ObjectInherit`, which is the scope `ThisFolderSubfoldersAndFiles`. Entries on files always carry `None`. + + + None + ContainerInherit + ObjectInherit + + InheritanceFlags + + InheritanceFlags + + + ContainerInherit, ObjectInherit + + + PassThru + + Indicates that the cmdlet writes the access control entries of every processed item, explicit and inherited, after the change. Without this switch the cmdlet produces no output. + + + SwitchParameter + + + False + + + PropagationFlags + + Specifies the propagation flags of the entry that is addressed. `None` marks an entry that is inherited by all levels allowed by its inheritance flags, `InheritOnly` marks an entry that does not apply to the item it is defined on, and `NoPropagateInherit` marks an entry that is only inherited by the direct children of the folder. The default is `None`. + + + None + NoPropagateInherit + InheritOnly + + PropagationFlags + + PropagationFlags + + + None + + + + + + AccessRights + + Specifies the rights to remove from the matching access control entry. The parameter accepts basic rights such as `Read`, `ReadAndExecute`, `Modify`, and `FullControl`, granular rights such as `CreateFiles`, `Traverse`, or `WriteAttributes`, and any combination of them. Rights that the entry grants but that are not listed here remain in place. For how the values relate to the Windows security dialog, see Concepts (../Concepts.md). + + FileSystemRights2 + + FileSystemRights2 + + + None + + + AccessType + + Specifies whether an `Allow` or a `Deny` entry is addressed. The default is `Allow`. An entry of the other type is not touched. + + AccessControlType + + AccessControlType + + + Allow + + + Account + + Specifies one or more accounts or groups whose entries are changed. 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-21-1234567890-1234567890-1234567890-1001`, which is how the entries of deleted accounts are addressed. + + IdentityReference2[] + + IdentityReference2[] + + + None + + + AppliesTo + + Specifies the scope of the entry that is addressed, in the wording of the Windows security dialog, for example `ThisFolderOnly`, `ThisFolderAndSubfolders`, or `SubfoldersAndFilesOnly`. The cmdlet translates the value into the equivalent inheritance and propagation flags, so this parameter and the pair `-InheritanceFlags` and `-PropagationFlags` are two ways to describe the same entry. Use the scope that `Get-NTFSAccess` shows in the "Applies to" column of the entry. + + ApplyTo + + ApplyTo + + + None + + + InheritanceFlags + + Specifies the inheritance flags of the entry that is addressed. `ContainerInherit` marks an entry that child folders inherit, `ObjectInherit` marks an entry that child files inherit, and `None` marks an entry that is not inherited at all. The default is `ContainerInherit, ObjectInherit`, which is the scope `ThisFolderSubfoldersAndFiles`. Entries on files always carry `None`. + + InheritanceFlags + + InheritanceFlags + + + ContainerInherit, ObjectInherit + + + PassThru + + Indicates that the cmdlet writes the access control entries of every processed item, explicit and inherited, after the change. Without this switch the cmdlet produces no output. + + SwitchParameter + + SwitchParameter + + + False + + + Path + + Specifies the path of one or more files or folders whose access control entries are changed. Relative paths are resolved against the current location. The parameter accepts pipeline input by value and by property name through its alias `FullName`. + + String[] + + String[] + + + None + + + PropagationFlags + + Specifies the propagation flags of the entry that is addressed. `None` marks an entry that is inherited by all levels allowed by its inheritance flags, `InheritOnly` marks an entry that does not apply to the item it is defined on, and `NoPropagateInherit` marks an entry that is only inherited by the direct children of the folder. The default is `None`. + + PropagationFlags + + PropagationFlags + + + None + + + SecurityDescriptor + + Specifies one or more `Security2.FileSystemSecurity2` objects, as returned by `Get-NTFSSecurityDescriptor`, whose access control entries are changed. The change is made in memory only; use `Set-NTFSSecurityDescriptor` to write it to the file system. + 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. + + FileSystemSecurity2[] + + FileSystemSecurity2[] + + + None + + + + + + 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 returned by `Get-NTFSSecurityDescriptor`. + + + + + Security2.IdentityReference2[] + + + The accounts whose entries are changed, bound from a property named `Account`, `IdentityReference`, or `ID`. The output of `Get-NTFSAccess` and `Get-NTFSOrphanedAccess` supplies `Account`. + + + + + Security2.FileSystemRights2 + + + The rights to remove, piped by the property `AccessRights` or `FileSystemRights`. + + + + + System.Security.AccessControl.AccessControlType + + + The type of the entry, piped by the property `AccessType` or `AccessControlType`. + + + + + System.Security.AccessControl.InheritanceFlags + + + The inheritance flags of the entry, piped by the property `InheritanceFlags` in the `Complex` parameter sets. + + + + + System.Security.AccessControl.PropagationFlags + + + The propagation flags of the entry, piped by the property `PropagationFlags` in the `Complex` parameter sets. + + + + + Security2.ApplyTo + + + The scope of the entry, piped by the property `AppliesTo` in the `Simple` parameter sets. + + + + + + + Security2.FileSystemAccessRule2 + + + With `-PassThru`, the cmdlet writes all access control entries of every processed item, explicit and inherited. Without `-PassThru` it writes nothing. + + + + + + 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. + If the ACL of an item cannot be written because access is denied, the cmdlet tries once more after making the current account the owner of the item, and restores the previous owner afterwards. Changing the owner of an item requires the Take Ownership and Restore privileges, so this fallback only succeeds in an elevated session of an account that holds them. + Removing rights from an entry that does not exist is not an error; the cmdlet leaves the ACL unchanged. + + + + + --------- Example 1: Remove a permission from a folder --------- + PS C:\> Remove-NTFSAccess -Path C:\Data -Account 'CONTOSO\JohnDoe' -AccessRights Modify + + This command removes the modify rights of an account from `C:\Data`. The entry is matched with the default values of the remaining parameters, which are the access type `Allow` and the inheritance flags `ContainerInherit, ObjectInherit` with no propagation flags. + + + + -- Example 2: Take a single right away from an existing entry -- + PS C:\> Remove-NTFSAccess -Path C:\Data -Account 'CONTOSO\Domain Users' -AccessRights DeleteSubdirectoriesAndFiles -AppliesTo ThisFolderSubfoldersAndFiles + + This command removes one right from the entry of a domain group and leaves the other rights of that entry untouched. + + + + --- Example 3: Remove all explicit permissions of an account --- + PS C:\> Get-NTFSAccess -Path C:\Data -Account 'CONTOSO\JohnDoe' -ExcludeInherited | Remove-NTFSAccess + + This command removes every access control entry that was defined for an account on `C:\Data`. The piped objects supply the path, the account, the rights, the access type, and the flags, so each entry is matched exactly as it exists. + + + + ---- Example 4: Clean up orphaned entries in a folder tree ---- + PS C:\> Get-ChildItem2 -Path C:\Data -Recurse | Get-NTFSOrphanedAccess -ExcludeInherited | Remove-NTFSAccess + + This command removes the access control entries of deleted accounts from all items below `C:\Data`. `-ExcludeInherited` makes sure that each entry is removed where it is defined instead of where it is inherited. + + + + + + Online Version: + https://github.com/raandree/NTFSSecurity/blob/master/Docs/Cmdlets/Remove-NTFSAccess.md + + + Get-NTFSAccess + + + + Add-NTFSAccess + + + + Clear-NTFSAccess + + + + Get-NTFSOrphanedAccess + + + + Disable-NTFSAccessInheritance + + + + Set-NTFSSecurityDescriptor + + + + + + + Remove-NTFSAudit + Remove + NTFSAudit + + Removes an audit entry from a file or folder. + + + + The `Remove-NTFSAudit` cmdlet removes an audit entry from the system access control list (SACL) of a file or folder. The cmdlet builds an audit entry from `-Account`, `-AccessRights`, `-AuditFlags`, and the inheritance and propagation flags, and removes that entry from the SACL. The audit entries of the account are matched by their inheritance and propagation flags, and the requested access rights and audit flags are then taken away from them: an entry that audits further rights keeps those rights and disappears only when nothing is left. To remove an entry completely, pass the same values that `Get-NTFSAudit` reports for it. + Because the inheritance and propagation flags take part in the match, they must describe the entry you want to remove. `-AppliesTo ThisFolderOnly` removes an entry that is not inherited by child items, which is also the shape of every audit entry on a file, while the default of the complex parameter sets removes an entry that applies to the folder, its subfolders, and its files. An entry that an item inherits from a parent folder is stored on that parent, so remove it there, or use `Clear-NTFSAudit` with `-DisableInheritance` to drop the inherited entries on the item. + In the `PathSimple` and `PathComplex` parameter sets the cmdlet reads the security descriptor of every item in `-Path` and writes it back right away. In the `SDSimple` and `SDComplex` parameter sets it changes an in-memory `Security2.FileSystemSecurity2` object that `Get-NTFSSecurityDescriptor` returned, and the change reaches the file system only when you pass the object to `Set-NTFSSecurityDescriptor`. `PathComplex` is the default parameter set; because it requires `-Path`, a command that uses `-SecurityDescriptor` must also specify `-AppliesTo`, `-InheritanceFlags`, or `-PropagationFlags` so that PowerShell can choose between `SDSimple` and `SDComplex`. + When you omit them, `-AuditFlags` is `Success, Failure`, `-InheritanceFlags` is `ContainerInherit, ObjectInherit`, `-PropagationFlags` is `None`, and `-AppliesTo` is `ThisFolderOnly`. All parameters bind by property name, and `-Path` also binds by value and through its `FullName` alias, so you can pipe the output of `Get-NTFSAudit`, `Get-ChildItem`, `Get-ChildItem2`, and `Get-Item2` into the cmdlet. The cmdlet writes no object unless you use `-PassThru`. + + + + Remove-NTFSAudit + + Path + + Specifies the files or folders the audit entry is removed from. Relative paths are resolved against the current location. The parameter accepts pipeline input by value and by property name through its `FullName` alias. + + String[] + + String[] + + + None + + + Account + + Specifies the accounts whose audit entries are removed. The value is an account name such as `CONTOSO\JohnDoe`, `CONTOSO\Domain Users`, `BUILTIN\Users`, or `Everyone`, or a SID string such as `S-1-5-32-545`. A SID is the only way to address an entry whose account no longer resolves to a name. When you pass several accounts, the cmdlet removes one entry per account. + + IdentityReference2[] + + IdentityReference2[] + + + None + + + AccessRights + + Specifies the audited access rights to remove. The value accepts the basic rights such as `Read`, `Write`, `Modify`, and `FullControl` as well as the individual rights such as `Delete` or `WriteAttributes`, and it accepts a comma-separated list that combines them. Rights that an existing entry audits beyond the ones you specify stay in place. For the meaning of each right, see Concepts (../Concepts.md). + + + None + ReadData + ListDirectory + WriteData + CreateFiles + AppendData + CreateDirectories + ReadExtendedAttributes + WriteExtendedAttributes + ExecuteFile + Traverse + DeleteSubdirectoriesAndFiles + ReadAttributes + WriteAttributes + Write + Delete + ReadPermissions + Read + ReadAndExecute + Modify + ChangePermissions + TakeOwnership + Synchronize + FullControl + GenericAll + GenericExecute + GenericWrite + GenericRead + + FileSystemRights2 + + FileSystemRights2 + + + None + + + AppliesTo + + Specifies the scope of the audit entry to remove with a single value instead of the `-InheritanceFlags` and `-PropagationFlags` pair, in the same wording the Advanced Security Settings dialog uses. The value must describe the entry as `Get-NTFSAudit` reports it, otherwise nothing is removed. The default is `ThisFolderOnly`. + + + ThisFolderOnly + ThisFolderSubfoldersAndFiles + ThisFolderAndSubfolders + ThisFolderAndFiles + SubfoldersAndFilesOnly + SubfoldersOnly + FilesOnly + ThisFolderSubfoldersAndFilesOneLevel + ThisFolderAndSubfoldersOneLevel + ThisFolderAndFilesOneLevel + SubfoldersAndFilesOnlyOneLevel + SubfoldersOnlyOneLevel + FilesOnlyOneLevel + + ApplyTo + + ApplyTo + + + ThisFolderOnly + + + AuditFlags + + Specifies which audited access attempts are removed from the entry. `Success` removes the auditing of successful attempts, `Failure` removes the auditing of denied attempts, and `Success, Failure` removes both. An entry that audits the flag you did not specify stays in place with that flag. The default is `Success, Failure`. + + + None + Success + Failure + + AuditFlags + + AuditFlags + + + Success, Failure + + + PassThru + + Indicates that the cmdlet writes the access control entries of the processed item or descriptor to the pipeline after the change. All entries are returned, explicit and inherited ones, not only the entry that was removed. Without this switch the cmdlet returns nothing when the operation succeeds. See the OUTPUTS section for which entries each parameter set returns. + + + SwitchParameter + + + False + + + + Remove-NTFSAudit + + SecurityDescriptor + + Specifies one or more security descriptors that `Get-NTFSSecurityDescriptor` returned. The cmdlet removes the audit entry from the system access control list (SACL) of the in-memory object; pass the object to `Set-NTFSSecurityDescriptor` to write the change to the file system. + + FileSystemSecurity2[] + + FileSystemSecurity2[] + + + None + + + Account + + Specifies the accounts whose audit entries are removed. The value is an account name such as `CONTOSO\JohnDoe`, `CONTOSO\Domain Users`, `BUILTIN\Users`, or `Everyone`, or a SID string such as `S-1-5-32-545`. A SID is the only way to address an entry whose account no longer resolves to a name. When you pass several accounts, the cmdlet removes one entry per account. + + IdentityReference2[] + + IdentityReference2[] + + + None + + + AccessRights + + Specifies the audited access rights to remove. The value accepts the basic rights such as `Read`, `Write`, `Modify`, and `FullControl` as well as the individual rights such as `Delete` or `WriteAttributes`, and it accepts a comma-separated list that combines them. Rights that an existing entry audits beyond the ones you specify stay in place. For the meaning of each right, see Concepts (../Concepts.md). + + + None + ReadData + ListDirectory + WriteData + CreateFiles + AppendData + CreateDirectories + ReadExtendedAttributes + WriteExtendedAttributes + ExecuteFile + Traverse + DeleteSubdirectoriesAndFiles + ReadAttributes + WriteAttributes + Write + Delete + ReadPermissions + Read + ReadAndExecute + Modify + ChangePermissions + TakeOwnership + Synchronize + FullControl + GenericAll + GenericExecute + GenericWrite + GenericRead + + FileSystemRights2 + + FileSystemRights2 + + + None + + + AppliesTo + + Specifies the scope of the audit entry to remove with a single value instead of the `-InheritanceFlags` and `-PropagationFlags` pair, in the same wording the Advanced Security Settings dialog uses. The value must describe the entry as `Get-NTFSAudit` reports it, otherwise nothing is removed. The default is `ThisFolderOnly`. + + + ThisFolderOnly + ThisFolderSubfoldersAndFiles + ThisFolderAndSubfolders + ThisFolderAndFiles + SubfoldersAndFilesOnly + SubfoldersOnly + FilesOnly + ThisFolderSubfoldersAndFilesOneLevel + ThisFolderAndSubfoldersOneLevel + ThisFolderAndFilesOneLevel + SubfoldersAndFilesOnlyOneLevel + SubfoldersOnlyOneLevel + FilesOnlyOneLevel + + ApplyTo + + ApplyTo + + + ThisFolderOnly + + + AuditFlags + + Specifies which audited access attempts are removed from the entry. `Success` removes the auditing of successful attempts, `Failure` removes the auditing of denied attempts, and `Success, Failure` removes both. An entry that audits the flag you did not specify stays in place with that flag. The default is `Success, Failure`. + + + None + Success + Failure + + AuditFlags + + AuditFlags + + + Success, Failure + + + PassThru + + Indicates that the cmdlet writes the access control entries of the processed item or descriptor to the pipeline after the change. All entries are returned, explicit and inherited ones, not only the entry that was removed. Without this switch the cmdlet returns nothing when the operation succeeds. See the OUTPUTS section for which entries each parameter set returns. + + + SwitchParameter + + + False + + + + Remove-NTFSAudit + + Path + + Specifies the files or folders the audit entry is removed from. Relative paths are resolved against the current location. The parameter accepts pipeline input by value and by property name through its `FullName` alias. + + String[] + + String[] + + + None + + + Account + + Specifies the accounts whose audit entries are removed. The value is an account name such as `CONTOSO\JohnDoe`, `CONTOSO\Domain Users`, `BUILTIN\Users`, or `Everyone`, or a SID string such as `S-1-5-32-545`. A SID is the only way to address an entry whose account no longer resolves to a name. When you pass several accounts, the cmdlet removes one entry per account. + + IdentityReference2[] + + IdentityReference2[] + + + None + + + AccessRights + + Specifies the audited access rights to remove. The value accepts the basic rights such as `Read`, `Write`, `Modify`, and `FullControl` as well as the individual rights such as `Delete` or `WriteAttributes`, and it accepts a comma-separated list that combines them. Rights that an existing entry audits beyond the ones you specify stay in place. For the meaning of each right, see Concepts (../Concepts.md). + + + None + ReadData + ListDirectory + WriteData + CreateFiles + AppendData + CreateDirectories + ReadExtendedAttributes + WriteExtendedAttributes + ExecuteFile + Traverse + DeleteSubdirectoriesAndFiles + ReadAttributes + WriteAttributes + Write + Delete + ReadPermissions + Read + ReadAndExecute + Modify + ChangePermissions + TakeOwnership + Synchronize + FullControl + GenericAll + GenericExecute + GenericWrite + GenericRead + + FileSystemRights2 + + FileSystemRights2 + + + None + + + AuditFlags + + Specifies which audited access attempts are removed from the entry. `Success` removes the auditing of successful attempts, `Failure` removes the auditing of denied attempts, and `Success, Failure` removes both. An entry that audits the flag you did not specify stays in place with that flag. The default is `Success, Failure`. + + + None + Success + Failure + + AuditFlags + + AuditFlags + + + Success, Failure + + + InheritanceFlags + + Specifies the inheritance flags of the audit entry to remove. `ContainerInherit` addresses an entry that child folders inherit, `ObjectInherit` an entry that child files inherit, and `None` an entry that stays on the item itself. The values can be combined, and the default is `ContainerInherit, ObjectInherit`. The flags must match the entry as `Get-NTFSAudit` reports it, otherwise nothing is removed. + + + None + ContainerInherit + ObjectInherit + + InheritanceFlags + + InheritanceFlags + + + ContainerInherit, ObjectInherit + + + PassThru + + Indicates that the cmdlet writes the access control entries of the processed item or descriptor to the pipeline after the change. All entries are returned, explicit and inherited ones, not only the entry that was removed. Without this switch the cmdlet returns nothing when the operation succeeds. See the OUTPUTS section for which entries each parameter set returns. + + + SwitchParameter + + + False + + + PropagationFlags + + Specifies the propagation flags of the audit entry to remove. `None` addresses an entry that applies to the item itself and to all inheriting child items, `InheritOnly` an entry that applies to the child items only, and `NoPropagateInherit` an entry whose inheritance stops at the direct children. The values `InheritOnly` and `NoPropagateInherit` can be combined, and the default is `None`. + + + None + NoPropagateInherit + InheritOnly + + PropagationFlags + + PropagationFlags + + + None + + + + Remove-NTFSAudit + + SecurityDescriptor + + Specifies one or more security descriptors that `Get-NTFSSecurityDescriptor` returned. The cmdlet removes the audit entry from the system access control list (SACL) of the in-memory object; pass the object to `Set-NTFSSecurityDescriptor` to write the change to the file system. + + FileSystemSecurity2[] + + FileSystemSecurity2[] + + + None + + + Account + + Specifies the accounts whose audit entries are removed. The value is an account name such as `CONTOSO\JohnDoe`, `CONTOSO\Domain Users`, `BUILTIN\Users`, or `Everyone`, or a SID string such as `S-1-5-32-545`. A SID is the only way to address an entry whose account no longer resolves to a name. When you pass several accounts, the cmdlet removes one entry per account. + + IdentityReference2[] + + IdentityReference2[] + + + None + + + AccessRights + + Specifies the audited access rights to remove. The value accepts the basic rights such as `Read`, `Write`, `Modify`, and `FullControl` as well as the individual rights such as `Delete` or `WriteAttributes`, and it accepts a comma-separated list that combines them. Rights that an existing entry audits beyond the ones you specify stay in place. For the meaning of each right, see Concepts (../Concepts.md). + + + None + ReadData + ListDirectory + WriteData + CreateFiles + AppendData + CreateDirectories + ReadExtendedAttributes + WriteExtendedAttributes + ExecuteFile + Traverse + DeleteSubdirectoriesAndFiles + ReadAttributes + WriteAttributes + Write + Delete + ReadPermissions + Read + ReadAndExecute + Modify + ChangePermissions + TakeOwnership + Synchronize + FullControl + GenericAll + GenericExecute + GenericWrite + GenericRead + + FileSystemRights2 + + FileSystemRights2 + + + None + + + AuditFlags + + Specifies which audited access attempts are removed from the entry. `Success` removes the auditing of successful attempts, `Failure` removes the auditing of denied attempts, and `Success, Failure` removes both. An entry that audits the flag you did not specify stays in place with that flag. The default is `Success, Failure`. + + + None + Success + Failure + + AuditFlags + + AuditFlags + + + Success, Failure + + + InheritanceFlags + + Specifies the inheritance flags of the audit entry to remove. `ContainerInherit` addresses an entry that child folders inherit, `ObjectInherit` an entry that child files inherit, and `None` an entry that stays on the item itself. The values can be combined, and the default is `ContainerInherit, ObjectInherit`. The flags must match the entry as `Get-NTFSAudit` reports it, otherwise nothing is removed. + + + None + ContainerInherit + ObjectInherit + + InheritanceFlags + + InheritanceFlags + + + ContainerInherit, ObjectInherit + + + PassThru + + Indicates that the cmdlet writes the access control entries of the processed item or descriptor to the pipeline after the change. All entries are returned, explicit and inherited ones, not only the entry that was removed. Without this switch the cmdlet returns nothing when the operation succeeds. See the OUTPUTS section for which entries each parameter set returns. + + + SwitchParameter + + + False + + + PropagationFlags + + Specifies the propagation flags of the audit entry to remove. `None` addresses an entry that applies to the item itself and to all inheriting child items, `InheritOnly` an entry that applies to the child items only, and `NoPropagateInherit` an entry whose inheritance stops at the direct children. The values `InheritOnly` and `NoPropagateInherit` can be combined, and the default is `None`. + + + None + NoPropagateInherit + InheritOnly + + PropagationFlags + + PropagationFlags + + + None + + + + + + AccessRights + + Specifies the audited access rights to remove. The value accepts the basic rights such as `Read`, `Write`, `Modify`, and `FullControl` as well as the individual rights such as `Delete` or `WriteAttributes`, and it accepts a comma-separated list that combines them. Rights that an existing entry audits beyond the ones you specify stay in place. For the meaning of each right, see Concepts (../Concepts.md). + + FileSystemRights2 + + FileSystemRights2 + + + None + + + Account + + Specifies the accounts whose audit entries are removed. The value is an account name such as `CONTOSO\JohnDoe`, `CONTOSO\Domain Users`, `BUILTIN\Users`, or `Everyone`, or a SID string such as `S-1-5-32-545`. A SID is the only way to address an entry whose account no longer resolves to a name. When you pass several accounts, the cmdlet removes one entry per account. + + IdentityReference2[] + + IdentityReference2[] + + + None + + + AppliesTo + + Specifies the scope of the audit entry to remove with a single value instead of the `-InheritanceFlags` and `-PropagationFlags` pair, in the same wording the Advanced Security Settings dialog uses. The value must describe the entry as `Get-NTFSAudit` reports it, otherwise nothing is removed. The default is `ThisFolderOnly`. + + ApplyTo + + ApplyTo + + + ThisFolderOnly + + + AuditFlags + + Specifies which audited access attempts are removed from the entry. `Success` removes the auditing of successful attempts, `Failure` removes the auditing of denied attempts, and `Success, Failure` removes both. An entry that audits the flag you did not specify stays in place with that flag. The default is `Success, Failure`. + + AuditFlags + + AuditFlags + + + Success, Failure + + + InheritanceFlags + + Specifies the inheritance flags of the audit entry to remove. `ContainerInherit` addresses an entry that child folders inherit, `ObjectInherit` an entry that child files inherit, and `None` an entry that stays on the item itself. The values can be combined, and the default is `ContainerInherit, ObjectInherit`. The flags must match the entry as `Get-NTFSAudit` reports it, otherwise nothing is removed. + + InheritanceFlags + + InheritanceFlags + + + ContainerInherit, ObjectInherit + + + PassThru + + Indicates that the cmdlet writes the access control entries of the processed item or descriptor to the pipeline after the change. All entries are returned, explicit and inherited ones, not only the entry that was removed. Without this switch the cmdlet returns nothing when the operation succeeds. See the OUTPUTS section for which entries each parameter set returns. + + SwitchParameter + + SwitchParameter + + + False + + + Path + + Specifies the files or folders the audit entry is removed from. Relative paths are resolved against the current location. The parameter accepts pipeline input by value and by property name through its `FullName` alias. + + String[] + + String[] + + + None + + + PropagationFlags + + Specifies the propagation flags of the audit entry to remove. `None` addresses an entry that applies to the item itself and to all inheriting child items, `InheritOnly` an entry that applies to the child items only, and `NoPropagateInherit` an entry whose inheritance stops at the direct children. The values `InheritOnly` and `NoPropagateInherit` can be combined, and the default is `None`. + + PropagationFlags + + PropagationFlags + + + None + + + SecurityDescriptor + + Specifies one or more security descriptors that `Get-NTFSSecurityDescriptor` returned. The cmdlet removes the audit entry from the system access control list (SACL) of the in-memory object; pass the object to `Set-NTFSSecurityDescriptor` to write the change to the file system. + + FileSystemSecurity2[] + + FileSystemSecurity2[] + + + None + + + + + + System.String[] + + + You can pipe paths to this cmdlet, or objects that have a `Path` or `FullName` property, such as the output of `Get-NTFSAudit`, `Get-ChildItem`, `Get-ChildItem2`, and `Get-Item2`. + + + + + Security2.FileSystemSecurity2[] + + + You can pipe the security descriptors that `Get-NTFSSecurityDescriptor` returns to this cmdlet. + + + + + Security2.IdentityReference2[] + + + The accounts passed to `-Account` are converted to this type from an account name or a SID string. The parameter binds by property name through its own name and its aliases `IdentityReference` and `ID`, so the `Account` property of the entries this module returns supplies the value. + + + + + Security2.FileSystemRights2 + + + The value passed to `-AccessRights` is converted to this type. The parameter binds by property name, so an object with an `AccessRights` or `FileSystemRights` property supplies the value. + + + + + System.Security.AccessControl.AuditFlags + + + The value passed to `-AuditFlags` is converted to this type and binds by property name. + + + + + System.Security.AccessControl.InheritanceFlags + + + The value passed to `-InheritanceFlags` is converted to this type and binds by property name in the `PathComplex` and `SDComplex` parameter sets. + + + + + System.Security.AccessControl.PropagationFlags + + + The value passed to `-PropagationFlags` is converted to this type and binds by property name in the `PathComplex` and `SDComplex` parameter sets. + + + + + Security2.ApplyTo + + + The value passed to `-AppliesTo` is converted to this type and binds by property name in the `PathSimple` and `SDSimple` parameter sets. + + + + + + + Security2.FileSystemAccessRule2 + + + Without `-PassThru` the cmdlet writes nothing. With `-PassThru` the type depends on the parameter set: in the `Path` sets the cmdlet writes all access entries of the item, explicit and inherited ones, as `Security2.FileSystemAccessRule2` objects, while in the `SecurityDescriptor` sets it writes all audit entries of the descriptor as `Security2.FileSystemAuditRule2` objects. Use `Get-NTFSAudit` to check the audit entries of an item after the removal. + + + + + + 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 and writing the SACL requires the Security privilege (`SeSecurityPrivilege`, "Manage auditing and security log"), so run this cmdlet in an elevated session of an account that holds that privilege. Without it, the cmdlet writes a non-terminating `RemoveAceError` whose message states that a required privilege is not held by the client, and the item is left unchanged. + If the security descriptor cannot be read or written because access is denied, the cmdlet takes ownership of the item, repeats the operation, and restores the previous owner. If the second attempt fails as well, the cmdlet writes an error, and the ownership change is not rolled back. + The cmdlet reports no error when no entry matches the supplied values. Compare the result with `Get-NTFSAudit` to confirm that the entry is gone. + + + + + -------- Example 1: Remove an audit entry from a folder -------- + PS C:\> Remove-NTFSAudit -Path C:\Data -Account 'CONTOSO\Domain Users' -AccessRights FullControl -AuditFlags Failure + + This command removes the entry that audits failed access of `CONTOSO\Domain Users` to `C:\Data`, its subfolders, and its files. + + + + - Example 2: Remove an audit entry that applies to one folder - + PS C:\> Remove-NTFSAudit -Path C:\Data -Account Everyone -AccessRights Delete, DeleteSubdirectoriesAndFiles -AuditFlags Success -AppliesTo ThisFolderOnly + + This command removes the entry that audits successful deletions in the folder `C:\Data` itself. Use the same `-AppliesTo` value to remove an audit entry from a file, because audit entries on files are never inherited by child items. + + + + ------ Example 3: Remove the audit entries of one account ------ + PS C:\> Get-NTFSAudit -Path C:\Data -Account 'CONTOSO\JohnDoe' -ExcludeInherited | Remove-NTFSAudit + + This command reads the explicit audit entries of `CONTOSO\JohnDoe` and pipes them back into `Remove-NTFSAudit`, which removes each of them from the item it came from. The path, account, access rights, audit flags, and inheritance flags all bind from the properties of the piped entries. + + + + - Example 4: Remove an audit entry from a security descriptor - + PS C:\> $sd = Get-NTFSSecurityDescriptor -Path C:\Data +PS C:\> Remove-NTFSAudit -SecurityDescriptor $sd -Account 'CONTOSO\JohnDoe' -AccessRights Modify -AuditFlags Success, Failure -AppliesTo SubfoldersAndFilesOnly +PS C:\> Set-NTFSSecurityDescriptor -SecurityDescriptor $sd + + This command removes the entry from the in-memory security descriptor of `C:\Data` and then writes the descriptor back to the file system. + + + + + + Online Version: + https://github.com/raandree/NTFSSecurity/blob/master/Docs/Cmdlets/Remove-NTFSAudit.md + + + Get-NTFSAudit + + + + Add-NTFSAudit + + + + Clear-NTFSAudit + + + + Get-NTFSOrphanedAudit + + + + Remove-NTFSAccess + + + + Set-NTFSSecurityDescriptor + + + + + + + Set-NTFSInheritance + Set + NTFSInheritance + + Sets the inheritance of the access rules and the audit rules of a file or folder. + + + + The `Set-NTFSInheritance` cmdlet turns the inheritance of access rules and audit rules on or off in a single call. It reads the current state of the item first and changes a section only when the requested value differs from the current one, which makes the cmdlet suitable for repeatedly applying a desired state to a folder tree. + The cmdlet performs the same operations as `Enable-NTFSAccessInheritance`, `Disable-NTFSAccessInheritance`, `Enable-NTFSAuditInheritance`, and `Disable-NTFSAuditInheritance`, but it does not expose their switches and it does not use their defaults. `-AccessInheritanceEnabled $false` discards the inherited access rules instead of copying them into the item's own DACL, `-AccessInheritanceEnabled $true` keeps the explicit access rules, `-AuditInheritanceEnabled $false` copies the inherited audit rules into the item's own SACL, and `-AuditInheritanceEnabled $true` removes the explicit audit rules. Use the individual Enable and Disable cmdlets when you need the opposite behavior. + Specify both `-AccessInheritanceEnabled` and `-AuditInheritanceEnabled`. The cmdlet compares the current state against the parameter value even when the parameter was not supplied, and when such a comparison reports a difference it fails with the non-terminating error "Nullable object must have a value". Omitting `-AccessInheritanceEnabled` always triggers that error, and omitting `-AuditInheritanceEnabled` triggers it in a session that can read the audit section. Changing the audit section requires the Security privilege and therefore an elevated session. + In the `Path` parameter set the cmdlet writes each changed section back to disk immediately. In the `SecurityDescriptor` parameter set it changes the `Security2.FileSystemSecurity2` object in memory only; nothing reaches the file system until you pass that object to `Set-NTFSSecurityDescriptor`. `-Path`, `-AccessInheritanceEnabled`, and `-AuditInheritanceEnabled` all accept pipeline input by property name, so a `Security2.FileSystemInheritanceInfo` object from `Get-NTFSInheritance` binds to all three at once. + + + + Set-NTFSInheritance + + Path + + Specifies the path of one or more files or folders whose inheritance is set. Relative paths are resolved against the current location. The parameter accepts pipeline input by value and by property name through its `FullName` alias, so the output of `Get-ChildItem`, `Get-ChildItem2`, `Get-Item2`, and `Get-NTFSInheritance` binds to it. The cmdlet does nothing when no path is supplied, either directly or from the pipeline. + + String[] + + String[] + + + None + + + AccessInheritanceEnabled + + Specifies whether the item inherits access rules from its parent folder. `$true` removes the protection from the DACL and keeps the access rules that are stored directly on the item; `$false` protects the DACL and discards the rules the item currently inherits, which leaves only its explicit rules. The section is left untouched when the requested value already matches the current state. Always supply this parameter, because the cmdlet fails with "Nullable object must have a value" when it has to compare against a value that was not provided. + + Boolean + + Boolean + + + None + + + AuditInheritanceEnabled + + Specifies whether the item inherits audit rules from its parent folder. `$true` removes the protection from the SACL and removes the audit rules that are stored directly on the item; `$false` protects the SACL and copies the inherited audit rules into it. The section is left untouched when the requested value already matches the current state. Reading and writing the audit section requires the Security privilege and therefore an elevated session. + + Boolean + + Boolean + + + None + + + PassThru + + Indicates that the cmdlet returns a `Security2.FileSystemInheritanceInfo` object for each processed item. By default, this cmdlet produces no output. The state is read after the changes were attempted, so an object is also written when a change failed. + + + SwitchParameter + + + False + + + + Set-NTFSInheritance + + SecurityDescriptor + + The SecurityDescriptor parameter allows passing an security descriptor or an array or security descriptors. + 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. + This cmdlet changes the descriptor in memory only. Pass the object to `Set-NTFSSecurityDescriptor` to write the change to the file system. + + FileSystemSecurity2[] + + FileSystemSecurity2[] + + + None + + + AccessInheritanceEnabled + + Specifies whether the item inherits access rules from its parent folder. `$true` removes the protection from the DACL and keeps the access rules that are stored directly on the item; `$false` protects the DACL and discards the rules the item currently inherits, which leaves only its explicit rules. The section is left untouched when the requested value already matches the current state. Always supply this parameter, because the cmdlet fails with "Nullable object must have a value" when it has to compare against a value that was not provided. + + Boolean + + Boolean + + + None + + + AuditInheritanceEnabled + + Specifies whether the item inherits audit rules from its parent folder. `$true` removes the protection from the SACL and removes the audit rules that are stored directly on the item; `$false` protects the SACL and copies the inherited audit rules into it. The section is left untouched when the requested value already matches the current state. Reading and writing the audit section requires the Security privilege and therefore an elevated session. + + Boolean + + Boolean + + + None + + + PassThru + + Indicates that the cmdlet returns a `Security2.FileSystemInheritanceInfo` object for each processed item. By default, this cmdlet produces no output. The state is read after the changes were attempted, so an object is also written when a change failed. + + + SwitchParameter + + + False + + + + + + AccessInheritanceEnabled + + Specifies whether the item inherits access rules from its parent folder. `$true` removes the protection from the DACL and keeps the access rules that are stored directly on the item; `$false` protects the DACL and discards the rules the item currently inherits, which leaves only its explicit rules. The section is left untouched when the requested value already matches the current state. Always supply this parameter, because the cmdlet fails with "Nullable object must have a value" when it has to compare against a value that was not provided. + + Boolean + + Boolean + + + None + + + AuditInheritanceEnabled + + Specifies whether the item inherits audit rules from its parent folder. `$true` removes the protection from the SACL and removes the audit rules that are stored directly on the item; `$false` protects the SACL and copies the inherited audit rules into it. The section is left untouched when the requested value already matches the current state. Reading and writing the audit section requires the Security privilege and therefore an elevated session. + + Boolean + + Boolean + + + None + + + PassThru + + Indicates that the cmdlet returns a `Security2.FileSystemInheritanceInfo` object for each processed item. By default, this cmdlet produces no output. The state is read after the changes were attempted, so an object is also written when a change failed. + + SwitchParameter + + SwitchParameter + + + False + + + Path + + Specifies the path of one or more files or folders whose inheritance is set. Relative paths are resolved against the current location. The parameter accepts pipeline input by value and by property name through its `FullName` alias, so the output of `Get-ChildItem`, `Get-ChildItem2`, `Get-Item2`, and `Get-NTFSInheritance` binds to it. The cmdlet does nothing when no path is supplied, either directly or from the pipeline. + + String[] + + String[] + + + None + + + SecurityDescriptor + + The SecurityDescriptor parameter allows passing an security descriptor or an array or security descriptors. + 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. + This cmdlet changes the descriptor in memory only. Pass the object to `Set-NTFSSecurityDescriptor` to write the change to the file system. + + FileSystemSecurity2[] + + FileSystemSecurity2[] + + + None + + + + + + System.String[] + + + You can pipe one or more path strings, or objects that have a `FullName` property such as the output of `Get-ChildItem2`, `Get-Item2`, and `Get-ChildItem`, to this cmdlet. + + + + + Security2.FileSystemSecurity2[] + + + You can pipe the security descriptors that `Get-NTFSSecurityDescriptor` returns to this cmdlet. + + + + + System.Nullable`1[[System.Boolean, mscorlib, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089]] + + + You can supply `-AccessInheritanceEnabled` and `-AuditInheritanceEnabled` through a pipeline object that has properties of those names, such as the `Security2.FileSystemInheritanceInfo` objects that `Get-NTFSInheritance` returns. + + + + + + + System.Object + + + By default this cmdlet returns no output. With `-PassThru` it writes one `Security2.FileSystemInheritanceInfo` object per item, which reports the `AccessInheritanceEnabled` and `AuditInheritanceEnabled` state after the change. + + + + + + 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. + The audit section of a security descriptor can only be read and written with the Security privilege (`SeSecurityPrivilege`), which an account can only use in an elevated session. Without it, a requested change of `-AuditInheritanceEnabled` produces a non-terminating error that reports Windows error 1314, "A required privilege is not held by the client". The access section is processed first, so a change of `-AccessInheritanceEnabled` in the same command is applied even when the audit change fails. + If the descriptor cannot be opened because the account has no permission to the item, the cmdlet takes ownership of the item, applies the changes, and sets the previous owner back. That fallback only succeeds when the account can take ownership of the item and restore the original owner; otherwise the cmdlet writes an error and continues with the next item. + A path that does not exist produces a non-terminating error and the cmdlet continues with the remaining paths. + + + + + -------- Example 1: Block inheritance of both sections -------- + PS C:\> Set-NTFSInheritance -Path C:\Data\Projects -AccessInheritanceEnabled $false -AuditInheritanceEnabled $false + + This command protects the DACL and the SACL of `C:\Data\Projects`. The inherited access rules are discarded, so make sure the folder has explicit access rules of its own; the inherited audit rules are copied into the folder's SACL. Changing the audit section requires an elevated session. + + + + ------- Example 2: Restore inheritance of both sections ------- + PS C:\> Set-NTFSInheritance -Path C:\Data\Projects -AccessInheritanceEnabled $true -AuditInheritanceEnabled $true -PassThru + + This command lets the folder inherit from `C:\Data` again. The explicit access rules are kept, the explicit audit rules are removed, and `-PassThru` returns the resulting state. + + + + ---------- Example 3: Save a state and apply it again ---------- + PS C:\> $state = Get-NTFSInheritance -Path C:\Data\Projects +PS C:\> Disable-NTFSAccessInheritance -Path C:\Data\Projects +PS C:\> $state | Set-NTFSInheritance + + The first command records the inheritance state of the folder. After the second command changed it, the third command pipes the recorded object back and restores both values, because `FullName`, `AccessInheritanceEnabled`, and `AuditInheritanceEnabled` bind by property name. + + + + ------ Example 4: Change a security descriptor in memory ------ + PS C:\> $sd = Get-NTFSSecurityDescriptor -Path C:\Data\Projects +PS C:\> Set-NTFSInheritance -SecurityDescriptor $sd -AccessInheritanceEnabled $false -AuditInheritanceEnabled $false +PS C:\> Set-NTFSSecurityDescriptor -SecurityDescriptor $sd + + The first two commands read the security descriptor and change its inheritance in memory, which does not change anything on disk. The third command writes the descriptor back and applies the change. + + + + + + Online Version: + https://github.com/raandree/NTFSSecurity/blob/master/Docs/Cmdlets/Set-NTFSInheritance.md + + + Get-NTFSInheritance + + + + Enable-NTFSAccessInheritance + + + + Disable-NTFSAccessInheritance + + + + Enable-NTFSAuditInheritance + + + + Disable-NTFSAuditInheritance + + + + Set-NTFSSecurityDescriptor + + + + + + + Set-NTFSOwner + Set + NTFSOwner + + Sets the owner of a file or folder. + + + + The `Set-NTFSOwner` cmdlet writes the account given in `-Account` into the owner field of the security descriptor of a file or folder. + The two parameter sets differ in where the change lands. With `-Path`, the cmdlet reads the owner section of the item, replaces the owner, and writes the change to the file system immediately. With `-SecurityDescriptor`, it changes only the descriptor in memory; the new owner reaches the file system when you pass the descriptor to `Set-NTFSSecurityDescriptor`. + The cmdlet returns nothing unless you use `-PassThru`, which returns the owner of each processed item as a `Security2.FileSystemOwner` object. `-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 omitting `-Path` leaves the cmdlet without work to do. + Every item is processed on its own. When a path does not exist or the owner cannot be written, the cmdlet writes a non-terminating error and continues with the next item. Windows itself decides whether the change is allowed: taking ownership requires the Take Ownership right on the item or the Take Ownership privilege (`SeTakeOwnershipPrivilege`), and assigning ownership to an account other than your own requires the Restore privilege (`SeRestorePrivilege`). The module tries to enable both privileges while the cmdlet runs, as described in the Notes section. + + + + Set-NTFSOwner + + Path + + Specifies the path of one or more files or folders whose owner you want to change. The change is written to the file system immediately. Relative paths are resolved against the current location. When you omit this parameter, the cmdlet does nothing. + + String[] + + String[] + + + None + + + Account + + Specifies the account that becomes the new owner. The value is a `Security2.IdentityReference2` object, which the module creates from an account name such as `CONTOSO\JohnDoe` or `BUILTIN\Administrators`, or from a security identifier such as `S-1-5-32-544`. An account name that cannot be resolved fails during parameter binding. + + IdentityReference2 + + IdentityReference2 + + + None + + + PassThru + + Indicates that the cmdlet returns the owner of each processed item as a `Security2.FileSystemOwner` object. Without this parameter, the cmdlet produces no output. + + + SwitchParameter + + + False + + + + Set-NTFSOwner + + SecurityDescriptor + + Specifies one or more security descriptors that `Get-NTFSSecurityDescriptor` returned. The cmdlet changes the owner only in memory; pass the descriptor to `Set-NTFSSecurityDescriptor` to write the change to the file system. + + FileSystemSecurity2[] + + FileSystemSecurity2[] + + + None + + + Account + + Specifies the account that becomes the new owner. The value is a `Security2.IdentityReference2` object, which the module creates from an account name such as `CONTOSO\JohnDoe` or `BUILTIN\Administrators`, or from a security identifier such as `S-1-5-32-544`. An account name that cannot be resolved fails during parameter binding. + + IdentityReference2 + + IdentityReference2 + + + None + + + PassThru + + Indicates that the cmdlet returns the owner of each processed item as a `Security2.FileSystemOwner` object. Without this parameter, the cmdlet produces no output. + + + SwitchParameter + + + False + + + + + + Account + + Specifies the account that becomes the new owner. The value is a `Security2.IdentityReference2` object, which the module creates from an account name such as `CONTOSO\JohnDoe` or `BUILTIN\Administrators`, or from a security identifier such as `S-1-5-32-544`. An account name that cannot be resolved fails during parameter binding. + + IdentityReference2 + + IdentityReference2 + + + None + + + PassThru + + Indicates that the cmdlet returns the owner of each processed item as a `Security2.FileSystemOwner` object. Without this parameter, the cmdlet produces no output. + + SwitchParameter + + SwitchParameter + + + False + + + Path + + Specifies the path of one or more files or folders whose owner you want to change. The change is written to the file system immediately. Relative paths are resolved against the current location. When you omit this parameter, the cmdlet does nothing. + + String[] + + String[] + + + None + + + SecurityDescriptor + + Specifies one or more security descriptors that `Get-NTFSSecurityDescriptor` returned. The cmdlet changes the owner only in memory; pass the descriptor to `Set-NTFSSecurityDescriptor` to write the change to the file system. + + FileSystemSecurity2[] + + FileSystemSecurity2[] + + + None + + + + + + 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. + + + + + Security2.FileSystemSecurity2[] + + + You can pipe security descriptors that `Get-NTFSSecurityDescriptor` returned to this cmdlet. + + + + + Security2.IdentityReference2 + + + An account binds to `-Account` by property name, so an object that exposes an `Account` property supplies the new owner. + + + + + + + Security2.FileSystemOwner + + + The cmdlet returns one object per processed item only when you use `-PassThru`. It contains the item in `Item`, its path in `FullName`, and the new owner in `Owner` and `Account`. + + + + + + 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. + Without those privileges, Windows allows the change only when your account already holds the Take Ownership right on the item, and it refuses to assign ownership to another account. In a session that is not elevated, setting an owner other than your own account therefore fails with a non-terminating error. + + + + + ------------- Example 1: Set the owner of a folder ------------- + PS C:\> Set-NTFSOwner -Path C:\Data -Account 'CONTOSO\JohnDoe' + + This command makes `CONTOSO\JohnDoe` the owner of the `C:\Data` folder and writes the change immediately. + + + + Example 2: Set the owner of a folder tree and show the result + PS C:\> Get-ChildItem2 -Path C:\Data -Recurse | Set-NTFSOwner -Account 'BUILTIN\Administrators' -PassThru + + This command makes the local Administrators group the owner of every file and folder below `C:\Data`. The `-PassThru` parameter returns the new owner of each item. + + + + Example 3: Change the owner in a security descriptor and write it back + PS C:\> $sd = Get-NTFSSecurityDescriptor -Path C:\Data +PS C:\> Set-NTFSOwner -SecurityDescriptor $sd -Account 'BUILTIN\Administrators' +PS C:\> Set-NTFSSecurityDescriptor -SecurityDescriptor $sd + + The first two commands read the security descriptor of `C:\Data` and change its owner in memory. The third command writes the descriptor, which applies the new owner together with every other change made to `$sd`. + + + + ------- Example 4: Set the owner by security identifier ------- + PS C:\> Set-NTFSOwner -Path C:\Data\Report.docx -Account 'S-1-5-32-544' + + This command makes the account with the security identifier `S-1-5-32-544`, which is the local Administrators group, the owner of the file. Use a SID when an account name cannot be resolved on the current computer. + + + + + + Online Version: + https://github.com/raandree/NTFSSecurity/blob/master/Docs/Cmdlets/Set-NTFSOwner.md + + + Get-NTFSOwner + + + + Get-NTFSSecurityDescriptor + + + + Set-NTFSSecurityDescriptor + + + + Enable-Privileges + + + + + + + Set-NTFSSecurityDescriptor + Set + NTFSSecurityDescriptor + + Writes a security descriptor to the file or folder it was read from. + + + + The `Set-NTFSSecurityDescriptor` cmdlet writes a `Security2.FileSystemSecurity2` object to the file system. It is the final step of the security descriptor workflow: `Get-NTFSSecurityDescriptor` reads a descriptor into memory, cmdlets such as `Add-NTFSAccess`, `Remove-NTFSAccess`, `Set-NTFSOwner`, and `Disable-NTFSAccessInheritance` change that copy through their `-SecurityDescriptor` parameter, and this cmdlet applies all of those changes in a single write. + Each descriptor remembers the item it was read from, and the cmdlet writes it back to exactly that item. There is no parameter that redirects the write to a different path, and writing a descriptor that you did not change simply re-applies its current content. + The cmdlet produces no output unless you use `-PassThru`, which reads the item again after the write and returns a new `FileSystemSecurity2` object that reflects what is now stored on disk. Descriptors can be passed as an array or through the pipeline, and each one is processed on its own. + When the write fails because access is denied, the cmdlet takes ownership of the item with the account of the current session, writes the descriptor, and restores the previous owner. If that fails as well, it writes a non-terminating error and continues with the next descriptor. Windows checks each section separately: changing the access control list requires the Change Permissions right on the item, changing the owner requires the Take Ownership right or the Take Ownership privilege, assigning ownership to another account requires the Restore privilege, and writing audit entries requires the Security privilege. + + + + Set-NTFSSecurityDescriptor + + SecurityDescriptor + + Specifies one or more security descriptors that `Get-NTFSSecurityDescriptor` returned. Each descriptor is written to the file or folder it was read from, including every change that was made to it in memory. + + FileSystemSecurity2[] + + FileSystemSecurity2[] + + + None + + + PassThru + + Indicates that the cmdlet reads each item again after the write and returns its current security descriptor. Without this parameter, the cmdlet produces no output. + + + SwitchParameter + + + False + + + + + + PassThru + + Indicates that the cmdlet reads each item again after the write and returns its current security descriptor. Without this parameter, the cmdlet produces no output. + + SwitchParameter + + SwitchParameter + + + False + + + SecurityDescriptor + + Specifies one or more security descriptors that `Get-NTFSSecurityDescriptor` returned. Each descriptor is written to the file or folder it was read from, including every change that was made to it in memory. + + FileSystemSecurity2[] + + FileSystemSecurity2[] + + + None + + + + + + Security2.FileSystemSecurity2[] + + + You can pipe one or more security descriptors that `Get-NTFSSecurityDescriptor` returned to this cmdlet. + + + + + + + Security2.FileSystemSecurity2 + + + The cmdlet returns a descriptor per written item only when you use `-PassThru`. That descriptor is read from the item after the write, so it is a new object and not the one you passed in. + + + + + + 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. + The cmdlet always writes to the item that is stored in the descriptor, so it cannot apply the descriptor of one item to another file or folder. To copy permissions, read the descriptor of the target item, add the entries you need with `Add-NTFSAccess`, and write the target descriptor. + `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. + + + + + -------- Example 1: Write a changed security descriptor -------- + PS C:\> $sd = Get-NTFSSecurityDescriptor -Path C:\Data +PS C:\> Add-NTFSAccess -SecurityDescriptor $sd -Account 'CONTOSO\JohnDoe' -AccessRights Modify -AppliesTo ThisFolderSubfoldersAndFiles +PS C:\> Set-NTFSSecurityDescriptor -SecurityDescriptor $sd + + The first two commands add an access control entry to the descriptor in memory, which leaves `C:\Data` untouched. The third command writes the descriptor and applies the new entry to the folder. + + + + ----- Example 2: Write several descriptors in one pipeline ----- + PS C:\> $descriptors = Get-ChildItem2 -Path C:\Data | Get-NTFSSecurityDescriptor +PS C:\> $descriptors | ForEach-Object { Add-NTFSAccess -SecurityDescriptor $_ -Account 'CONTOSO\JohnDoe' -AccessRights Modify -AppliesTo ThisFolderSubfoldersAndFiles } +PS C:\> $descriptors | Set-NTFSSecurityDescriptor + + The descriptors of all items in `C:\Data` are read, changed in memory, and then written back. Each descriptor goes to the item it came from. + + + + ----------------- Example 3: Write a new owner ----------------- + PS C:\> $sd = Get-NTFSSecurityDescriptor -Path C:\Data\Report.docx +PS C:\> Set-NTFSOwner -SecurityDescriptor $sd -Account 'BUILTIN\Administrators' +PS C:\> Set-NTFSSecurityDescriptor -SecurityDescriptor $sd + + This sequence changes the owner inside the descriptor and then writes the owner section to the file. + + + + ---------- Example 4: Verify the result after writing ---------- + PS C:\> Set-NTFSSecurityDescriptor -SecurityDescriptor $sd -PassThru | Get-NTFSAccess + + This command writes the descriptor, reads the item again, and lists the access control entries that are now stored on it. + + + + + + Online Version: + https://github.com/raandree/NTFSSecurity/blob/master/Docs/Cmdlets/Set-NTFSSecurityDescriptor.md + + + Get-NTFSSecurityDescriptor + + + + Add-NTFSAccess + + + + Remove-NTFSAccess + + + + Set-NTFSOwner + + + + Disable-NTFSAccessInheritance + + + + + + + Test-Path2 + Test + Path2 + + Determines whether a file or folder exists at the specified path. + + + + The `Test-Path2` cmdlet returns `$true` when an item exists at the specified path and `$false` when it does not. It resolves paths with the AlphaFS library instead of the Windows PowerShell file system provider, so it also reports items whose full path exceeds the 260-character `MAX_PATH` limit, where the built-in `Test-Path` cmdlet returns `$false`. + The `-PathType` parameter narrows the test. `Any`, the default, returns `$true` for a file and for a folder, `Container` returns `$true` only for a folder, and `Leaf` returns `$true` only for a file. A path that does not exist returns `$false` for every `-PathType` value. + `-Path` accepts an array of paths and writes one Boolean value for each of them, in the order in which they are passed. The parameter takes 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. + + + + Test-Path2 + + Path + + Specifies one or more paths to test. Relative paths are resolved against the current location. The parameter accepts pipeline input by value and by property name through its `FullName` alias. + + String[] + + String[] + + + None + + + PathType + + Specifies the kind of item that the path must point to. `Any`, the default, matches a file and a folder, `Container` matches only a folder, and `Leaf` matches only a file. + + + Any + Container + Leaf + + TestPathType + + TestPathType + + + Any + + + + + + Path + + Specifies one or more paths to test. Relative paths are resolved against the current location. The parameter accepts pipeline input by value and by property name through its `FullName` alias. + + String[] + + String[] + + + None + + + PathType + + Specifies the kind of item that the path must point to. `Any`, the default, matches a file and a folder, `Container` matches only a folder, and `Leaf` matches only a file. + + TestPathType + + TestPathType + + + Any + + + + + + System.String[] + + + You can pipe one or more path strings, or objects that have a `FullName` property such as the output of `Get-ChildItem2` and `Get-Item2`, to this cmdlet. + + + + + NTFSSecurity.TestPathType + + + You can supply the `-PathType` value through a pipeline object that has a `PathType` property. + + + + + + + Alphaleonis.Win32.Filesystem.FileInfo + + + `Test-Path2` does not write file objects. For each path it writes a single `System.Boolean` value that is `$true` when the item exists and matches `-PathType`, and `$false` otherwise. + + + + + Alphaleonis.Win32.Filesystem.DirectoryInfo + + + `Test-Path2` does not write folder objects either. A folder is reported through the same `System.Boolean` result as a file. + + + + + + The cmdlet resolves paths through the AlphaFS library, which is not bound by the 260-character `MAX_PATH` limit of the Windows PowerShell file system provider. Use `Test-Path2` instead of `Test-Path` when a path can be longer than that limit. + A path that does not exist is not an error condition. The cmdlet writes `$false` and continues with the next path. + + + + + ------------ Example 1: Test whether a file exists ------------ + PS C:\> Test-Path2 -Path C:\Data\Report.txt + + This command returns `$true` when `Report.txt` exists in the `C:\Data` folder, regardless of whether it is a file or a folder. + + + + ---------- Example 2: Test whether a path is a folder ---------- + PS C:\> Test-Path2 -Path C:\Data -PathType Container + + This command returns `$true` only when `C:\Data` exists and is a folder. If `C:\Data` is a file, the command returns `$false`. + + + + ------------ Example 3: Test several paths at once ------------ + PS C:\> Test-Path2 -Path C:\Data\Report.txt, C:\Data\Archive\Report.txt -PathType Leaf + + This command tests both paths and writes one Boolean value for each of them, in the order in which they are given. + + + + ------ Example 4: Test paths that come from the pipeline ------ + PS C:\> Get-ChildItem2 -Path C:\Data -Recurse | Test-Path2 -PathType Leaf + + This command pipes every item below `C:\Data` to `Test-Path2`, which binds the `FullName` property of each item to `-Path` and reports `$true` for the files and `$false` for the folders. + + + + + + Online Version: + https://github.com/raandree/NTFSSecurity/blob/master/Docs/Cmdlets/Test-Path2.md + + + Get-Item2 + + + + Get-ChildItem2 + + + + Get-FileHash2 + + + + Remove-Item2 + + + + + \ No newline at end of file diff --git a/Tests/Help.Tests.ps1 b/Tests/Help.Tests.ps1 new file mode 100644 index 0000000..34fec87 --- /dev/null +++ b/Tests/Help.Tests.ps1 @@ -0,0 +1,115 @@ +<# + Tests that Get-Help shows the help that is generated from Docs/Cmdlets for + every cmdlet of the module built in NTFSSecurity\bin\Release. +#> +[Diagnostics.CodeAnalysis.SuppressMessageAttribute( + 'PSUseDeclaredVarsMoreThanAssignments', '', Justification = 'Pester shares variables between blocks.' +)] +param () + +BeforeDiscovery { + $pagePath = Join-Path -Path $PSScriptRoot -ChildPath '..\Docs\Cmdlets' + $sectionPattern = '(?ms)^## (?[A-Z ]+?)\s*$(?.*?)(?=^## |\z)' + + $helpPages = foreach ($page in Get-ChildItem -Path $pagePath -Filter '*.md') { + $content = Get-Content -LiteralPath $page.FullName -Raw + $sections = @{} + foreach ($match in [regex]::Matches($content, $sectionPattern)) { + $sections[$match.Groups['Heading'].Value] = $match.Groups['Text'].Value + } + + $parameterNames = [regex]::Matches("$($sections['PARAMETERS'])", '(?m)^### -(?\w+)') | + ForEach-Object -Process { $_.Groups['Name'].Value } + + @{ + CommandName = $page.BaseName + Synopsis = "$($sections['SYNOPSIS'])".Trim() + ExampleCount = [regex]::Matches("$($sections['EXAMPLES'])", '(?m)^### ').Count + ParameterNames = @($parameterNames) + OnlineUri = [regex]::Match($content, '(?m)^online version: (?\S+)').Groups['Uri'].Value + } + } +} + +Describe 'Help of the NTFSSecurity cmdlets' { + BeforeAll { + $modulePath = Join-Path -Path $PSScriptRoot -ChildPath '..\NTFSSecurity\bin\Release\NTFSSecurity.psd1' + $module = Import-Module -Name $modulePath -Force -PassThru -ErrorAction Stop + $pagePath = Join-Path -Path $PSScriptRoot -ChildPath '..\Docs\Cmdlets' + + <# + With this test hook, Get-Help -Online returns the URI instead of opening a browser. In PowerShell 7, + the hook also makes Get-Help ignore the help file, so this test runs only in Windows PowerShell. + #> + $testHooks = [psobject].Assembly.GetType('System.Management.Automation.Internal.InternalTestHooks') + $bypassOnlineHelp = if ($testHooks -and $PSVersionTable.PSEdition -ne 'Core') { + $testHooks.GetField('BypassOnlineHelpRetrieval', [Reflection.BindingFlags] 'NonPublic, Static') + } + } + + AfterAll { + Remove-Module -Name NTFSSecurity -Force -ErrorAction SilentlyContinue + } + + It 'Should ship the help file in the en-US folder' { + Join-Path -Path $module.ModuleBase -ChildPath 'en-US\NTFSSecurity.dll-Help.xml' | Should -Exist + } + + It 'Should have a page in Docs/Cmdlets for every exported cmdlet' { + $pageNames = (Get-ChildItem -Path $pagePath -Filter '*.md').BaseName | Sort-Object + $cmdletNames = (Get-Command -Module NTFSSecurity -CommandType Cmdlet).Name | Sort-Object + + $cmdletNames -join ', ' | Should -BeExactly ($pageNames -join ', ') + } + + Context '' -ForEach $helpPages { + BeforeAll { + $help = Get-Help -Name $CommandName -Full + } + + It 'Should show the synopsis from Docs/Cmdlets' { + "$($help.Synopsis)".Trim() | Should -BeExactly $Synopsis + } + + It 'Should describe the parameters from Docs/Cmdlets' { + $describedParameterNames = foreach ($parameter in $help.parameters.parameter) { + if (($parameter.description.Text -join '').Trim()) { + $parameter.name + } + } + + ($describedParameterNames | Sort-Object) -join ', ' | + Should -BeExactly (($ParameterNames | Sort-Object) -join ', ') + } + + It 'Should show the examples from Docs/Cmdlets' { + @($help.examples.example | Where-Object -FilterScript { $_ }) | Should -HaveCount $ExampleCount + } + + It 'Should link to the online version from Docs/Cmdlets' { + @($help.relatedLinks.navigationLink)[0].uri | Should -BeExactly $OnlineUri + } + + It 'Should keep the space after each link in the help text' { + # platyPS writes an inline link as "text (url)" and drops the space that follows it. + $help | Out-String -Width 4096 | Should -Not -Match '\((?:\.\./|https?://)[^)\s]+\)\w' + } + + It 'Should open the online version with Get-Help -Online' { + if (-not $bypassOnlineHelp) { + $reason = 'the test hook for Get-Help -Online reads the help file only in Windows PowerShell' + Set-ItResult -Skipped -Because $reason + return + } + + $bypassOnlineHelp.SetValue($null, $true) + try { + $onlineHelp = Get-Help -Name $CommandName -Online + } finally { + $bypassOnlineHelp.SetValue($null, $false) + } + + "$onlineHelp" | Should -Match ('{0}$' -f [regex]::Escape($OnlineUri)) + } + } +} diff --git a/appveyor.yml b/appveyor.yml index effe479..9354623 100644 --- a/appveyor.yml +++ b/appveyor.yml @@ -1,5 +1,6 @@ -# Builds the NTFSSecurity module from source and checks that the cmdlet -# documentation in Docs/Cmdlets matches the cmdlets of that build. +# Builds the NTFSSecurity module from source, checks that the cmdlet +# documentation in Docs/Cmdlets and the help file generated from it match the +# cmdlets of that build, and runs the Pester tests against the build. image: Visual Studio 2022 init: @@ -11,6 +12,8 @@ install: Install-PackageProvider -Name NuGet -MinimumVersion 2.8.5.201 -Force | Out-Null Install-Module -Name platyPS -RequiredVersion 0.14.2 -Force Install-Module -Name MarkdownLinkCheck -RequiredVersion 0.2.0 -Force + # The image includes Pester 3.4.0, which is signed by a different publisher. + Install-Module -Name Pester -RequiredVersion 5.7.1 -Force -SkipPublisherCheck before_build: - nuget restore NTFSSecurity\packages.config -PackagesDirectory packages -NonInteractive @@ -46,3 +49,38 @@ test_script: if ($brokenLinks) { throw "Found broken hyperlinks $brokenLinks" } + + # 03. Test that the help file of the module matches the documentation + New-ExternalHelp -Path ./Docs/Cmdlets -OutputPath ./NTFSSecurity/en-US -Force | Out-Null + $helpChanges = git status --porcelain -- NTFSSecurity/en-US + if ($helpChanges) { + throw "The help file is not up-to-date, run New-ExternalHelp -Path .\Docs\Cmdlets -OutputPath .\NTFSSecurity\en-US -Force: $helpChanges" + } + + # 04. Run the Pester tests against the module build + Import-Module -Name Pester -RequiredVersion 5.7.1 + $configuration = New-PesterConfiguration + $configuration.Run.Path = '.\Tests' + $configuration.Run.PassThru = $true + $configuration.Output.Verbosity = 'Detailed' + $result = Invoke-Pester -Configuration $configuration + + # Report every test once on the Tests tab. An uploaded NUnit file lists a + # Pester 5 test once for each block that contains it. + if ($env:APPVEYOR_API_URL -and $result.Tests) { + $tests = @(foreach ($test in $result.Tests) { + @{ + testName = $test.ExpandedPath + testFramework = 'Pester' + fileName = Split-Path -Path $test.ScriptBlock.File -Leaf + outcome = if ($test.Result -eq 'NotRun') { 'NotRunnable' } else { "$($test.Result)" } + durationMilliseconds = [long] $test.Duration.TotalMilliseconds + ErrorMessage = @($test.ErrorRecord | ForEach-Object -Process { "$_" }) -join [Environment]::NewLine + } + }) + $body = [Text.Encoding]::UTF8.GetBytes((ConvertTo-Json -InputObject $tests -Compress)) + Invoke-RestMethod -Method Post -Uri ($env:APPVEYOR_API_URL.TrimEnd('/') + '/api/tests/batch') -Body $body -ContentType 'application/json; charset=utf-8' | Out-Null + } + if ($result.FailedCount -gt 0) { + throw "$($result.FailedCount) Pester tests failed." + }