Edit‑NTFSItemSecurityDescriptor

SYNOPSIS

Edits selected NTFS descriptor sections in one bounded scope.

SYNTAX

Path (Default)

Edit-NTFSItemSecurityDescriptor [[-Path] <String[]>] [-Sections <AccessControlSections>]
 [-ScriptBlock] <ScriptBlock> [-ArgumentList <Object[]>] [-RequireUnchanged] [-ThrottleLimit <Int32>]
 [-PassThru] [-WhatIf] [-Confirm] [<CommonParameters>]

LiteralPath

Edit-NTFSItemSecurityDescriptor -LiteralPath <String[]> [-Sections <AccessControlSections>]
 [-ScriptBlock] <ScriptBlock> [-ArgumentList <Object[]>] [-RequireUnchanged] [-ThrottleLimit <Int32>]
 [-PassThru] [-WhatIf] [-Confirm] [<CommonParameters>]

DESCRIPTION

Reads one detached security descriptor per canonical target, invokes a caller script block with that descriptor and optional arguments, then persists the originally selected sections at most once. Callback output is suppressed; use PassThru for the edited descriptor. A callback error or unloaded-section expansion prevents persistence.

EXAMPLES

EXAMPLE 1

Edit-NTFSItemSecurityDescriptor -LiteralPath 'C:\Data' -Sections Access {
    param($descriptor)
    $descriptor | Add-NTFSAccessRule `
        -Account 'CONTOSO\Analysts' `
        -AccessRights Read | Out-Null
}

Reads and writes the DACL once while staging the rule in memory.

PARAMETERS

-ArgumentList

Supplies additional positional arguments after the descriptor.

Type: Object[]
Parameter Sets: (All)
Aliases:

Required: False
Position: Named
Default value: @()
Accept pipeline input: False
Accept wildcard characters: False

-LiteralPath

One or more filesystem paths used exactly as supplied.

Type: String[]
Parameter Sets: LiteralPath
Aliases: PSPath

Required: True
Position: Named
Default value: None
Accept pipeline input: True (ByPropertyName)
Accept wildcard characters: False

-PassThru

Returns the edited descriptor after persistence without rereading it.

Type: SwitchParameter
Parameter Sets: (All)
Aliases:

Required: False
Position: Named
Default value: False
Accept pipeline input: False
Accept wildcard characters: False

-Path

One or more filesystem paths. Wildcards are expanded by the FileSystem provider, and strings can be supplied through the pipeline.

Type: String[]
Parameter Sets: Path
Aliases: FullName

Required: False
Position: 1
Default value: .
Accept pipeline input: True (ByPropertyName, ByValue)
Accept wildcard characters: True

-RequireUnchanged

Rejects the write when the selected sections changed between this scope's read and its persist step. The default is last-writer-wins.

Type: SwitchParameter
Parameter Sets: (All)
Aliases:

Required: False
Position: Named
Default value: False
Accept pipeline input: False
Accept wildcard characters: False

-ScriptBlock

Receives the detached descriptor as its first positional argument. Mutations made through descriptor-aware commands remain in memory until this scope persists them.

Type: ScriptBlock
Parameter Sets: (All)
Aliases:

Required: True
Position: 2
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-Sections

Selects the descriptor sections loaded and eligible for persistence.

Type: AccessControlSections
Parameter Sets: (All)
Aliases:
Accepted values: None, Audit, Access, Owner, Group, All

Required: False
Position: Named
Default value: Access
Accept pipeline input: False
Accept wildcard characters: False

-ThrottleLimit

Accepted for target-array command consistency. Caller script blocks are intentionally dispatched sequentially to preserve runspace affinity; values greater than one do not parallelize this command.

Type: Int32
Parameter Sets: (All)
Aliases:

Required: False
Position: Named
Default value: [Math]::Max(1, [Math]::Min(8, [Environment]::ProcessorCount))
Accept pipeline input: False
Accept wildcard characters: False

-Confirm

Prompts you for confirmation before running the cmdlet.

Type: SwitchParameter
Parameter Sets: (All)
Aliases: cf

Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-WhatIf

Shows what would happen if the cmdlet runs. The cmdlet is not run.

Type: SwitchParameter
Parameter Sets: (All)
Aliases: wi

Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

CommonParameters

This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters.

INPUTS

System.String

System.IO.FileSystemInfo

OUTPUTS

None

WindowsAccessControl.SecurityDescriptor

NOTES

RELATED LINKS