fix: return audit entries from -PassThru of the audit cmdlets

Defect 6. With -PassThru, Add-NTFSAudit returned the access entries of a
security descriptor in its SecurityDescriptor sets, and Remove-NTFSAudit
returned the access entries of the item in its Path sets. Both now return
the audit entries, as in their other parameter sets.

Tests/Audit.Tests.ps1: 2 tests; the Remove-NTFSAudit test writes a SACL
and runs in CI.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: AI Assistant <ai@example.com>

CHANGELOG.md

@@ -68,5 +68,8 @@ The format is based on
   both at position 2, so that positional calls failed; `-AccessRights` is
   now at position 3, like in `Remove-NTFSAudit`
   ([#4](https://github.com/raandree/NTFSSecurity/issues/4))
+- Fix `-PassThru` of `Add-NTFSAudit` with `-SecurityDescriptor` and of
+  `Remove-NTFSAudit` with `-Path`, which returned access entries; both now
+  return the audit entries
 
 [Unreleased]: https://github.com/raandree/NTFSSecurity/compare/4.2.6...HEAD

Docs/Cmdlets/Add-NTFSAudit.md

@@ -278,9 +278,9 @@ The value passed to `-AppliesTo` is converted to this type and binds by property
 
 ## OUTPUTS
 
-### Security2.FileSystemAccessRule2
+### Security2.FileSystemAuditRule2
 
-Without `-PassThru` the cmdlet writes nothing. With `-PassThru` the type depends on the parameter set: in the `Path` sets the cmdlet writes all audit entries of the item, explicit and inherited ones, as `Security2.FileSystemAuditRule2` objects, while in the `SecurityDescriptor` sets it writes the access entries of the descriptor as `Security2.FileSystemAccessRule2` objects. Use `Get-NTFSAudit` when you need the audit entries of a security descriptor.
+Without `-PassThru` the cmdlet writes nothing. With `-PassThru` the cmdlet writes all audit entries of the item or the security descriptor, explicit and inherited ones, as `Security2.FileSystemAuditRule2` objects. Before 5.0.0, the `SecurityDescriptor` sets wrote the access entries of the descriptor instead.
 
 ## NOTES
 

Docs/Cmdlets/Remove-NTFSAudit.md

@@ -276,9 +276,9 @@ The value passed to `-AppliesTo` is converted to this type and binds by property
 
 ## OUTPUTS
 
-### Security2.FileSystemAccessRule2
+### Security2.FileSystemAuditRule2
 
-Without `-PassThru` the cmdlet writes nothing. With `-PassThru` the type depends on the parameter set: in the `Path` sets the cmdlet writes all access entries of the item, explicit and inherited ones, as `Security2.FileSystemAccessRule2` objects, while in the `SecurityDescriptor` sets it writes all audit entries of the descriptor as `Security2.FileSystemAuditRule2` objects. Use `Get-NTFSAudit` to check the audit entries of an item after the removal.
+Without `-PassThru` the cmdlet writes nothing. With `-PassThru` the cmdlet writes all audit entries of the item or the security descriptor, explicit and inherited ones, as `Security2.FileSystemAuditRule2` objects. Before 5.0.0, the `Path` sets wrote the access entries of the item instead.
 
 ## NOTES
 

NTFSSecurity/AuditCmdlets/AddAudit.cs

@@ -169,7 +169,7 @@ namespace NTFSSecurity
 
                     if (passThru == true)
                     {
-                        FileSystemAccessRule2.GetFileSystemAccessRules(sd, true, true).ForEach(ace => WriteObject(ace));
+                        FileSystemAuditRule2.GetFileSystemAuditRules(sd, true, true).ForEach(ace => WriteObject(ace));
                     }
                 }
             }

NTFSSecurity/AuditCmdlets/RemoveAudit.cs

@@ -162,7 +162,7 @@ namespace NTFSSecurity
 
                     if (passThru == true)
                     {
-                        FileSystemAccessRule2.GetFileSystemAccessRules(item, true, true).ForEach(ace => WriteObject(ace));
+                        FileSystemAuditRule2.GetFileSystemAuditRules(item, true, true).ForEach(ace => WriteObject(ace));
                     }
                 }
             }

NTFSSecurity/en-US/NTFSSecurity.dll-Help.xml

@@ -1490,10 +1490,10 @@
     <command:returnValues>
       <command:returnValue>
         <dev:type>
-          <maml:name>Security2.FileSystemAccessRule2</maml:name>
+          <maml:name>Security2.FileSystemAuditRule2</maml:name>
         </dev:type>
         <maml:description>
-          <maml:para>Without `-PassThru` the cmdlet writes nothing. With `-PassThru` the type depends on the parameter set: in the `Path` sets the cmdlet writes all audit entries of the item, explicit and inherited ones, as `Security2.FileSystemAuditRule2` objects, while in the `SecurityDescriptor` sets it writes the access entries of the descriptor as `Security2.FileSystemAccessRule2` objects. Use `Get-NTFSAudit` when you need the audit entries of a security descriptor.</maml:para>
+          <maml:para>Without `-PassThru` the cmdlet writes nothing. With `-PassThru` the cmdlet writes all audit entries of the item or the security descriptor, explicit and inherited ones, as `Security2.FileSystemAuditRule2` objects. Before 5.0.0, the `SecurityDescriptor` sets wrote the access entries of the descriptor instead.</maml:para>
         </maml:description>
       </command:returnValue>
     </command:returnValues>
@@ -9083,10 +9083,10 @@ PS C:\Data&gt; Get-NTFSSecurityDescriptor</dev:code>
     <command:returnValues>
       <command:returnValue>
         <dev:type>
-          <maml:name>Security2.FileSystemAccessRule2</maml:name>
+          <maml:name>Security2.FileSystemAuditRule2</maml:name>
         </dev:type>
         <maml:description>
-          <maml:para>Without `-PassThru` the cmdlet writes nothing. With `-PassThru` the type depends on the parameter set: in the `Path` sets the cmdlet writes all access entries of the item, explicit and inherited ones, as `Security2.FileSystemAccessRule2` objects, while in the `SecurityDescriptor` sets it writes all audit entries of the descriptor as `Security2.FileSystemAuditRule2` objects. Use `Get-NTFSAudit` to check the audit entries of an item after the removal.</maml:para>
+          <maml:para>Without `-PassThru` the cmdlet writes nothing. With `-PassThru` the cmdlet writes all audit entries of the item or the security descriptor, explicit and inherited ones, as `Security2.FileSystemAuditRule2` objects. Before 5.0.0, the `Path` sets wrote the access entries of the item instead.</maml:para>
         </maml:description>
       </command:returnValue>
     </command:returnValues>

Tests/Audit.Tests.ps1

@@ -93,4 +93,33 @@ Describe 'Add-NTFSAudit' {
             @($rules | Where-Object -FilterScript { $_.IdentityReference.Value -eq 'S-1-1-0' }) | Should -HaveCount 1
         }
     }
+
+    Context 'With -PassThru' {
+        It 'Should return the audit entries of a security descriptor, not its access entries' {
+            $file = New-TestSandboxItem -Sandbox $sandbox -Name 'PassThru'
+            $sd = Get-NTFSSecurityDescriptor -Path $file
+
+            $result = @(Add-NTFSAudit -SecurityDescriptor $sd -Account 'Everyone' -AccessRights ReadData -InheritanceFlags None -PropagationFlags None -PassThru)
+
+            $result | Should -Not -BeNullOrEmpty
+            $result | ForEach-Object -Process { $_ | Should -BeOfType [Security2.FileSystemAuditRule2] }
+            @($result | Where-Object -FilterScript { $_.Account.Sid -eq 'S-1-1-0' }) | Should -HaveCount 1
+        }
+    }
+}
+
+Describe 'Remove-NTFSAudit' {
+    Context 'With -PassThru' {
+        It 'Should return the audit entries of the item, not its access entries' -Skip:(-not $canReadAudit) {
+            $file = New-TestSandboxItem -Sandbox $sandbox -Name 'PassThru'
+            Add-NTFSAudit -Path $file -Account 'Everyone' -AccessRights ReadData -InheritanceFlags None -PropagationFlags None
+            Add-NTFSAudit -Path $file -Account 'BUILTIN\Users' -AccessRights Delete -InheritanceFlags None -PropagationFlags None
+
+            $result = @(Remove-NTFSAudit -Path $file -Account 'Everyone' -AccessRights ReadData -InheritanceFlags None -PropagationFlags None -PassThru)
+
+            $result | Should -Not -BeNullOrEmpty
+            $result | ForEach-Object -Process { $_ | Should -BeOfType [Security2.FileSystemAuditRule2] }
+            @($result | Where-Object -FilterScript { $_.Account.Sid -eq 'S-1-5-32-545' }) | Should -HaveCount 1
+        }
+    }
 }