From 93ed2c7da4fa70bd37bf77bb5a5fb2cbbc695064 Mon Sep 17 00:00:00 2001 From: Raimund Andree Date: Sun, 11 Oct 2026 11:02:53 +0000 Subject: [PATCH] fix(access,audit): bind the AppliesTo property of a piped object for paths Add-NTFSAccess, Remove-NTFSAccess, Add-NTFSAudit, and Remove-NTFSAudit declared PathComplex as the default parameter set. An object that had Path, Account, and AccessRights satisfied the mandatory parameters of the default set, so PowerShell never tried PathSimple and the cmdlet dropped the AppliesTo property of the object. Since 4b1abc9 made -AppliesTo mandatory in the Simple sets, the default set is redundant for every call that names its parameters, and it masked PathSimple for the pipeline. Without a default set, an object that has AppliesTo binds PathSimple, one that has InheritanceFlags or PropagationFlags binds PathComplex, and one that has neither binds PathComplex with the default scope. An object that has AppliesTo and InheritanceFlags now fails with AmbiguousParameterSet, like the same two named parameters. Named calls, -SecurityDescriptor calls without AppliesTo, and the round trip Get-NTFSAccess | Add-NTFSAccess keep their behavior. The tests pipe objects of each shape and fail without the change. The cmdlet pages and the help file follow the build. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Co-authored-by: AI Assistant --- CHANGELOG.md | 6 ++ Docs/Cmdlets/Add-NTFSAccess.md | 14 ++-- Docs/Cmdlets/Add-NTFSAudit.md | 14 ++-- Docs/Cmdlets/Remove-NTFSAccess.md | 14 ++-- Docs/Cmdlets/Remove-NTFSAudit.md | 14 ++-- NTFSSecurity/AccessCmdlets/AddAccess.cs | 2 +- NTFSSecurity/AccessCmdlets/RemoveAccess.cs | 2 +- NTFSSecurity/AuditCmdlets/AddAudit.cs | 2 +- NTFSSecurity/AuditCmdlets/RemoveAudit.cs | 2 +- NTFSSecurity/en-US/NTFSSecurity.dll-Help.xml | 8 +-- Tests/ParameterSets.Access.Tests.ps1 | 68 ++++++++++++++++-- Tests/ParameterSets.Audit.Tests.ps1 | 76 +++++++++++++++++--- 12 files changed, 172 insertions(+), 50 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 4e79419..ff33a7c 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -226,6 +226,12 @@ The format is based on `-PropagationFlags`; `-AppliesTo` is now mandatory in the `Simple` parameter sets, so such a command uses the flag parameters and their defaults, as for a path +- Fix `Add-NTFSAccess`, `Remove-NTFSAccess`, `Add-NTFSAudit`, and + `Remove-NTFSAudit`, which ignored the `AppliesTo` property of an object + piped to them with a path and used the default scope; the property now + sets the scope. A piped object that has `AppliesTo` and `InheritanceFlags` + or `PropagationFlags` now fails with `AmbiguousParameterSet`, like the + same parameters on the command line, instead of using the flags - Fix `Get-NTFSEffectiveAccess`: `-ExcludeNoneAccessEntries` now leaves out items without access, the cmdlet uses the current location when `-Path` is omitted, and `-SecurityDescriptor` returns the effective access of the diff --git a/Docs/Cmdlets/Add-NTFSAccess.md b/Docs/Cmdlets/Add-NTFSAccess.md index d30e4c6..e605ba4 100644 --- a/Docs/Cmdlets/Add-NTFSAccess.md +++ b/Docs/Cmdlets/Add-NTFSAccess.md @@ -13,17 +13,17 @@ Adds an access control entry (ACE) to a file, a folder, or a security descriptor ## SYNTAX -### PathComplex (Default) +### PathSimple ``` Add-NTFSAccess [-Path] [-Account] [-AccessRights] - [-AccessType ] [-InheritanceFlags ] - [-PropagationFlags ] [-PassThru] [] + [-AccessType ] -AppliesTo [-PassThru] [] ``` -### PathSimple +### PathComplex ``` Add-NTFSAccess [-Path] [-Account] [-AccessRights] - [-AccessType ] -AppliesTo [-PassThru] [] + [-AccessType ] [-InheritanceFlags ] + [-PropagationFlags ] [-PassThru] [] ``` ### SDSimple @@ -46,7 +46,7 @@ Adds an access control entry (ACE) to the discretionary access control list (DAC `-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 without `-AppliesTo` uses a `Complex` set, also when it works on a security descriptor. Before 5.0.0, a command that used `-SecurityDescriptor` without `-AppliesTo`, `-InheritanceFlags`, or `-PropagationFlags` failed, because PowerShell couldn't choose between the two `SD` sets. +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. A command without `-AppliesTo` uses a `Complex` set, also when it works on a security descriptor, and a command that has `-AppliesTo` together with `-InheritanceFlags` or `-PropagationFlags` fails, because PowerShell can't choose between the sets. The same holds for an object that you pipe in: its property `AppliesTo` selects a `Simple` set, its properties `InheritanceFlags` and `PropagationFlags` select a `Complex` set, and an object that has both kinds fails. Before 5.0.0, a command that used `-SecurityDescriptor` without `-AppliesTo`, `-InheritanceFlags`, or `-PropagationFlags` failed, because PowerShell couldn't choose between the two `SD` sets. 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. @@ -196,7 +196,7 @@ Specifies the path of one or more files or folders the ACE is added to. Relative ```yaml Type: String[] -Parameter Sets: PathComplex, PathSimple +Parameter Sets: PathSimple, PathComplex Aliases: FullName Required: True diff --git a/Docs/Cmdlets/Add-NTFSAudit.md b/Docs/Cmdlets/Add-NTFSAudit.md index f6b3bcd..68bc7a5 100644 --- a/Docs/Cmdlets/Add-NTFSAudit.md +++ b/Docs/Cmdlets/Add-NTFSAudit.md @@ -13,17 +13,17 @@ Adds an audit entry to a file or folder. ## SYNTAX -### PathComplex (Default) +### PathSimple ``` Add-NTFSAudit [-Path] [-Account] [-AccessRights] - [-AuditFlags ] [-InheritanceFlags ] [-PropagationFlags ] - [-PassThru] [] + [-AuditFlags ] -AppliesTo [-PassThru] [] ``` -### PathSimple +### PathComplex ``` Add-NTFSAudit [-Path] [-Account] [-AccessRights] - [-AuditFlags ] -AppliesTo [-PassThru] [] + [-AuditFlags ] [-InheritanceFlags ] [-PropagationFlags ] + [-PassThru] [] ``` ### SDSimple @@ -46,7 +46,7 @@ The `Add-NTFSAudit` cmdlet adds an audit entry to the system access control list 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. A command without `-AppliesTo` uses a `Complex` set, also when it works on a security descriptor. Before 5.0.0, a command that used `-SecurityDescriptor` without `-AppliesTo`, `-InheritanceFlags`, or `-PropagationFlags` failed, because PowerShell couldn't choose between the two `SD` sets. +A command without `-AppliesTo` uses a `Complex` set, also when it works on a security descriptor, and a command that has `-AppliesTo` together with `-InheritanceFlags` or `-PropagationFlags` fails, because PowerShell can't choose between the sets. The same holds for an object that you pipe in: its property `AppliesTo` selects a `Simple` set, its properties `InheritanceFlags` and `PropagationFlags` select a `Complex` set, and an object that has both kinds fails. Before 5.0.0, a command that used `-SecurityDescriptor` without `-AppliesTo`, `-InheritanceFlags`, or `-PropagationFlags` failed, because PowerShell couldn't choose between the two `SD` sets. 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. @@ -196,7 +196,7 @@ Specifies the files or folders the audit entry is added to. Relative paths are r ```yaml Type: String[] -Parameter Sets: PathComplex, PathSimple +Parameter Sets: PathSimple, PathComplex Aliases: FullName Required: True diff --git a/Docs/Cmdlets/Remove-NTFSAccess.md b/Docs/Cmdlets/Remove-NTFSAccess.md index 86e8d5f..639fcdc 100644 --- a/Docs/Cmdlets/Remove-NTFSAccess.md +++ b/Docs/Cmdlets/Remove-NTFSAccess.md @@ -13,17 +13,17 @@ Removes rights from the access control entries (ACEs) of a file, a folder, or a ## SYNTAX -### PathComplex (Default) +### PathSimple ``` Remove-NTFSAccess [-Path] [-Account] [-AccessRights] - [-AccessType ] [-InheritanceFlags ] - [-PropagationFlags ] [-RemoveSpecific] [-PassThru] [] + [-AccessType ] -AppliesTo [-RemoveSpecific] [-PassThru] [] ``` -### PathSimple +### PathComplex ``` Remove-NTFSAccess [-Path] [-Account] [-AccessRights] - [-AccessType ] -AppliesTo [-RemoveSpecific] [-PassThru] [] + [-AccessType ] [-InheritanceFlags ] + [-PropagationFlags ] [-RemoveSpecific] [-PassThru] [] ``` ### SDSimple @@ -48,7 +48,7 @@ Only the specified rights are taken away: when an entry grants more than `-Acces 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 without `-AppliesTo` uses a `Complex` set, also when it works on a security descriptor. Before 5.0.0, a command that used `-SecurityDescriptor` without `-AppliesTo`, `-InheritanceFlags`, or `-PropagationFlags` failed, because PowerShell couldn't choose between the two `SD` sets. 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. +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`. A command without `-AppliesTo` uses a `Complex` set, also when it works on a security descriptor, and a command that has `-AppliesTo` together with `-InheritanceFlags` or `-PropagationFlags` fails, because PowerShell can't choose between the sets. The same holds for an object that you pipe in: its property `AppliesTo` selects a `Simple` set, its properties `InheritanceFlags` and `PropagationFlags` select a `Complex` set, and an object that has both kinds fails. Before 5.0.0, a command that used `-SecurityDescriptor` without `-AppliesTo`, `-InheritanceFlags`, or `-PropagationFlags` failed, because PowerShell couldn't choose between the two `SD` sets. 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. ## EXAMPLES @@ -192,7 +192,7 @@ Specifies the path of one or more files or folders whose access control entries ```yaml Type: String[] -Parameter Sets: PathComplex, PathSimple +Parameter Sets: PathSimple, PathComplex Aliases: FullName Required: True diff --git a/Docs/Cmdlets/Remove-NTFSAudit.md b/Docs/Cmdlets/Remove-NTFSAudit.md index 68bbeb9..ee7d48d 100644 --- a/Docs/Cmdlets/Remove-NTFSAudit.md +++ b/Docs/Cmdlets/Remove-NTFSAudit.md @@ -13,17 +13,17 @@ Removes an audit entry from a file or folder. ## SYNTAX -### PathComplex (Default) +### PathSimple ``` Remove-NTFSAudit [-Path] [-Account] [-AccessRights] - [-AuditFlags ] [-InheritanceFlags ] [-PropagationFlags ] - [-RemoveSpecific] [-PassThru] [] + [-AuditFlags ] -AppliesTo [-RemoveSpecific] [-PassThru] [] ``` -### PathSimple +### PathComplex ``` Remove-NTFSAudit [-Path] [-Account] [-AccessRights] - [-AuditFlags ] -AppliesTo [-RemoveSpecific] [-PassThru] [] + [-AuditFlags ] [-InheritanceFlags ] [-PropagationFlags ] + [-RemoveSpecific] [-PassThru] [] ``` ### SDSimple @@ -46,7 +46,7 @@ The `Remove-NTFSAudit` cmdlet removes an audit entry from the system access cont 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. A command without `-AppliesTo` uses a `Complex` set, also when it works on a security descriptor. Before 5.0.0, a command that used `-SecurityDescriptor` without `-AppliesTo`, `-InheritanceFlags`, or `-PropagationFlags` failed, because PowerShell couldn't choose between the two `SD` sets. +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`. A command without `-AppliesTo` uses a `Complex` set, also when it works on a security descriptor, and a command that has `-AppliesTo` together with `-InheritanceFlags` or `-PropagationFlags` fails, because PowerShell can't choose between the sets. The same holds for an object that you pipe in: its property `AppliesTo` selects a `Simple` set, its properties `InheritanceFlags` and `PropagationFlags` select a `Complex` set, and an object that has both kinds fails. Before 5.0.0, a command that used `-SecurityDescriptor` without `-AppliesTo`, `-InheritanceFlags`, or `-PropagationFlags` failed, because PowerShell couldn't choose between the two `SD` sets. When you omit them, `-AuditFlags` is `Success, Failure`, `-InheritanceFlags` is `ContainerInherit, ObjectInherit`, `-PropagationFlags` is `None`. 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`. @@ -194,7 +194,7 @@ Specifies the files or folders the audit entry is removed from. Relative paths a ```yaml Type: String[] -Parameter Sets: PathComplex, PathSimple +Parameter Sets: PathSimple, PathComplex Aliases: FullName Required: True diff --git a/NTFSSecurity/AccessCmdlets/AddAccess.cs b/NTFSSecurity/AccessCmdlets/AddAccess.cs index f503aaa..11ea0c3 100644 --- a/NTFSSecurity/AccessCmdlets/AddAccess.cs +++ b/NTFSSecurity/AccessCmdlets/AddAccess.cs @@ -7,7 +7,7 @@ using System.Security.AccessControl; namespace NTFSSecurity { - [Cmdlet(VerbsCommon.Add, "NTFSAccess", DefaultParameterSetName = "PathComplex")] + [Cmdlet(VerbsCommon.Add, "NTFSAccess")] [OutputType(typeof(FileSystemAccessRule2))] public class AddAccess : BaseCmdletWithPrivControl { diff --git a/NTFSSecurity/AccessCmdlets/RemoveAccess.cs b/NTFSSecurity/AccessCmdlets/RemoveAccess.cs index a1c566b..eb49d20 100644 --- a/NTFSSecurity/AccessCmdlets/RemoveAccess.cs +++ b/NTFSSecurity/AccessCmdlets/RemoveAccess.cs @@ -7,7 +7,7 @@ using System.Security.AccessControl; namespace NTFSSecurity { - [Cmdlet(VerbsCommon.Remove, "NTFSAccess", DefaultParameterSetName = "PathComplex")] + [Cmdlet(VerbsCommon.Remove, "NTFSAccess")] [OutputType(typeof(FileSystemAccessRule2))] public class RemoveAccess : BaseCmdletWithPrivControl { diff --git a/NTFSSecurity/AuditCmdlets/AddAudit.cs b/NTFSSecurity/AuditCmdlets/AddAudit.cs index 3e7e097..0ab1ec6 100644 --- a/NTFSSecurity/AuditCmdlets/AddAudit.cs +++ b/NTFSSecurity/AuditCmdlets/AddAudit.cs @@ -7,7 +7,7 @@ using System.Security.AccessControl; namespace NTFSSecurity { - [Cmdlet(VerbsCommon.Add, "NTFSAudit", DefaultParameterSetName = "PathComplex")] + [Cmdlet(VerbsCommon.Add, "NTFSAudit")] [OutputType(typeof(FileSystemAuditRule2))] public class AddAudit : BaseCmdletWithPrivControl { diff --git a/NTFSSecurity/AuditCmdlets/RemoveAudit.cs b/NTFSSecurity/AuditCmdlets/RemoveAudit.cs index c4d2e1b..0891edd 100644 --- a/NTFSSecurity/AuditCmdlets/RemoveAudit.cs +++ b/NTFSSecurity/AuditCmdlets/RemoveAudit.cs @@ -7,7 +7,7 @@ using System.Security.AccessControl; namespace NTFSSecurity { - [Cmdlet(VerbsCommon.Remove, "NTFSAudit", DefaultParameterSetName = "PathComplex")] + [Cmdlet(VerbsCommon.Remove, "NTFSAudit")] [OutputType(typeof(FileSystemAuditRule2))] public class RemoveAudit : BaseCmdletWithPrivControl { diff --git a/NTFSSecurity/en-US/NTFSSecurity.dll-Help.xml b/NTFSSecurity/en-US/NTFSSecurity.dll-Help.xml index 53d4966..20c394e 100644 --- a/NTFSSecurity/en-US/NTFSSecurity.dll-Help.xml +++ b/NTFSSecurity/en-US/NTFSSecurity.dll-Help.xml @@ -12,7 +12,7 @@ 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 without `-AppliesTo` uses a `Complex` set, also when it works on a security descriptor. Before 5.0.0, a command that used `-SecurityDescriptor` without `-AppliesTo`, `-InheritanceFlags`, or `-PropagationFlags` failed, because PowerShell couldn't choose between the two `SD` sets. + 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. A command without `-AppliesTo` uses a `Complex` set, also when it works on a security descriptor, and a command that has `-AppliesTo` together with `-InheritanceFlags` or `-PropagationFlags` fails, because PowerShell can't choose between the sets. The same holds for an object that you pipe in: its property `AppliesTo` selects a `Simple` set, its properties `InheritanceFlags` and `PropagationFlags` select a `Complex` set, and an object that has both kinds fails. Before 5.0.0, a command that used `-SecurityDescriptor` without `-AppliesTo`, `-InheritanceFlags`, or `-PropagationFlags` failed, because PowerShell couldn't choose between the two `SD` sets. 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. @@ -796,7 +796,7 @@ 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. A command without `-AppliesTo` uses a `Complex` set, also when it works on a security descriptor. Before 5.0.0, a command that used `-SecurityDescriptor` without `-AppliesTo`, `-InheritanceFlags`, or `-PropagationFlags` failed, because PowerShell couldn't choose between the two `SD` sets. + A command without `-AppliesTo` uses a `Complex` set, also when it works on a security descriptor, and a command that has `-AppliesTo` together with `-InheritanceFlags` or `-PropagationFlags` fails, because PowerShell can't choose between the sets. The same holds for an object that you pipe in: its property `AppliesTo` selects a `Simple` set, its properties `InheritanceFlags` and `PropagationFlags` select a `Complex` set, and an object that has both kinds fails. Before 5.0.0, a command that used `-SecurityDescriptor` without `-AppliesTo`, `-InheritanceFlags`, or `-PropagationFlags` failed, because PowerShell couldn't choose between the two `SD` sets. 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`. @@ -7721,7 +7721,7 @@ PS C:\Data> Get-NTFSSecurityDescriptor 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. With `-RemoveSpecific`, the cmdlet removes only an entry that matches exactly. 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 without `-AppliesTo` uses a `Complex` set, also when it works on a security descriptor. Before 5.0.0, a command that used `-SecurityDescriptor` without `-AppliesTo`, `-InheritanceFlags`, or `-PropagationFlags` failed, because PowerShell couldn't choose between the two `SD` sets. 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. + 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`. A command without `-AppliesTo` uses a `Complex` set, also when it works on a security descriptor, and a command that has `-AppliesTo` together with `-InheritanceFlags` or `-PropagationFlags` fails, because PowerShell can't choose between the sets. The same holds for an object that you pipe in: its property `AppliesTo` selects a `Simple` set, its properties `InheritanceFlags` and `PropagationFlags` select a `Complex` set, and an object that has both kinds fails. Before 5.0.0, a command that used `-SecurityDescriptor` without `-AppliesTo`, `-InheritanceFlags`, or `-PropagationFlags` failed, because PowerShell couldn't choose between the two `SD` sets. 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. @@ -8560,7 +8560,7 @@ PS C:\Data> Get-NTFSSecurityDescriptor 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. With `-RemoveSpecific`, the cmdlet removes only an entry that matches exactly. 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. A command without `-AppliesTo` uses a `Complex` set, also when it works on a security descriptor. Before 5.0.0, a command that used `-SecurityDescriptor` without `-AppliesTo`, `-InheritanceFlags`, or `-PropagationFlags` failed, because PowerShell couldn't choose between the two `SD` sets. + 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`. A command without `-AppliesTo` uses a `Complex` set, also when it works on a security descriptor, and a command that has `-AppliesTo` together with `-InheritanceFlags` or `-PropagationFlags` fails, because PowerShell can't choose between the sets. The same holds for an object that you pipe in: its property `AppliesTo` selects a `Simple` set, its properties `InheritanceFlags` and `PropagationFlags` select a `Complex` set, and an object that has both kinds fails. Before 5.0.0, a command that used `-SecurityDescriptor` without `-AppliesTo`, `-InheritanceFlags`, or `-PropagationFlags` failed, because PowerShell couldn't choose between the two `SD` sets. When you omit them, `-AuditFlags` is `Success, Failure`, `-InheritanceFlags` is `ContainerInherit, ObjectInherit`, `-PropagationFlags` is `None`. 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`. diff --git a/Tests/ParameterSets.Access.Tests.ps1 b/Tests/ParameterSets.Access.Tests.ps1 index 78825b2..038893b 100644 --- a/Tests/ParameterSets.Access.Tests.ps1 +++ b/Tests/ParameterSets.Access.Tests.ps1 @@ -104,6 +104,38 @@ Describe 'Add-NTFSAccess' { } } + # The property AppliesTo selects PathSimple, InheritanceFlags and PropagationFlags select PathComplex, and an object that + # has none of them gets the default scope. No parameter set is the default: while PathComplex was, an object that had + # AppliesTo bound PathComplex as well, and the cmdlet dropped the property. + Context 'Choosing the parameter set of an object bound through the pipeline by property name' { + It 'Should give the entry for the piped object that has the scope ' -ForEach @( + @{ Name = 'AddPipedThisFolderOnly'; Shape = 'AppliesTo ThisFolderOnly'; Extra = @{ AppliesTo = 'ThisFolderOnly' }; Scope = 'None/None' } + @{ Name = 'AddPipedSubfolders'; Shape = 'AppliesTo ThisFolderAndSubfolders'; Extra = @{ AppliesTo = 'ThisFolderAndSubfolders' }; Scope = 'ContainerInherit/None' } + @{ Name = 'AddPipedInheritOnly'; Shape = 'AppliesTo SubfoldersAndFilesOnly'; Extra = @{ AppliesTo = 'SubfoldersAndFilesOnly' }; Scope = 'ContainerInherit, ObjectInherit/InheritOnly' } + @{ Name = 'AddPipedFlags'; Shape = 'InheritanceFlags and PropagationFlags'; Extra = @{ InheritanceFlags = 'ContainerInherit'; PropagationFlags = 'InheritOnly' }; Scope = 'ContainerInherit/InheritOnly' } + @{ Name = 'AddPipedNoScope'; Shape = 'no scope'; Extra = @{}; Scope = 'ContainerInherit, ObjectInherit/None' } + ) { + $folder = New-TestSandboxItem -Sandbox $sandbox -Name $Name -Directory + + [pscustomobject] (@{ Path = $folder; Account = 'S-1-5-32-546'; AccessRights = 'ReadData' } + $Extra) | Add-NTFSAccess -ErrorAction Stop + + $scopes = @((Get-Acl -LiteralPath $folder).GetAccessRules($true, $false, $sidType) | + Where-Object -FilterScript { $_.IdentityReference.Value -eq 'S-1-5-32-546' } | + ForEach-Object -Process { '{0}/{1}' -f $_.InheritanceFlags, $_.PropagationFlags }) + ($scopes -join ';') | Should -BeExactly $Scope + } + + It 'Should reject a piped object that has both AppliesTo and InheritanceFlags with an AmbiguousParameterSet error and change nothing' { + $folder = New-TestSandboxItem -Sandbox $sandbox -Name 'AddPipedBoth' -Directory + $before = (Get-Acl -LiteralPath $folder).Sddl + $object = [pscustomobject]@{ Path = $folder; Account = 'S-1-1-0'; AccessRights = 'ReadData'; AppliesTo = 'ThisFolderOnly'; InheritanceFlags = 'None' } + + { $object | Add-NTFSAccess -ErrorAction Stop } | Should -Throw -ErrorId 'AmbiguousParameterSet*' + + (Get-Acl -LiteralPath $folder).Sddl | Should -BeExactly $before + } + } + Context 'PathSimple parameter set' { It 'Should report a missing path''s error by category and target, still scope the next path''s entry, and keep binding -Path through the pipeline once -AppliesTo selects the set' { $missing = Join-Path -Path $sandbox -ChildPath ('AddSimpleMissing-{0}' -f [guid]::NewGuid().ToString('N').Substring(0, 8)) @@ -119,11 +151,7 @@ Describe 'Add-NTFSAccess' { $fileRule = @((Get-Acl -LiteralPath $file).GetAccessRules($true, $false, $sidType) | Where-Object -FilterScript { $_.IdentityReference.Value -eq 'S-1-1-0' }) $fileRule | Should -HaveCount 1 - # A plain object with an AppliesTo property does not steer the pipeline to PathSimple by itself: both - # PathComplex (default) and PathSimple can bind the object's Path/Account/AccessRights, and the module - # resolves the ambiguity to the default set, PathComplex, silently ignoring the unmatched AppliesTo - # property (see the report). -AppliesTo named explicitly still selects PathSimple while -Path arrives - # through the pipeline. + # -AppliesTo named explicitly selects PathSimple while -Path arrives through the pipeline. $folder = New-TestSandboxItem -Sandbox $sandbox -Name 'AddSimplePipedFolder' -Directory Get-Item2 -Path $folder | Add-NTFSAccess -Account 'S-1-5-32-546' -AccessRights ReadData -AppliesTo ThisFolderAndSubfolders -ErrorAction Stop @@ -170,6 +198,36 @@ Describe 'Remove-NTFSAccess' { } } + # As for Add-NTFSAccess, the property AppliesTo of the piped object selects PathSimple, and the entry that the cmdlet + # addresses is the one of the scope it names: the rest of an entry of a wider scope stays. + Context 'Choosing the parameter set of an object bound through the pipeline by property name' { + It 'Should leave of an entry that applies to this folder, subfolders, and files when the piped object that has removes its rights' -ForEach @( + @{ Name = 'RemovePipedThisFolderOnly'; Shape = 'AppliesTo ThisFolderOnly'; Extra = @{ AppliesTo = 'ThisFolderOnly' }; Meaning = 'the part that only subfolders and files inherit'; Left = 'ContainerInherit, ObjectInherit/InheritOnly' } + @{ Name = 'RemovePipedNoScope'; Shape = 'no scope'; Extra = @{}; Meaning = 'nothing'; Left = '' } + ) { + $folder = New-TestSandboxItem -Sandbox $sandbox -Name $Name -Directory + Add-NTFSAccess -Path $folder -Account 'S-1-5-32-546' -AccessRights ReadData -AppliesTo ThisFolderSubfoldersAndFiles -ErrorAction Stop + + [pscustomobject] (@{ Path = $folder; Account = 'S-1-5-32-546'; AccessRights = 'ReadData' } + $Extra) | Remove-NTFSAccess -ErrorAction Stop + + $remaining = @((Get-Acl -LiteralPath $folder).GetAccessRules($true, $false, $sidType) | + Where-Object -FilterScript { $_.IdentityReference.Value -eq 'S-1-5-32-546' } | + ForEach-Object -Process { '{0}/{1}' -f $_.InheritanceFlags, $_.PropagationFlags }) + ($remaining -join ';') | Should -BeExactly $Left + } + + It 'Should reject a piped object that has both AppliesTo and InheritanceFlags with an AmbiguousParameterSet error and change nothing' { + $folder = New-TestSandboxItem -Sandbox $sandbox -Name 'RemovePipedBoth' -Directory + Add-NTFSAccess -Path $folder -Account 'S-1-1-0' -AccessRights ReadData -AppliesTo ThisFolderOnly -ErrorAction Stop + $before = (Get-Acl -LiteralPath $folder).Sddl + $object = [pscustomobject]@{ Path = $folder; Account = 'S-1-1-0'; AccessRights = 'ReadData'; AppliesTo = 'ThisFolderOnly'; InheritanceFlags = 'None' } + + { $object | Remove-NTFSAccess -ErrorAction Stop } | Should -Throw -ErrorId 'AmbiguousParameterSet*' + + (Get-Acl -LiteralPath $folder).Sddl | Should -BeExactly $before + } + } + Context 'PathSimple parameter set' { It 'Should take only the requested rights from an entry scoped by -AppliesTo without -RemoveSpecific, keep its flags, and leave another account''s entry untouched' { $folder = New-TestSandboxItem -Sandbox $sandbox -Name 'RemoveSimpleScope' -Directory diff --git a/Tests/ParameterSets.Audit.Tests.ps1 b/Tests/ParameterSets.Audit.Tests.ps1 index ddd20dc..8ba9ef7 100644 --- a/Tests/ParameterSets.Audit.Tests.ps1 +++ b/Tests/ParameterSets.Audit.Tests.ps1 @@ -117,12 +117,12 @@ Describe 'Audit cmdlets with a security descriptor that has no audit section' { Describe 'Add-NTFSAudit' { Context 'Binding -Path from the pipeline by property name' { - # -AppliesTo is named for the Simple row, not piped: an object with an AppliesTo property binds the default set - # PathComplex and the property is dropped (the folders show it: the scope of the entry stays the default one), so - # only the named parameter selects PathSimple. + # The PathSimple row pipes AppliesTo, which selects the set; the PathSimpleNamed row names -AppliesTo instead, and the + # piped object brings only the path. It 'Should add the audit entry for the piped object that exists, write a ReadFileError for the one that does not, and leave the DACL unchanged' -ForEach @( @{ Set = 'PathComplex'; ExtraProperties = @{ InheritanceFlags = 'None'; PropagationFlags = 'None' }; Named = @{} } - @{ Set = 'PathSimple'; ExtraProperties = @{}; Named = @{ AppliesTo = 'ThisFolderOnly' } } + @{ Set = 'PathSimple'; ExtraProperties = @{ AppliesTo = 'ThisFolderOnly' }; Named = @{} } + @{ Set = 'PathSimpleNamed'; ExtraProperties = @{}; Named = @{ AppliesTo = 'ThisFolderOnly' } } ) -Skip:(-not $canReadAudit) { $missing = Join-Path -Path $sandbox -ChildPath ('AddPipeMissing-{0}' -f [guid]::NewGuid().ToString('N')) Assert-TestSandboxPath -Sandbox $sandbox -Path $missing @@ -157,8 +157,8 @@ Describe 'Add-NTFSAudit' { ) -Skip:(-not $canReadAudit) { $badFile = New-TestSandboxItem -Sandbox $sandbox -Name "AddPipeSDBad$Set" $sdBad = Get-TestAccessOnlyDescriptor -Path $badFile - # A folder, so that the scope of the entry is observable; for a descriptor the piped AppliesTo property does bind - # SDSimple (no default set competes: Path is not on the object), unlike for a path + # A folder, so that the scope of the entry is observable; the piped AppliesTo property binds SDSimple, as it binds + # PathSimple for a path $goodFile = New-TestSandboxItem -Sandbox $sandbox -Name "AddPipeSDGood$Set" -Directory $auditBefore = Get-TestAuditSddl -Path $goodFile $daclBefore = Get-TestDaclSddl -Path $goodFile @@ -189,6 +189,35 @@ Describe 'Add-NTFSAudit' { } } + # The property AppliesTo selects PathSimple, InheritanceFlags and PropagationFlags select PathComplex, and an object that + # has none of them gets the default scope, as for Add-NTFSAccess (ParameterSets.Access.Tests.ps1). + Context 'Choosing the parameter set of an object bound through the pipeline by property name' { + It 'Should give the audit entry for the piped object that has the scope ' -ForEach @( + @{ Name = 'AddPipedAuditThisFolderOnly'; Shape = 'AppliesTo ThisFolderOnly'; Extra = @{ AppliesTo = 'ThisFolderOnly' }; Scope = 'None/None' } + @{ Name = 'AddPipedAuditSubfolders'; Shape = 'AppliesTo ThisFolderAndSubfolders'; Extra = @{ AppliesTo = 'ThisFolderAndSubfolders' }; Scope = 'ContainerInherit/None' } + @{ Name = 'AddPipedAuditFlags'; Shape = 'InheritanceFlags and PropagationFlags'; Extra = @{ InheritanceFlags = 'ContainerInherit'; PropagationFlags = 'InheritOnly' }; Scope = 'ContainerInherit/InheritOnly' } + @{ Name = 'AddPipedAuditNoScope'; Shape = 'no scope'; Extra = @{}; Scope = 'ContainerInherit, ObjectInherit/None' } + ) -Skip:(-not $canReadAudit) { + $folder = New-TestSandboxItem -Sandbox $sandbox -Name $Name -Directory + + [pscustomobject] (@{ FullName = $folder; Account = $probe; AccessRights = 'ReadData' } + $Extra) | Add-NTFSAudit -ErrorAction Stop + + $scopes = @(Get-TestAccountAuditRule -Acl (Get-Acl -LiteralPath $folder -Audit) -Account $probe | + ForEach-Object -Process { '{0}/{1}' -f $_.InheritanceFlags, $_.PropagationFlags }) + ($scopes -join ';') | Should -BeExactly $Scope + } + + It 'Should reject a piped object that has both AppliesTo and InheritanceFlags with an AmbiguousParameterSet error and change nothing' { + $folder = New-TestSandboxItem -Sandbox $sandbox -Name 'AddPipedAuditBoth' -Directory + $before = Get-TestDaclSddl -Path $folder + $object = [pscustomobject]@{ FullName = $folder; Account = $probe; AccessRights = 'ReadData'; AppliesTo = 'ThisFolderOnly'; InheritanceFlags = 'None' } + + { $object | Add-NTFSAudit -ErrorAction Stop } | Should -Throw -ErrorId 'AmbiguousParameterSet*' + + Get-TestDaclSddl -Path $folder | Should -BeExactly $before + } + } + Context 'Conflicting parameters' { It 'Should reject -AppliesTo combined with -InheritanceFlags with an AmbiguousParameterSet error and change nothing' { $file = New-TestSandboxItem -Sandbox $sandbox -Name 'AddAmbiguous' @@ -220,11 +249,12 @@ Describe 'Add-NTFSAudit' { Describe 'Remove-NTFSAudit' { Context 'Binding -Path from the pipeline by property name' { - # -AppliesTo is named for the Simple row, not piped: a piped AppliesTo property would be dropped for a path (the - # default set PathComplex wins), so only the named parameter selects PathSimple. + # The PathSimple row pipes AppliesTo, which selects the set; the PathSimpleNamed row names -AppliesTo instead, and the + # piped object brings only the path. It "Should remove the audit entry for the piped object that exists, write a ReadFileError for the one that does not, and keep the other account's entry" -ForEach @( @{ Set = 'PathComplex'; ExtraProperties = @{ InheritanceFlags = 'None'; PropagationFlags = 'None' }; Named = @{} } - @{ Set = 'PathSimple'; ExtraProperties = @{}; Named = @{ AppliesTo = 'ThisFolderOnly' } } + @{ Set = 'PathSimple'; ExtraProperties = @{ AppliesTo = 'ThisFolderOnly' }; Named = @{} } + @{ Set = 'PathSimpleNamed'; ExtraProperties = @{}; Named = @{ AppliesTo = 'ThisFolderOnly' } } ) -Skip:(-not $canReadAudit) { $missing = Join-Path -Path $sandbox -ChildPath ('RemovePipeMissing-{0}' -f [guid]::NewGuid().ToString('N')) Assert-TestSandboxPath -Sandbox $sandbox -Path $missing @@ -281,6 +311,34 @@ Describe 'Remove-NTFSAudit' { } } + # As for Add-NTFSAudit, the property AppliesTo of the piped object selects PathSimple, and the entry that the cmdlet + # addresses is the one of the scope it names: the rest of an entry of a wider scope stays. + Context 'Choosing the parameter set of an object bound through the pipeline by property name' { + It 'Should leave of an audit entry that applies to this folder, subfolders, and files when the piped object that has removes its rights' -ForEach @( + @{ Name = 'RemovePipedAuditThisFolderOnly'; Shape = 'AppliesTo ThisFolderOnly'; Extra = @{ AppliesTo = 'ThisFolderOnly' }; Meaning = 'the part that only subfolders and files inherit'; Left = 'ContainerInherit, ObjectInherit/InheritOnly' } + @{ Name = 'RemovePipedAuditNoScope'; Shape = 'no scope'; Extra = @{}; Meaning = 'nothing'; Left = '' } + ) -Skip:(-not $canReadAudit) { + $folder = New-TestSandboxItem -Sandbox $sandbox -Name $Name -Directory + Add-NTFSAudit -Path $folder @entry -ErrorAction Stop + + [pscustomobject] (@{ FullName = $folder; Account = $probe; AccessRights = 'ReadData' } + $Extra) | Remove-NTFSAudit -ErrorAction Stop + + $remaining = @(Get-TestAccountAuditRule -Acl (Get-Acl -LiteralPath $folder -Audit) -Account $probe | + ForEach-Object -Process { '{0}/{1}' -f $_.InheritanceFlags, $_.PropagationFlags }) + ($remaining -join ';') | Should -BeExactly $Left + } + + It 'Should reject a piped object that has both AppliesTo and InheritanceFlags with an AmbiguousParameterSet error and change nothing' { + $folder = New-TestSandboxItem -Sandbox $sandbox -Name 'RemovePipedAuditBoth' -Directory + $before = Get-TestDaclSddl -Path $folder + $object = [pscustomobject]@{ FullName = $folder; Account = $probe; AccessRights = 'ReadData'; AppliesTo = 'ThisFolderOnly'; InheritanceFlags = 'None' } + + { $object | Remove-NTFSAudit -ErrorAction Stop } | Should -Throw -ErrorId 'AmbiguousParameterSet*' + + Get-TestDaclSddl -Path $folder | Should -BeExactly $before + } + } + Context 'Without -RemoveSpecific' { # Judged-audit-notes.md: "the Modify entry keeps the other rights (probe first, then pin)". It 'Should narrow an entry that grants more rights than it removes, instead of deleting it' -Skip:(-not $canReadAudit) {