BaseCmdletWithPrivControl.BeginProcessing and EndProcessing read
(bool)privateData["EnablePrivileges"] without checking it first; a
setting that is not a Boolean, such as the string '$true' from a typo
in the module manifest, or a missing key, made every cmdlet derived
from the class fail with an InvalidCastException or a
NullReferenceException before anything useful was said.
Enable-Privileges had its own try/catch for the same cast that raised a
different message (a ParseException), but it was unreachable, because
BeginProcessing always failed first.
A new helper, GetEnablePrivilegesSetting, centralizes the check in the
base class: a setting that is missing or not a Boolean now stops the
cmdlet with one terminating error, id EnablePrivilegesSettingInvalid,
category InvalidData, that names the setting, says it must be $true or
$false, and names the module manifest. BeginProcessing, EndProcessing,
and Enable-Privileges all use it now; the dead try/catch of
Enable-Privileges is removed, so a mistaken setting no longer produces
two different messages depending on which cmdlet hit it first. The
valid settings $true and $false keep today's behavior.
GetInheritedFrom (used by Get-NTFSAccess and Get-NTFSAudit),
GetFileSystemModeProperty, and IdentifyHardLinks (both used by
Get-ChildItem2) read their own setting the same unchecked way and share
this weakness; they are not changed here; see the final report.
Breaking: a script that caught the old InvalidCastException,
NullReferenceException, or ParseException for a malformed
EnablePrivileges setting now needs to catch the terminating error with
id EnablePrivilegesSettingInvalid instead.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: AI Assistant <ai@example.com>
Add tests for the error handling that the cmdlets with -Path share: a
path that doesn't exist (16 cmdlets, and 6 audit cmdlets with the
Security privilege), an item whose owner may not read its permissions
(6 cmdlets), and an item whose owner may not change them, which the 6
cmdlets that write the DACL handle by taking ownership. Each error
belongs to its path only, and the cmdlet goes on with the next one.
The tests found one defect: Get-NTFSOrphanedAccess reported an item that
it couldn't read as an AddAceError with the category WriteError. It now
writes a ReadSecurityError, like Get-NTFSAccess.
They also show that the take-ownership retry works without privileges
when the account holds the Take Ownership right and may assign the
previous owner, and that it can't help a denied read, because reading
the owner needs the same right. Concepts and five cmdlet pages said that
the retry needs the privileges; they now describe both, and that Windows
removes the OWNER RIGHTS entries when the owner changes.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: AI Assistant <ai@example.com>
A cmdlet that enables the Backup, Restore, Take Ownership, and Security
privileges decided which ones to disable on the states that it had read
when it enabled them, and stopped at the first one that failed. When
another command in the pipeline, such as Disable-Privileges, had disabled
one of them, the cmdlet stopped with "Priviledge already disabled" and
left the privileges after that one enabled. After an early stop, which
Dispose handles since this branch, it left them enabled without any
message, because PowerShell ignores exceptions thrown in Dispose; and
Disable-Privileges threw that exception in Dispose on every call while
the privileges were disabled. 4.2.6 already decided on the old states.
DisablePrivilege now reads the current state, and the cleanup tries every
privilege: in EndProcessing, a privilege that it can't disable gives a
warning; in Dispose, it is ignored.
The early-stop tests now pin EnablePrivileges and check that the cmdlet
had enabled the privileges, so that they can't pass without testing
anything.
Found by the security review of fcb370e..00c3646 (findings 1 to 3).
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: AI Assistant <ai@example.com>
The cmdlets that enable the Backup, Restore, Take Ownership, and Security
privileges disabled them only in EndProcessing, which PowerShell skips
when a later command, such as Select-Object -First, or a terminating
error stops the pipeline. The privileges then stayed enabled in the
session. BaseCmdletWithPrivControl now implements IDisposable and
disables them in Dispose as well; Enable-Privileges keeps them.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: AI Assistant <ai@example.com>
The types file added the alias Size of LengthOnDisk to System.IO.FileInfo.
Type data can't replace an existing member, so in Windows PowerShell the
import failed when another module had added a Size member first (#82).
BREAKING CHANGE: use LengthOnDisk instead of Size.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: AI Assistant <ai@example.com>
-AccessInheritanceEnabled $false now copies the inherited access entries
into the DACL, and -AuditInheritanceEnabled $true keeps the explicit audit
entries, as Disable-NTFSAccessInheritance and Enable-NTFSAuditInheritance
do without their switches (Decision 13).
BREAKING CHANGE: to remove the entries, use
Disable-NTFSAccessInheritance -RemoveInheritedAccessRules or
Enable-NTFSAuditInheritance -RemoveExplicitAuditRules.
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 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 12. Besides the base class, which enables the privileges only when
the module setting EnablePrivileges is $true and disables them again in
EndProcessing, the six inheritance cmdlets called
EnableFileSystemPrivileges in BeginProcessing unconditionally. With
EnablePrivileges = $false they enabled the privileges anyway and, because
EndProcessing disables them only when the setting is $true, left them
enabled. The extra calls are gone; the inheritance cmdlets now behave like
the other cmdlets.
Tests/Privileges.Tests.ps1: 6 tests, one per cmdlet, CI-only, because
they need a token that holds the privileges. Without the fix the Backup
privilege is enabled after each call.
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
sup3rlativ3