WindowsAccessControl

Author(s)

• WindowsAccessControl contributors

Tags

NTFS Registry Service Process TaskScheduler Certificate CNG Permissions ACL Security DSC Windows

Functions

Add-ADObjectAccessRule Add-CertificatePrivateKeyAccessRule Add-NTFSAccessRule Add-NTFSAuditRule Add-ProcessAccessRule Add-ProcessAuditRule Add-RegistryKeyAccessRule Add-RegistryKeyAuditRule Add-ScheduledTaskAccessRule Add-ServiceAccessRule Add-ServiceAuditRule Add-SmbShareAccessRule Add-TaskFolderAccessRule Backup-NTFSItemSecurityDescriptor Backup-WindowsSecurityDescriptor Clear-ADObjectAccessRule Clear-NTFSAccessRule Clear-NTFSAuditRule Clear-ProcessAccessRule Clear-ProcessAuditRule Clear-RegistryKeyAccessRule Clear-RegistryKeyAuditRule Clear-ServiceAccessRule Clear-ServiceAuditRule Copy-NTFSItemSecurityDescriptor Disable-NTFSItemInheritance Disable-RegistryKeyInheritance Disable-WindowsPrivilege Edit-NTFSItemSecurityDescriptor Edit-RegistryKeySecurityDescriptor Enable-NTFSItemInheritance Enable-RegistryKeyInheritance Enable-WindowsPrivilege Get-ADObjectAccessRule Get-ADObjectCallerEffectiveAccess Get-ADObjectSchemaDefaultAccessRule Get-ADObjectSecurityDescriptor Get-CertificatePrivateKeyAccessRule Get-CertificatePrivateKeySecurityDescriptor Get-NTFSAccessRule Get-NTFSAuditRule Get-NTFSItemEffectiveAccess Get-NTFSItemInheritance Get-NTFSItemOwner Get-NTFSItemSecurityDescriptor Get-ProcessAccessRule Get-ProcessAuditRule Get-ProcessSecurityDescriptor Get-RegistryKeyAccessRule Get-RegistryKeyAuditRule Get-RegistryKeyInheritance Get-RegistryKeySecurityDescriptor Get-ScheduledTaskAccessRule Get-ScheduledTaskSecurityDescriptor Get-ServiceAccessRule Get-ServiceAuditRule Get-ServiceSecurityDescriptor Get-SmbShareAccessRule Get-SmbShareEffectiveAccess Get-SmbShareSecurityDescriptor Get-TaskFolderAccessRule Get-TaskFolderSecurityDescriptor Get-WindowsAccessControlMetric Get-WindowsPrivilege Invoke-WindowsAccessControl New-NTFSAccessRule New-NTFSAuditRule Remove-ADObjectAccessRule Remove-CertificatePrivateKeyAccessRule Remove-NTFSAccessRule Remove-NTFSAuditRule Remove-ProcessAccessRule Remove-ProcessAuditRule Remove-RegistryKeyAccessRule Remove-RegistryKeyAuditRule Remove-ScheduledTaskAccessRule Remove-ServiceAccessRule Remove-ServiceAuditRule Remove-SmbShareAccessRule Remove-TaskFolderAccessRule Resolve-WindowsIdentity Restore-NTFSItemSecurityDescriptor Restore-WindowsSecurityDescriptor Set-ADObjectAccessRule Set-ADObjectSecurityDescriptor Set-CertificatePrivateKeySecurityDescriptor Set-NTFSAccessRule Set-NTFSAuditRule Set-NTFSItemOwner Set-NTFSItemSecurityDescriptor Set-ProcessAccessRule Set-ProcessAuditRule Set-ProcessSecurityDescriptor Set-RegistryKeyAccessRule Set-RegistryKeyAuditRule Set-RegistryKeySecurityDescriptor Set-ScheduledTaskSecurityDescriptor Set-ServiceAccessRule Set-ServiceAuditRule Set-ServiceSecurityDescriptor Set-SmbShareSecurityDescriptor Set-TaskFolderSecurityDescriptor Test-CertificatePrivateKeyCriticalBinding Test-NTFSItemAcl Test-WindowsPrivilege

DSCResources

WindowsAccessControlNtfsSecurityDescriptor WindowsAccessControlRegistryKeySecurityDescriptor WindowsAccessControlServiceSecurityDescriptor WindowsAccessControlServiceControlManagerSecurityDescriptor WindowsAccessControlProcessSecurityDescriptor WindowsAccessControlSmbShareSecurityDescriptor WindowsAccessControlADObjectSecurityDescriptor WindowsAccessControlTaskFolderSecurityDescriptor WindowsAccessControlScheduledTaskSecurityDescriptor WindowsAccessControlCertificatePrivateKeySecurityDescriptor WindowsAccessControlNtfsAccessRule WindowsAccessControlRegistryKeyAccessRule WindowsAccessControlServiceAccessRule WindowsAccessControlServiceControlManagerAccessRule WindowsAccessControlProcessAccessRule WindowsAccessControlSmbShareAccessRule WindowsAccessControlADObjectAccessRule WindowsAccessControlTaskFolderAccessRule WindowsAccessControlScheduledTaskAccessRule WindowsAccessControlCertificatePrivateKeyAccessRule

PSEditions

Desktop Core

Dependencies

This module has no dependencies.

Release Notes

## [0.3.0-preview0003] - 2026-10-08

### Added

- Add a repeatable descriptor-processing benchmark beside the existing NTFS
   read benchmark, covering rights rendering, removed-entry detection, DACL
   equivalence, and single-target dispatch. Both benchmarks now accept
   `-ModuleManifestPath` to measure one specific built artifact and record its
   SHA-256 with every run, so a before-and-after comparison names the exact
   module it measured
- Add a migration guide for `NTFSSecurity` users, whose module is deprecated in
   favor of this one. It maps every command that the NTFSSecurity 4.2.6 and
   5.0.0 manifests export to its replacement or to the decision that leaves it
   out, and it calls out the differences that change what a migrated script
   does: `Remove-NTFSAccessRule` matches exactly unless `-RemovalMode Rights`
   is given, the remove, clear, and owner commands prompt for confirmation, and
   a path longer than 260 characters needs PowerShell 7. The documentation
   index had pointed NTFSSecurity users at the `NTFSPermission` rename map,
   which never mentions NTFSSecurity
- Add live domain-lab cases for two safeguards that only unit tests covered.
   A Task Scheduler folder and task whose protected DACL has no Local System
   ACE accept an unrelated ACE, still refuse a Local System deny, and can have
   Local System restored. Around an SMB share DACL write, the description
   that the native write clears is restored and reported, a concurrent edit is
   kept with a warning, and a description that cannot be read before the
   write stops the command before anything is written
- Add live domain-lab cases for the SMB share and Active Directory paths that
   no test executed. An SDDL without a DACL is refused, `-PassThru` returns
   the stored descriptor, a rule copy that was not read from the share and a
   rule bound to another server are refused before anything is removed, and a
   share DACL write asks for confirmation and writes nothing when the caller
   cannot answer. A failed inheritance-source or schema-name lookup leaves the
   rules in the report with a non-terminating error, and an object deleted
   after target resolution is reported as not found

### Changed

- Speed up the shared descriptor paths that every object family reads through.
   Measured on PowerShell 7, repeated rights rendering is 69% faster,
   removed-entry detection over 256 access-control entries 66% faster, and
   single-target batch dispatch 18% faster; on Windows PowerShell 5.1
   removed-entry detection is 95% faster. Private-key DACL comparison over
   256 entries is 15% faster on PowerShell 7 when measured on its own and 4%
   faster on Windows PowerShell 5.1. The public command surface, output
   objects, descriptor semantics, and required privileges are unchanged, and
   filesystem owner reads are unchanged because their cost is the
   operating-system call rather than the module. See the
   [measurement report](docs/performance-refactor-2026-09-10.md) for the
   method, the artifact hashes, and the limits of each figure
- Keep exact access-control entry identity while comparing descriptors faster.
   Removed-entry detection for Active Directory still reports one entry per
   removed copy in its original order and still compares the complete binary
   entry, so the deny-removal warning raised before a directory write keeps
   its exact-match guarantee. Private-key DACL comparison keeps an ordered
   desired-state check separate from unordered post-write verification
- Read the RootDSE and the caller's effective access through the same
   directory search function as every other directory read, so unit tests
   cover their response checks without a domain controller. An object deleted
   between target resolution and the effective-access read of
   `Get-ADObjectCallerEffectiveAccess` now fails with an
   `ItemNotFoundException` naming it, like the family's other reads, instead
   of a `MethodInvocationException` from the LDAP call
   ([specification](specs/0018-active-directory-caller-effective-access.md#output-contract))

### Fixed

- Stop the domain-lab coverage pass from changing how member-server suites
   handle errors: arming coverage in a member session set
   `$ErrorActionPreference` to `Stop` for the rest of that session, so the
   SMB share, certificate private-key, Task Scheduler, and foreign-principal
   suites stopped at a non-terminating error only in the pass that collects
   coverage
   ([verification and traceability](specs/0005-verification-and-traceability.md#code-coverage-measurement))
- Describe both windows in which an SMB share DACL write can still lose a
   concurrent description edit. The usage page and the specification named
   only an edit that the native write clears; an edit that lands between the
   write's read-back and its restoration is overwritten by that restoration
   too, as the new live case observed
   ([specification](specs/0009-smb-share-and-active-directory-dacl-management.md#smb-share-contract))
- End a release that published without opening its changelog pull request.
   Sampler's `Create_ChangeLog_GitHub_PR` reports a refused pull request only
   as a line in the build log, so the v0.2.0 run pushed
   `updateChangelogAfterv0.2.0`, opened no pull request, and still concluded
   successfully, which is why the 0.2.0 section never reached `main`. The
   publish job now asks the GitHub API for the pull request of that branch
   after the task has run and stops the release when there is none, naming
   whether the branch itself was pushed
   ([workflow](.github/workflows/build.yml))
- Let `Get-ADObjectCallerEffectiveAccess` answer for a caller who cannot read
   the object's security descriptor: resolving its targets no longer requests
   `nTSecurityDescriptor`, which no output property uses. A command that does
   need the descriptor now fails with an `UnauthorizedAccessException` naming
   the likely missing read-control access instead of
   `Cannot index into a null array`
   ([specification](specs/0018-active-directory-caller-effective-access.md#output-contract))
- Keep an SMB share description that someone edits while a share DACL write
   is in flight: the write now reads the description immediately before the
   native call instead of reusing the value captured at target resolution,
   restores it only when the native write cleared it, and warns instead of
   overwriting any other change. A description that cannot be read before
   the write stops the command before anything is written, and one that
   cannot be checked or restored after the DACL was written is reported as a
   warning naming the earlier value instead of failing a change that is
   already live
   ([specification](specs/0009-smb-share-and-active-directory-dacl-management.md#smb-share-contract))
- Accept a Task Scheduler DACL write that restores Local System to a folder or
   task whose DACL has no Local System ACE; such repairs were refused even
   though every current Local System ACE was preserved. A current DACL that
   is missing or null is still refused, now with its own message
   ([specification](specs/0010-task-scheduler-dacl-management.md#persistence-and-safety))
- Stop the domain-lab acceptance runner from deleting directories it did not
   create: it marks the payload root, its `package` staging directory, and
   the module version directory it installs, refuses an existing one that is
   unmarked or contains a junction or symbolic link before deleting anything,
   rejects a payload root that is not a dedicated local directory on the
   management domain controller, and stops when a remote step does not
   confirm its directory
   ([lab guide](tests/Lab/README.md#payload-and-module-ownership))
- Return the already-verified CNG private-key descriptor bytes after a
   successful DACL write, avoiding a redundant provider read that could report
   failure after permissions had already changed
   ([regression](tests/Unit/Private/WindowsCngKeyMutation.Tests.ps1))
- Release the obsolete cleanup identity in the AD name-reuse acceptance test
   after successful GUID-based deletion, so suite cleanup does not abort on
   an already-absent object and leave subsequent fixtures behind
   ([fixture regression](tests/Unit/Lab/ADObjectReplicationFixtureSafety.Tests.ps1))
- Require selected PowerShell editions, explicit process exit status, and fresh
   evidence in domain-lab acceptance; report coverage-finalization failures as
   failed evidence and handle empty console output in Windows PowerShell 5.1
   ([audit](docs/test-gap-audit-2026-09-06.md))
- Preserve existing module installations when DSC test setup refuses to
   overwrite them, and restore the module search path even when cleanup fails
   ([fixture safety](tests/Unit/DSC/DscLcmFixtureSafety.Tests.ps1))

### Security

- Enforce Active Directory allowed-OU boundaries at real distinguished-name
   components so escaped commas cannot impersonate an ancestor separator
- Preserve the recorded Active Directory object GUID through restore's write
   path; direct descriptor writes can supply the same `ExpectedObjectGuid`
   guard to refuse a reused distinguished name
- Match the complete native ACE during exact removal, preserving neighboring
   conditional and object-specific ACEs with the same SID, mask, and flags
   ([audit regressions](docs/test-gap-audit-2026-09-06.md#confirmed-findings))