diff --git a/CHANGELOG.md b/CHANGELOG.md index ff33a7c..6946ad7 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -228,10 +228,14 @@ The format is based on 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 + piped to them with a path and used the default scope, and which gave a + piped security descriptor object without a scope the scope of the object + before it; the property now sets the scope of its own object only. A piped + object that has `AppliesTo` and `InheritanceFlags` or `PropagationFlags` + now fails with `AmbiguousParameterSet`, like the same parameters on the + command line, and one whose `AppliesTo` is empty fails to bind. A call with + neither `-Path` nor `-SecurityDescriptor` now fails with + `AmbiguousParameterSet` instead of a missing-parameter error for `-Path` - 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 e605ba4..1a13a12 100644 --- a/Docs/Cmdlets/Add-NTFSAccess.md +++ b/Docs/Cmdlets/Add-NTFSAccess.md @@ -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. 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. +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, or an empty `AppliesTo`, 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. diff --git a/Docs/Cmdlets/Add-NTFSAudit.md b/Docs/Cmdlets/Add-NTFSAudit.md index 68bc7a5..49dfa9a 100644 --- a/Docs/Cmdlets/Add-NTFSAudit.md +++ b/Docs/Cmdlets/Add-NTFSAudit.md @@ -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`. -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. +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, or an empty `AppliesTo`, 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. diff --git a/Docs/Cmdlets/Remove-NTFSAccess.md b/Docs/Cmdlets/Remove-NTFSAccess.md index 639fcdc..eade133 100644 --- a/Docs/Cmdlets/Remove-NTFSAccess.md +++ b/Docs/Cmdlets/Remove-NTFSAccess.md @@ -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`. 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. +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, or an empty `AppliesTo`, 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 diff --git a/Docs/Cmdlets/Remove-NTFSAudit.md b/Docs/Cmdlets/Remove-NTFSAudit.md index ee7d48d..9a194e6 100644 --- a/Docs/Cmdlets/Remove-NTFSAudit.md +++ b/Docs/Cmdlets/Remove-NTFSAudit.md @@ -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`. 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. +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, or an empty `AppliesTo`, 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/Docs/Examples.md b/Docs/Examples.md index b6ea942..ed564c5 100644 --- a/Docs/Examples.md +++ b/Docs/Examples.md @@ -173,8 +173,8 @@ Set-NTFSOwner -Path C:\Data -Account 'BUILTIN\Administrators' ## Make several changes in one write Get the security descriptor once, change it in memory, and write it back. -With security descriptor input, specify `-AppliesTo` (or the inheritance and -propagation flags) so that PowerShell can choose the parameter set: +`-AppliesTo` sets the scope of the entry; without it, the entry applies to this +folder, subfolders, and files: ```powershell $sd = Get-NTFSSecurityDescriptor -Path C:\Data diff --git a/NTFSSecurity/AccessCmdlets/AddAccess.cs b/NTFSSecurity/AccessCmdlets/AddAccess.cs index 11ea0c3..5907a1a 100644 --- a/NTFSSecurity/AccessCmdlets/AddAccess.cs +++ b/NTFSSecurity/AccessCmdlets/AddAccess.cs @@ -110,9 +110,14 @@ namespace NTFSSecurity protected override void ProcessRecord() { + // The flags of this record are locals: the fields behind -InheritanceFlags and -PropagationFlags keep the value of the + // previous piped object when the next one binds neither, so the scope that -AppliesTo converts to must not stay in them. + var inheritance = inheritanceFlags; + var propagation = propagationFlags; + if (ParameterSetName.EndsWith("Simple")) { - FileSystemSecurity2.ConvertToFileSystemFlags(appliesTo, out inheritanceFlags, out propagationFlags); + FileSystemSecurity2.ConvertToFileSystemFlags(appliesTo, out inheritance, out propagation); } if (ParameterSetName.StartsWith("Path")) @@ -133,7 +138,7 @@ namespace NTFSSecurity try { - FileSystemAccessRule2.AddFileSystemAccessRule(item, account.ToList(), accessRights, accessType, inheritanceFlags, propagationFlags); + FileSystemAccessRule2.AddFileSystemAccessRule(item, account.ToList(), accessRights, accessType, inheritance, propagation); } catch (UnauthorizedAccessException) { @@ -141,7 +146,7 @@ namespace NTFSSecurity { InvokeAsOwner(item, path, () => { - FileSystemAccessRule2.AddFileSystemAccessRule(item, account.ToList(), accessRights, accessType, inheritanceFlags, propagationFlags); + FileSystemAccessRule2.AddFileSystemAccessRule(item, account.ToList(), accessRights, accessType, inheritance, propagation); }); } catch (Exception ex2) @@ -166,7 +171,7 @@ namespace NTFSSecurity { foreach (var sd in securityDescriptors) { - FileSystemAccessRule2.AddFileSystemAccessRule(sd, account.ToList(), accessRights, accessType, inheritanceFlags, propagationFlags); + FileSystemAccessRule2.AddFileSystemAccessRule(sd, account.ToList(), accessRights, accessType, inheritance, propagation); if (passThru == true) { diff --git a/NTFSSecurity/AccessCmdlets/RemoveAccess.cs b/NTFSSecurity/AccessCmdlets/RemoveAccess.cs index eb49d20..757ac61 100644 --- a/NTFSSecurity/AccessCmdlets/RemoveAccess.cs +++ b/NTFSSecurity/AccessCmdlets/RemoveAccess.cs @@ -121,9 +121,14 @@ namespace NTFSSecurity protected override void ProcessRecord() { + // The flags of this record are locals: the fields behind -InheritanceFlags and -PropagationFlags keep the value of the + // previous piped object when the next one binds neither, so the scope that -AppliesTo converts to must not stay in them. + var inheritance = inheritanceFlags; + var propagation = propagationFlags; + if (ParameterSetName.EndsWith("Simple")) { - FileSystemSecurity2.ConvertToFileSystemFlags(appliesTo, out inheritanceFlags, out propagationFlags); + FileSystemSecurity2.ConvertToFileSystemFlags(appliesTo, out inheritance, out propagation); } if (ParameterSetName.StartsWith("Path")) @@ -142,14 +147,9 @@ namespace NTFSSecurity continue; } - if (ParameterSetName == "PathSimple") - { - FileSystemSecurity2.ConvertToFileSystemFlags(appliesTo, out inheritanceFlags, out propagationFlags); - } - try { - FileSystemAccessRule2.RemoveFileSystemAccessRule(item, account.ToList(), accessRights, accessType, inheritanceFlags, propagationFlags, removeSpecific); + FileSystemAccessRule2.RemoveFileSystemAccessRule(item, account.ToList(), accessRights, accessType, inheritance, propagation, removeSpecific); } catch (UnauthorizedAccessException) { @@ -157,7 +157,7 @@ namespace NTFSSecurity { InvokeAsOwner(item, path, () => { - FileSystemAccessRule2.RemoveFileSystemAccessRule(item, account.ToList(), accessRights, accessType, inheritanceFlags, propagationFlags, removeSpecific); + FileSystemAccessRule2.RemoveFileSystemAccessRule(item, account.ToList(), accessRights, accessType, inheritance, propagation, removeSpecific); }); } catch (Exception ex2) @@ -182,7 +182,7 @@ namespace NTFSSecurity { foreach (var sd in securityDescriptors) { - FileSystemAccessRule2.RemoveFileSystemAccessRule(sd, account.ToList(), accessRights, accessType, inheritanceFlags, propagationFlags, removeSpecific); + FileSystemAccessRule2.RemoveFileSystemAccessRule(sd, account.ToList(), accessRights, accessType, inheritance, propagation, removeSpecific); if (passThru == true) { diff --git a/NTFSSecurity/AuditCmdlets/AddAudit.cs b/NTFSSecurity/AuditCmdlets/AddAudit.cs index 0ab1ec6..e9ea655 100644 --- a/NTFSSecurity/AuditCmdlets/AddAudit.cs +++ b/NTFSSecurity/AuditCmdlets/AddAudit.cs @@ -109,9 +109,14 @@ namespace NTFSSecurity protected override void ProcessRecord() { + // The flags of this record are locals: the fields behind -InheritanceFlags and -PropagationFlags keep the value of the + // previous piped object when the next one binds neither, so the scope that -AppliesTo converts to must not stay in them. + var inheritance = inheritanceFlags; + var propagation = propagationFlags; + if (ParameterSetName.EndsWith("Simple")) { - FileSystemSecurity2.ConvertToFileSystemFlags(appliesTo, out inheritanceFlags, out propagationFlags); + FileSystemSecurity2.ConvertToFileSystemFlags(appliesTo, out inheritance, out propagation); } if (ParameterSetName.StartsWith("Path")) @@ -132,7 +137,7 @@ namespace NTFSSecurity try { - FileSystemAuditRule2.AddFileSystemAuditRule(item, account.ToList(), accessRights, auditFlags, inheritanceFlags, propagationFlags); + FileSystemAuditRule2.AddFileSystemAuditRule(item, account.ToList(), accessRights, auditFlags, inheritance, propagation); } catch (UnauthorizedAccessException) { @@ -140,7 +145,7 @@ namespace NTFSSecurity { InvokeAsOwner(item, path, () => { - FileSystemAuditRule2.AddFileSystemAuditRule(item, account.ToList(), accessRights, auditFlags, inheritanceFlags, propagationFlags); + FileSystemAuditRule2.AddFileSystemAuditRule(item, account.ToList(), accessRights, auditFlags, inheritance, propagation); }); } catch (Exception ex2) @@ -170,7 +175,7 @@ namespace NTFSSecurity continue; } - FileSystemAuditRule2.AddFileSystemAuditRule(sd, account.ToList(), accessRights, auditFlags, inheritanceFlags, propagationFlags); + FileSystemAuditRule2.AddFileSystemAuditRule(sd, account.ToList(), accessRights, auditFlags, inheritance, propagation); if (passThru == true) { diff --git a/NTFSSecurity/AuditCmdlets/RemoveAudit.cs b/NTFSSecurity/AuditCmdlets/RemoveAudit.cs index 0891edd..352b65d 100644 --- a/NTFSSecurity/AuditCmdlets/RemoveAudit.cs +++ b/NTFSSecurity/AuditCmdlets/RemoveAudit.cs @@ -120,9 +120,14 @@ namespace NTFSSecurity protected override void ProcessRecord() { + // The flags of this record are locals: the fields behind -InheritanceFlags and -PropagationFlags keep the value of the + // previous piped object when the next one binds neither, so the scope that -AppliesTo converts to must not stay in them. + var inheritance = inheritanceFlags; + var propagation = propagationFlags; + if (ParameterSetName.EndsWith("Simple")) { - FileSystemSecurity2.ConvertToFileSystemFlags(appliesTo, out inheritanceFlags, out propagationFlags); + FileSystemSecurity2.ConvertToFileSystemFlags(appliesTo, out inheritance, out propagation); } if (ParameterSetName.StartsWith("Path")) @@ -141,14 +146,9 @@ namespace NTFSSecurity continue; } - if (ParameterSetName == "PathSimple") - { - FileSystemSecurity2.ConvertToFileSystemFlags(appliesTo, out inheritanceFlags, out propagationFlags); - } - try { - FileSystemAuditRule2.RemoveFileSystemAuditRule(item, account.ToList(), accessRights, auditFlags, inheritanceFlags, propagationFlags, removeSpecific); + FileSystemAuditRule2.RemoveFileSystemAuditRule(item, account.ToList(), accessRights, auditFlags, inheritance, propagation, removeSpecific); } catch (UnauthorizedAccessException) { @@ -156,7 +156,7 @@ namespace NTFSSecurity { InvokeAsOwner(item, path, () => { - FileSystemAuditRule2.RemoveFileSystemAuditRule(item, account.ToList(), accessRights, auditFlags, inheritanceFlags, propagationFlags, removeSpecific); + FileSystemAuditRule2.RemoveFileSystemAuditRule(item, account.ToList(), accessRights, auditFlags, inheritance, propagation, removeSpecific); }); } catch (Exception ex2) @@ -186,7 +186,7 @@ namespace NTFSSecurity continue; } - FileSystemAuditRule2.RemoveFileSystemAuditRule(sd, account.ToList(), accessRights, auditFlags, inheritanceFlags, propagationFlags, removeSpecific); + FileSystemAuditRule2.RemoveFileSystemAuditRule(sd, account.ToList(), accessRights, auditFlags, inheritance, propagation, removeSpecific); if (passThru == true) { diff --git a/NTFSSecurity/en-US/NTFSSecurity.dll-Help.xml b/NTFSSecurity/en-US/NTFSSecurity.dll-Help.xml index 20c394e..3b67201 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. 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. + 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, or an empty `AppliesTo`, 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`. - 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. + 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, or an empty `AppliesTo`, 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`. 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. + 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, or an empty `AppliesTo`, 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`. 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. + 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, or an empty `AppliesTo`, 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 038893b..69237a6 100644 --- a/Tests/ParameterSets.Access.Tests.ps1 +++ b/Tests/ParameterSets.Access.Tests.ps1 @@ -38,6 +38,17 @@ BeforeAll { $enablePrivileges = $privateData['EnablePrivileges'] $sidType = [System.Security.Principal.SecurityIdentifier] $currentUser = [System.Security.Principal.WindowsIdentity]::GetCurrent().User.Value + + function Get-TestAccountScope { + # The scopes of the explicit entries of one account, each as 'inheritance flags/propagation flags', joined by ';' + param ( + [Parameter(Mandatory)] [System.Security.AccessControl.FileSystemSecurity] $Acl, + [Parameter(Mandatory)] [string] $Account + ) + @($Acl.GetAccessRules($true, $false, $sidType) | + Where-Object -FilterScript { $_.IdentityReference.Value -eq $Account } | + ForEach-Object -Process { '{0}/{1}' -f $_.InheritanceFlags, $_.PropagationFlags }) -join ';' + } } AfterAll { @@ -119,10 +130,7 @@ Describe 'Add-NTFSAccess' { [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 + Get-TestAccountScope -Acl (Get-Acl -LiteralPath $folder) -Account 'S-1-5-32-546' | Should -BeExactly $Scope } It 'Should reject a piped object that has both AppliesTo and InheritanceFlags with an AmbiguousParameterSet error and change nothing' { @@ -136,6 +144,79 @@ Describe 'Add-NTFSAccess' { } } + # PowerShell resets only the parameters that the previous object bound from the pipeline. The scope that the cmdlet + # derives from AppliesTo must therefore not stay in the fields behind InheritanceFlags and PropagationFlags: the next + # object that has no scope, or only one flag, would get it. + Context 'Objects with different scopes in one pipeline' { + It 'Should give each piped path object only its own scope: AppliesTo, none, AppliesTo, one flag, none' { + $folders = @('AddMixedThisFolderOnly', 'AddMixedNoScope', 'AddMixedInheritOnly', 'AddMixedOneFlag', 'AddMixedNoScopeAgain' | + ForEach-Object -Process { New-TestSandboxItem -Sandbox $sandbox -Name $_ -Directory }) + $entry = @{ Account = 'S-1-5-32-546'; AccessRights = 'ReadData' } + + @( + [pscustomobject] ($entry + @{ Path = $folders[0]; AppliesTo = 'ThisFolderOnly' }) + [pscustomobject] ($entry + @{ Path = $folders[1] }) + [pscustomobject] ($entry + @{ Path = $folders[2]; AppliesTo = 'SubfoldersAndFilesOnly' }) + [pscustomobject] ($entry + @{ Path = $folders[3]; InheritanceFlags = 'ContainerInherit' }) + [pscustomobject] ($entry + @{ Path = $folders[4] }) + ) | Add-NTFSAccess -ErrorAction Stop + + $scopes = $folders | ForEach-Object -Process { Get-TestAccountScope -Acl (Get-Acl -LiteralPath $_) -Account 'S-1-5-32-546' } + $scopes -join '|' | Should -BeExactly 'None/None|ContainerInherit, ObjectInherit/None|ContainerInherit, ObjectInherit/InheritOnly|ContainerInherit/None|ContainerInherit, ObjectInherit/None' + } + + It 'Should give each row of an imported CSV file that has an AppliesTo column its own scope' { + $folders = @('AddCsvThisFolderOnly', 'AddCsvSubfolders', 'AddCsvInheritOnly' | + ForEach-Object -Process { New-TestSandboxItem -Sandbox $sandbox -Name $_ -Directory }) + $rows = @( + 'Path,Account,AccessRights,AppliesTo' + ('"{0}",S-1-5-32-546,ReadData,ThisFolderOnly' -f $folders[0]) + ('"{0}",S-1-5-32-546,ReadData,ThisFolderAndSubfolders' -f $folders[1]) + ('"{0}",S-1-5-32-546,ReadData,SubfoldersAndFilesOnly' -f $folders[2]) + ) | ConvertFrom-Csv + + $rows | Add-NTFSAccess -ErrorAction Stop + + $scopes = $folders | ForEach-Object -Process { Get-TestAccountScope -Acl (Get-Acl -LiteralPath $_) -Account 'S-1-5-32-546' } + $scopes -join '|' | Should -BeExactly 'None/None|ContainerInherit/None|ContainerInherit, ObjectInherit/InheritOnly' + } + + # An empty cell is not "no scope": the property AppliesTo is there and cannot be bound, so the row fails, loudly, and the + # cmdlet goes on with the next row. Before the property was bound at all, such a column was ignored. + It 'Should report a binding error for the CSV row whose AppliesTo cell is empty, leave its folder alone, and still process the other rows' { + $folders = @('AddCsvEmptyFirst', 'AddCsvEmptyCell', 'AddCsvEmptyLast' | + ForEach-Object -Process { New-TestSandboxItem -Sandbox $sandbox -Name $_ -Directory }) + $rows = @( + 'Path,Account,AccessRights,AppliesTo' + ('"{0}",S-1-5-32-546,ReadData,ThisFolderOnly' -f $folders[0]) + ('"{0}",S-1-5-32-546,ReadData,' -f $folders[1]) + ('"{0}",S-1-5-32-546,ReadData,SubfoldersAndFilesOnly' -f $folders[2]) + ) | ConvertFrom-Csv + + $rows | Add-NTFSAccess -ErrorVariable addErrors -ErrorAction SilentlyContinue + + @($addErrors) | Should -HaveCount 1 + $addErrors[0].Exception.Message | Should -BeLike '*AppliesTo*' + $scopes = $folders | ForEach-Object -Process { Get-TestAccountScope -Acl (Get-Acl -LiteralPath $_) -Account 'S-1-5-32-546' } + $scopes -join '|' | Should -BeExactly 'None/None||ContainerInherit, ObjectInherit/InheritOnly' + } + + It 'Should give each piped descriptor object only its own scope: AppliesTo, then none' { + $folders = @('AddMixedSDThisFolderOnly', 'AddMixedSDNoScope' | + ForEach-Object -Process { New-TestSandboxItem -Sandbox $sandbox -Name $_ -Directory }) + $descriptors = @(Get-NTFSSecurityDescriptor -Path $folders -ErrorAction Stop) + $entry = @{ Account = 'S-1-5-32-546'; AccessRights = 'ReadData' } + + @( + [pscustomobject] ($entry + @{ SecurityDescriptor = $descriptors[0]; AppliesTo = 'ThisFolderOnly' }) + [pscustomobject] ($entry + @{ SecurityDescriptor = $descriptors[1] }) + ) | Add-NTFSAccess -ErrorAction Stop + + $scopes = $descriptors | ForEach-Object -Process { Get-TestAccountScope -Acl $_.SecurityDescriptor -Account 'S-1-5-32-546' } + $scopes -join '|' | Should -BeExactly 'None/None|ContainerInherit, ObjectInherit/None' + } + } + 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)) @@ -210,10 +291,7 @@ Describe 'Remove-NTFSAccess' { [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 + Get-TestAccountScope -Acl (Get-Acl -LiteralPath $folder) -Account 'S-1-5-32-546' | Should -BeExactly $Left } It 'Should reject a piped object that has both AppliesTo and InheritanceFlags with an AmbiguousParameterSet error and change nothing' { @@ -228,6 +306,46 @@ Describe 'Remove-NTFSAccess' { } } + # As for Add-NTFSAccess: the scope that the cmdlet derives from AppliesTo must not stay for the next object. + Context 'Objects with different scopes in one pipeline' { + It 'Should remove from each piped path object the entry of its own scope: AppliesTo, none, AppliesTo, none' { + $folders = @('RemoveMixedFirst', 'RemoveMixedSecond', 'RemoveMixedThird', 'RemoveMixedFourth' | ForEach-Object -Process { + $folder = New-TestSandboxItem -Sandbox $sandbox -Name $_ -Directory + Add-NTFSAccess -Path $folder -Account 'S-1-5-32-546' -AccessRights ReadData -AppliesTo ThisFolderSubfoldersAndFiles -ErrorAction Stop + $folder + }) + $entry = @{ Account = 'S-1-5-32-546'; AccessRights = 'ReadData' } + + @( + [pscustomobject] ($entry + @{ Path = $folders[0]; AppliesTo = 'ThisFolderOnly' }) + [pscustomobject] ($entry + @{ Path = $folders[1] }) + [pscustomobject] ($entry + @{ Path = $folders[2]; AppliesTo = 'ThisFolderOnly' }) + [pscustomobject] ($entry + @{ Path = $folders[3] }) + ) | Remove-NTFSAccess -ErrorAction Stop + + $remaining = $folders | ForEach-Object -Process { Get-TestAccountScope -Acl (Get-Acl -LiteralPath $_) -Account 'S-1-5-32-546' } + $remaining -join '|' | Should -BeExactly 'ContainerInherit, ObjectInherit/InheritOnly||ContainerInherit, ObjectInherit/InheritOnly|' + } + + It 'Should remove from each piped descriptor object the entry of its own scope: AppliesTo, then none' { + $folders = @('RemoveMixedSDFirst', 'RemoveMixedSDSecond' | ForEach-Object -Process { + $folder = New-TestSandboxItem -Sandbox $sandbox -Name $_ -Directory + Add-NTFSAccess -Path $folder -Account 'S-1-5-32-546' -AccessRights ReadData -AppliesTo ThisFolderSubfoldersAndFiles -ErrorAction Stop + $folder + }) + $descriptors = @(Get-NTFSSecurityDescriptor -Path $folders -ErrorAction Stop) + $entry = @{ Account = 'S-1-5-32-546'; AccessRights = 'ReadData' } + + @( + [pscustomobject] ($entry + @{ SecurityDescriptor = $descriptors[0]; AppliesTo = 'ThisFolderOnly' }) + [pscustomobject] ($entry + @{ SecurityDescriptor = $descriptors[1] }) + ) | Remove-NTFSAccess -ErrorAction Stop + + $remaining = $descriptors | ForEach-Object -Process { Get-TestAccountScope -Acl $_.SecurityDescriptor -Account 'S-1-5-32-546' } + $remaining -join '|' | Should -BeExactly 'ContainerInherit, ObjectInherit/InheritOnly|' + } + } + 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 8ba9ef7..87956c4 100644 --- a/Tests/ParameterSets.Audit.Tests.ps1 +++ b/Tests/ParameterSets.Audit.Tests.ps1 @@ -78,6 +78,13 @@ BeforeAll { ) @($Acl.GetAuditRules($true, $false, $sidType) | Where-Object -FilterScript { $_.IdentityReference.Value -eq $Account }) } + + function Get-TestAuditScope { + # The scopes of the explicit audit entries of the probe account, each as 'inheritance flags/propagation flags', joined by ';' + param ([Parameter(Mandatory)] [System.Security.AccessControl.FileSystemSecurity] $Acl) + @(Get-TestAccountAuditRule -Acl $Acl -Account $probe | + ForEach-Object -Process { '{0}/{1}' -f $_.InheritanceFlags, $_.PropagationFlags }) -join ';' + } } AfterAll { @@ -202,9 +209,7 @@ Describe 'Add-NTFSAudit' { [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 + Get-TestAuditScope -Acl (Get-Acl -LiteralPath $folder -Audit) | Should -BeExactly $Scope } It 'Should reject a piped object that has both AppliesTo and InheritanceFlags with an AmbiguousParameterSet error and change nothing' { @@ -218,6 +223,77 @@ Describe 'Add-NTFSAudit' { } } + # PowerShell resets only the parameters that the previous object bound from the pipeline. The scope that the cmdlet + # derives from AppliesTo must therefore not stay in the fields behind InheritanceFlags and PropagationFlags: the next + # object that has no scope, or only one flag, would get it (ParameterSets.Access.Tests.ps1 has the same rows). + Context 'Objects with different scopes in one pipeline' { + It 'Should give each piped path object only its own scope: AppliesTo, none, AppliesTo, one flag, none' -Skip:(-not $canReadAudit) { + $folders = @('AddMixedAuditThisFolderOnly', 'AddMixedAuditNoScope', 'AddMixedAuditInheritOnly', 'AddMixedAuditOneFlag', 'AddMixedAuditNoScopeAgain' | + ForEach-Object -Process { New-TestSandboxItem -Sandbox $sandbox -Name $_ -Directory }) + + @( + [pscustomobject] ($entry + @{ FullName = $folders[0]; AppliesTo = 'ThisFolderOnly' }) + [pscustomobject] ($entry + @{ FullName = $folders[1] }) + [pscustomobject] ($entry + @{ FullName = $folders[2]; AppliesTo = 'SubfoldersAndFilesOnly' }) + [pscustomobject] ($entry + @{ FullName = $folders[3]; InheritanceFlags = 'ContainerInherit' }) + [pscustomobject] ($entry + @{ FullName = $folders[4] }) + ) | Add-NTFSAudit -ErrorAction Stop + + $scopes = $folders | ForEach-Object -Process { Get-TestAuditScope -Acl (Get-Acl -LiteralPath $_ -Audit) } + $scopes -join '|' | Should -BeExactly 'None/None|ContainerInherit, ObjectInherit/None|ContainerInherit, ObjectInherit/InheritOnly|ContainerInherit/None|ContainerInherit, ObjectInherit/None' + } + + It 'Should give each row of an imported CSV file that has an AppliesTo column its own scope' -Skip:(-not $canReadAudit) { + $folders = @('AddCsvAuditThisFolderOnly', 'AddCsvAuditSubfolders', 'AddCsvAuditInheritOnly' | + ForEach-Object -Process { New-TestSandboxItem -Sandbox $sandbox -Name $_ -Directory }) + $rows = @( + 'FullName,Account,AccessRights,AppliesTo' + ('"{0}",{1},ReadData,ThisFolderOnly' -f $folders[0], $probe) + ('"{0}",{1},ReadData,ThisFolderAndSubfolders' -f $folders[1], $probe) + ('"{0}",{1},ReadData,SubfoldersAndFilesOnly' -f $folders[2], $probe) + ) | ConvertFrom-Csv + + $rows | Add-NTFSAudit -ErrorAction Stop + + $scopes = $folders | ForEach-Object -Process { Get-TestAuditScope -Acl (Get-Acl -LiteralPath $_ -Audit) } + $scopes -join '|' | Should -BeExactly 'None/None|ContainerInherit/None|ContainerInherit, ObjectInherit/InheritOnly' + } + + # An empty cell is not "no scope": the property AppliesTo is there and cannot be bound, so the row fails, loudly, and the + # cmdlet goes on with the next row (ParameterSets.Access.Tests.ps1 has the same row). + It 'Should report a binding error for the CSV row whose AppliesTo cell is empty, leave its folder alone, and still process the other rows' -Skip:(-not $canReadAudit) { + $folders = @('AddCsvAuditEmptyFirst', 'AddCsvAuditEmptyCell', 'AddCsvAuditEmptyLast' | + ForEach-Object -Process { New-TestSandboxItem -Sandbox $sandbox -Name $_ -Directory }) + $rows = @( + 'FullName,Account,AccessRights,AppliesTo' + ('"{0}",{1},ReadData,ThisFolderOnly' -f $folders[0], $probe) + ('"{0}",{1},ReadData,' -f $folders[1], $probe) + ('"{0}",{1},ReadData,SubfoldersAndFilesOnly' -f $folders[2], $probe) + ) | ConvertFrom-Csv + + $rows | Add-NTFSAudit -ErrorVariable auditErrors -ErrorAction SilentlyContinue + + @($auditErrors) | Should -HaveCount 1 + $auditErrors[0].Exception.Message | Should -BeLike '*AppliesTo*' + $scopes = $folders | ForEach-Object -Process { Get-TestAuditScope -Acl (Get-Acl -LiteralPath $_ -Audit) } + $scopes -join '|' | Should -BeExactly 'None/None||ContainerInherit, ObjectInherit/InheritOnly' + } + + It 'Should give each piped descriptor object only its own scope: AppliesTo, then none' -Skip:(-not $canReadAudit) { + $folders = @('AddMixedAuditSDThisFolderOnly', 'AddMixedAuditSDNoScope' | + ForEach-Object -Process { New-TestSandboxItem -Sandbox $sandbox -Name $_ -Directory }) + $descriptors = @(Get-NTFSSecurityDescriptor -Path $folders -ErrorAction Stop) + + @( + [pscustomobject] ($entry + @{ SecurityDescriptor = $descriptors[0]; AppliesTo = 'ThisFolderOnly' }) + [pscustomobject] ($entry + @{ SecurityDescriptor = $descriptors[1] }) + ) | Add-NTFSAudit -ErrorAction Stop + + $scopes = $descriptors | ForEach-Object -Process { Get-TestAuditScope -Acl $_.SecurityDescriptor } + $scopes -join '|' | Should -BeExactly 'None/None|ContainerInherit, ObjectInherit/None' + } + } + Context 'Conflicting parameters' { It 'Should reject -AppliesTo combined with -InheritanceFlags with an AmbiguousParameterSet error and change nothing' { $file = New-TestSandboxItem -Sandbox $sandbox -Name 'AddAmbiguous' @@ -249,8 +325,8 @@ Describe 'Add-NTFSAudit' { Describe 'Remove-NTFSAudit' { Context 'Binding -Path from the pipeline by property name' { - # The PathSimple row pipes AppliesTo, which selects the set; the PathSimpleNamed row names -AppliesTo instead, and the - # piped object brings only the path. + # The PathSimple row pipes AppliesTo and the PathSimpleNamed row names it. Neither can tell the sets apart here: the + # entry is on a file, where the scope does not matter. The Contexts on folders below do. 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 = @{ AppliesTo = 'ThisFolderOnly' }; Named = @{} } @@ -323,9 +399,7 @@ Describe 'Remove-NTFSAudit' { [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 + Get-TestAuditScope -Acl (Get-Acl -LiteralPath $folder -Audit) | Should -BeExactly $Left } It 'Should reject a piped object that has both AppliesTo and InheritanceFlags with an AmbiguousParameterSet error and change nothing' { @@ -339,6 +413,44 @@ Describe 'Remove-NTFSAudit' { } } + # As for Add-NTFSAudit: the scope that the cmdlet derives from AppliesTo must not stay for the next object. + Context 'Objects with different scopes in one pipeline' { + It 'Should remove from each piped path object the entry of its own scope: AppliesTo, none, AppliesTo, none' -Skip:(-not $canReadAudit) { + $folders = @('RemoveMixedAuditFirst', 'RemoveMixedAuditSecond', 'RemoveMixedAuditThird', 'RemoveMixedAuditFourth' | ForEach-Object -Process { + $folder = New-TestSandboxItem -Sandbox $sandbox -Name $_ -Directory + Add-NTFSAudit -Path $folder @entry -ErrorAction Stop + $folder + }) + + @( + [pscustomobject] ($entry + @{ FullName = $folders[0]; AppliesTo = 'ThisFolderOnly' }) + [pscustomobject] ($entry + @{ FullName = $folders[1] }) + [pscustomobject] ($entry + @{ FullName = $folders[2]; AppliesTo = 'ThisFolderOnly' }) + [pscustomobject] ($entry + @{ FullName = $folders[3] }) + ) | Remove-NTFSAudit -ErrorAction Stop + + $remaining = $folders | ForEach-Object -Process { Get-TestAuditScope -Acl (Get-Acl -LiteralPath $_ -Audit) } + $remaining -join '|' | Should -BeExactly 'ContainerInherit, ObjectInherit/InheritOnly||ContainerInherit, ObjectInherit/InheritOnly|' + } + + It 'Should remove from each piped descriptor object the entry of its own scope: AppliesTo, then none' -Skip:(-not $canReadAudit) { + $folders = @('RemoveMixedAuditSDFirst', 'RemoveMixedAuditSDSecond' | ForEach-Object -Process { + $folder = New-TestSandboxItem -Sandbox $sandbox -Name $_ -Directory + Add-NTFSAudit -Path $folder @entry -ErrorAction Stop + $folder + }) + $descriptors = @(Get-NTFSSecurityDescriptor -Path $folders -ErrorAction Stop) + + @( + [pscustomobject] ($entry + @{ SecurityDescriptor = $descriptors[0]; AppliesTo = 'ThisFolderOnly' }) + [pscustomobject] ($entry + @{ SecurityDescriptor = $descriptors[1] }) + ) | Remove-NTFSAudit -ErrorAction Stop + + $remaining = $descriptors | ForEach-Object -Process { Get-TestAuditScope -Acl $_.SecurityDescriptor } + $remaining -join '|' | Should -BeExactly 'ContainerInherit, ObjectInherit/InheritOnly|' + } + } + 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) {