The follow-up review of 7bc7925 probed the sentence "an AppliesTo that is an
empty string or not the name of a scope is ignored, and the object gets the
default scope" and found it too narrow. What the cmdlets do, in both
editions, on the package of 9783d2a and on the package before the fix
(probe p-unconvertible-appliesto.ps1):
- A value that PowerShell cannot convert to a scope, such as the empty cell
of a CSV file or a misspelled name, is ignored, and the object is handled
as one without AppliesTo: it uses its own InheritanceFlags and
PropagationFlags, or the default scope when it has none. This is the same
before and after the fix.
- A row of a CSV file with fewer fields than its header gives $null, and a
$null AppliesTo fails to bind for that object.
- An object that has both Path and SecurityDescriptor now fails with
AmbiguousParameterSet; before, the path won and the descriptor was
ignored. No cmdlet of the module produces such an object.
The changelog entry, the four cmdlet pages, and the help file say so.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: AI Assistant <ai@example.com>
The follow-up review of 9783d2a found that "an empty AppliesTo fails to
bind", in the changelog entry and in the four cmdlet pages, holds only for
$null. A blank cell that Import-Csv reads is an empty string, which the
binder cannot convert: PathSimple does not bind, and the row gets the
default scope, as an object without the property does. An AppliesTo that
is not the name of a scope is ignored the same way (probe
p-empty-appliesto.ps1, both editions, on the package of 9783d2a and on
the baseline). Only $null fails to bind, with
ParameterArgumentValidationErrorNullNotAllowed, for that object.
The pages, the help file, and the changelog entry now say so.
The tests of the CSV route read a CSV file with Import-Csv, the route
that the documentation shows, instead of ConvertFrom-Csv of strings,
which makes a trailing blank cell $null. They pin the blank cell as the
default scope and the $null object as a binding error for that object
only, with the other objects processed.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: AI Assistant <ai@example.com>
Independent review of 93ed2c7: ProcessRecord of Add-NTFSAccess,
Remove-NTFSAccess, Add-NTFSAudit, and Remove-NTFSAudit wrote the scope
that it converts from AppliesTo into the fields behind InheritanceFlags
and PropagationFlags. PowerShell resets only the parameters that the
previous piped object bound, so the next object that had no scope, or
only one flag, took the scope of the one before it: AppliesTo
ThisFolderOnly, then none gave None/None twice, and Remove left the
InheritOnly part of every entry. Without the default set (93ed2c7) a
piped path object with AppliesTo reaches that code; for a piped
-SecurityDescriptor object it was a defect of rc7 already.
The flags of a record are locals now. The loop of the two Remove
cmdlets converted the scope a second time into the same fields; the
locals make that redundant, so it is gone.
The tests pipe objects with and without a scope, a CSV file, and
descriptor objects into the four cmdlets: red on the build of 93ed2c7
(8 of 87 cases of the two files, in every elevated configuration; 4 in
the basic-user ones, where the audit rows skip), green on this build.
An empty AppliesTo cell fails to bind for that row only; a test pins it.
The Remove-NTFSAudit PathSimple row cannot tell the sets apart (its
entry is on a file), and its comment says so. Docs/Examples.md no longer
says that a scope is needed so that PowerShell can choose the parameter
set (true before 5.0.0 only); the changelog entry names the new errors.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: AI Assistant <ai@example.com>
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 <ai@example.com>
- #41: for the root of a drive, the cmdlets read and changed the security
descriptor of the drive, a device object. FileSystemSecurity2 now routes
drive roots through the path-based AlphaFS methods, which keep the
trailing backslash; the removal and inheritance helpers use it too.
- #109: Add-, Remove-, and Clear-NTFSAudit report a security descriptor
without the audit entries like Get-NTFSAudit, through one helper, and
Get-NTFSEffectiveAccess names the cause that Windows reported instead
of a missing Security privilege.
- #108: Copy-Item2 and Move-Item2 check the destination only for an
operation that runs; with -WhatIf, a verbose message names the conflict.
- #111: Disable-Privileges skips the privileges that the token doesn't
hold, the privilege messages are spelled right, and Get-FileHash2
declares the type name of its objects; 05-Releasing.md documents the
release metadata tests.
- rc3 review leftovers: Remove-NTFSAudit writes nothing for an item
without a SACL, the owner retry of Set-NTFSSecurityDescriptor restores
the previous owner in a finally block and keeps an owner that the
descriptor sets, and FileSystemSecurity2.Write with another item writes
only the sections that were read.
Each fix has a test that failed first, in Windows PowerShell 5.1 and
PowerShell 7; writing a drive root was checked once on a temporary VHD.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: AI Assistant <ai@example.com>
The cmdlets that take ownership of an item to repeat a denied operation
left the account that ran them as the owner when the second attempt failed
as well. BaseCmdlet.InvokeAsOwner now restores the previous owner on every
exit path and reports a failed restore as RestoreOwnerError.
Add-NTFSAccess, Add-NTFSAudit, Remove-NTFSAccess, and Remove-NTFSAudit
wrote the unchanged entries of an item with -PassThru after a failed
change; they now continue with the next path.
The inheritance tests assert the error identity and cover a missing path
on every runner.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: AI Assistant <ai@example.com>
Defect 19, and the same gap in Remove-NTFSAudit. After the ReadFileError
for a path that doesn't exist, both cmdlets went on with a null item: the
removal failed with a NullReferenceException that they reported as a
second, misleading RemoveAceError, and with -PassThru the null item
stopped the command. Both now continue with the next path.
Tests: Access.Tests.ps1 and Audit.Tests.ps1, 2 tests each.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: AI Assistant <ai@example.com>
Defect 17. Both cmdlets carried a removeSpecific field that no parameter
set, so they always took the rights away from matching entries; the
version history documents a -RemoveSpecific switch since 4.1. Both
cmdlets now have the switch, which removes only an entry that matches
exactly. The Security2 list overloads didn't pass the flag on, and the
audit item overload didn't support it; all overloads now do.
The applies-to field of both cmdlets is initialized; -AppliesTo is
mandatory in the Simple sets since defect 14, so it is always set when
used.
Tests: Access.Tests.ps1 3 tests, Audit.Tests.ps1 2 tests, on in-memory
security descriptors.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: AI Assistant <ai@example.com>
Defect 14. Add-NTFSAccess, Remove-NTFSAccess, Add-NTFSAudit, and
Remove-NTFSAudit have the sets PathSimple, PathComplex, SDSimple, and
SDComplex; the default PathComplex needs -Path. A command with
-SecurityDescriptor and without -AppliesTo, -InheritanceFlags, or
-PropagationFlags matched both SD sets and failed with "Parameter set
cannot be resolved". -AppliesTo is now mandatory in the Simple sets, so
such a command resolves to the Complex set and its default flags
(ContainerInherit, ObjectInherit / None, which is what AppliesTo
ThisFolderSubfoldersAndFiles means), as a command with -Path already did.
With -AppliesTo nothing changes.
The pages say "Required: True" for -AppliesTo and drop its never
reachable defaults; platyPS takes that metadata from the shipped help
file, so the help file was regenerated before the build.
Tests/Access.Tests.ps1: 6 tests on in-memory security descriptors.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: AI Assistant <ai@example.com>
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>
* fix(help): ship the generated help file so Get-Help works
Get-Help showed only the syntax of the cmdlets: the module shipped a
pre-4.x MAML file for the old command names under the wrong name
(NTFSSecurity-Help.xml), while PowerShell looks for
en-US\NTFSSecurity.dll-Help.xml.
- Generate en-US\NTFSSecurity.dll-Help.xml from Docs/Cmdlets with
New-ExternalHelp and commit it. The csproj copies it to the output,
so every build ships it, including the local Debug builds that
releases are published from.
- List all runtime files, including the help file, in FileList.
- Remove the stale NTFSSecurity-Help.xml and the unused help editor
project NTFSSecurity\Help\NTFSSecurity.Help.pshproj.
- Add Tests\Help.Tests.ps1 (Pester 5): Get-Help shows the synopsis,
parameters, examples, and online link of every page, and
Get-Help -Online resolves to the GitHub page.
- Reword six sentences in five cmdlet pages so that each link ends its
sentence: platyPS drops the space after a link in the help text.
- CI regenerates the help file and fails when it differs from the
committed file, then runs the Pester tests.
- Document the regeneration step and the link rule in the contributor
guide.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: AI Assistant <ai@example.com>
* ci: report each Pester test once on AppVeyor
AppVeyor build 54834154 passed all 218 Pester tests but listed 870 on
its Tests tab: the NUnit import files a Pester 5 test under every block
that contains it (Pester, test file, Describe, and Context).
Report the results through the build worker API instead
(POST api/tests/batch): one entry per test with its outcome, duration,
and error message. Outside AppVeyor, and when no test ran, the step
sends nothing.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: AI Assistant <ai@example.com>
---------
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: AI Assistant <ai@example.com>
* chore: initialize the memory bank
Add the canonical .memory-bank base with evidence-based project context:
purpose and scope, workflows, stack and validation commands, architecture
map, decisions, and the open work found while documenting the cmdlets.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: AI Assistant <ai@example.com>
* docs: align documentation with the cmdlet source
- Fill all 36 platyPS cmdlet pages from the C# source: synopsis,
description, parameters, defaults, examples, inputs, outputs, and
notes, including documented limitations of the current code
- Check every example against live parameter metadata and run them in a
sandbox; fix examples that did not work (CSV restore, account filter,
recursive inheritance, -AccessRights typos)
- Rewrite the home, concepts, examples, README, and contributor pages;
add a grouped cmdlet overview, module settings, privileges, long paths,
and the platyPS workflow
- Document Remove-Item2 -PassThru as renamed after 4.2.6 (#64)
- Fix mkdocs.yml navigation, edit_uri, and copyright markup; add
build.os and a pinned MkDocs version for Read the Docs
- Point online help links to the pages on GitHub; add CHANGELOG.md
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: AI Assistant <ai@example.com>
* ci: build the module and check the docs against the build
The documentation check ran Update-MarkdownHelp against the NTFSSecurity
release from the PowerShell Gallery (4.2.6), so it failed for every
unreleased parameter change. PR #91 failed because 4.2.6 still has
Remove-Item2 -PassThur while the source and the docs have -PassThru.
- Build NTFSSecurity.csproj in Release on the Visual Studio 2022 image,
using the .NET Framework 4.5.2 reference assemblies package instead of
an installed targeting pack
- Check Docs/Cmdlets against the module built from source
- Pin platyPS 0.14.2 and MarkdownLinkCheck 0.2.0, and enable TLS 1.2 so
the NuGet provider bootstrap works
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: AI Assistant <ai@example.com>
* chore: record the green PR 91 build in the memory bank
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: AI Assistant <ai@example.com>
---------
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: AI Assistant <ai@example.com>
Raimund Andree
James Smith