The cNtfsAccessControl DSC resource module.
Switch branches/tags
Nothing to show
Clone or download
Permalink
Failed to load latest commit information.
DSCResources Version 1.4.0 Oct 1, 2018
Examples Samples updated May 4, 2016
Tests Version 1.4.0 Oct 1, 2018
.gitignore Preparation for a future release Feb 3, 2016
LICENSE Version 1.4.0 Oct 1, 2018
README.md Updated README.md Oct 1, 2018
appveyor.yml Updated appveyor.yml Oct 2, 2018
cNtfsAccessControl.psd1 Version 1.4.0 Oct 1, 2018

README.md

Build status

cNtfsAccessControl

The cNtfsAccessControl module contains DSC resources for NTFS access control management.

You can also download this module from the PowerShell Gallery.

Resources

cNtfsPermissionEntry

The cNtfsPermissionEntry DSC resource provides a mechanism to manage NTFS permissions.

  • Ensure: Indicates if the principal has explicitly assigned NTFS permissions on the target path. Set this property to Present (the default value) to ensure they exactly match what is provided through the AccessControlInformation property. If the AccessControlInformation property is not specified, the default permission entry is used as the reference permission entry. If this property is set to Absent and the AccessControlInformation property is not specified, all explicit permissions associated with the specified principal are removed.
  • Path: Indicates the path to the target item.
  • Principal: Indicates the identity of the principal. Valid formats are:
  • AccessControlInformation: Indicates the access control information in the form of an array of instances of the cNtfsAccessControlInformation CIM class. Its properties are as follows:
    • AccessControlType: Indicates whether to Allow or Deny access to the target item. The default value is Allow.
    • FileSystemRights: Indicates the access rights to be granted to the principal. Specify one or more values from the System.Security.AccessControl.FileSystemRights enumeration type. Multiple values can be specified by using an array of strings or a single comma-separated string. The default value is ReadAndExecute.
    • Inheritance: Indicates the inheritance type of the permission entry. This property is only applicable to directories. Valid values are:
      • None
      • ThisFolderOnly
      • ThisFolderSubfoldersAndFiles (the default value)
      • ThisFolderAndSubfolders
      • ThisFolderAndFiles
      • SubfoldersAndFilesOnly
      • SubfoldersOnly
      • FilesOnly
    • NoPropagateInherit: Indicates whether the permission entry is not propagated to child objects. This property is only applicable to directories. Set this property to $true to ensure inheritance is limited only to those sub-objects that are immediately subordinate to the target item. The default value is $false.

cNtfsPermissionsInheritance

The cNtfsPermissionsInheritance DSC resource provides a mechanism to manage NTFS permissions inheritance.

  • Path: Indicates the path to the target item.
  • Enabled: Indicates whether NTFS permissions inheritance is enabled. Set this property to $false to ensure it is disabled. The default value is $true.
  • PreserveInherited: Indicates whether to preserve inherited permissions. Set this property to $true to convert inherited permissions into explicit permissions. The default value is $false. Note: This property is only valid when the Enabled property is set to $false.

Versions

1.4.0 (October 1, 2018)

  • Added new resources:
    • cNtfsAuditEntry
    • cNtfsAuditInheritance

Special thanks to Scott Matthews (@mrhockeymonkey)!

1.3.1 (January 16, 2018)

  • Bug fixes.

1.3.0 (May 04, 2016)

  • Changed the behavior of the cNtfsPermissionEntry DSC resource with the Ensure property set to Absent. Added an ability to remove specific permission entries.
  • General improvements.

1.2.0 (February 19, 2016)

  • The ItemType property of the cNtfsPermissionEntry DSC resource was deprecated.
  • The cNtfsPermissionsInheritance DSC resource was added.
  • Unit and integration tests were added.
  • Bug fixes and general improvements.

1.1.1 (October 15, 2015)

  • Minor update.

1.1.0 (September 30, 2015)

  • The PermissionEntry property was renamed to AccessControlInformation.

1.0.0 (September 29, 2015)

  • Initial release with the following DSC resources:
    • cNtfsPermissionEntry

Examples

Assign NTFS permissions

This example shows how to use the cNtfsPermissionEntry DSC resource to assign NTFS permissions.

Configuration Sample_cNtfsPermissionEntry
{
    param
    (
        [Parameter(Mandatory = $false)]
        [ValidateNotNullOrEmpty()]
        [String]
        $Path = (Join-Path -Path ([System.IO.Path]::GetTempPath()) -ChildPath ([Guid]::NewGuid().Guid))
    )

    Import-DscResource -ModuleName cNtfsAccessControl
    Import-DscResource -ModuleName PSDesiredStateConfiguration

    File TestDirectory
    {
        Ensure = 'Present'
        DestinationPath = $Path
        Type = 'Directory'
    }

    # Ensure that a single permission entry is assigned to the local 'Users' group.
    cNtfsPermissionEntry PermissionSet1
    {
        Ensure = 'Present'
        Path = $Path
        Principal = 'BUILTIN\Users'
        AccessControlInformation = @(
            cNtfsAccessControlInformation
            {
                AccessControlType = 'Allow'
                FileSystemRights = 'ReadAndExecute'
                Inheritance = 'ThisFolderSubfoldersAndFiles'
                NoPropagateInherit = $false
            }
        )
        DependsOn = '[File]TestDirectory'
    }

    # Ensure that multiple permission entries are assigned to the local 'Administrators' group.
    cNtfsPermissionEntry PermissionSet2
    {
        Ensure = 'Present'
        Path = $Path
        Principal = 'BUILTIN\Administrators'
        AccessControlInformation = @(
            cNtfsAccessControlInformation
            {
                AccessControlType = 'Allow'
                FileSystemRights = 'Modify'
                Inheritance = 'ThisFolderOnly'
                NoPropagateInherit = $false
            }
            cNtfsAccessControlInformation
            {
                AccessControlType = 'Allow'
                FileSystemRights = 'ReadAndExecute'
                Inheritance = 'ThisFolderSubfoldersAndFiles'
                NoPropagateInherit = $false
            }
            cNtfsAccessControlInformation
            {
                AccessControlType = 'Allow'
                FileSystemRights = 'AppendData', 'CreateFiles'
                Inheritance = 'SubfoldersAndFilesOnly'
                NoPropagateInherit = $false
            }
        )
        DependsOn = '[File]TestDirectory'
    }

    # Ensure that all explicit permissions associated with the 'Authenticated Users' group are removed.
    cNtfsPermissionEntry PermissionSet3
    {
        Ensure = 'Absent'
        Path = $Path
        Principal = 'NT AUTHORITY\Authenticated Users'
        DependsOn = '[File]TestDirectory'
    }
}

$OutputPath = Join-Path -Path ([System.IO.Path]::GetTempPath()) -ChildPath 'Sample_cNtfsPermissionEntry'
Sample_cNtfsPermissionEntry -OutputPath $OutputPath
Start-DscConfiguration -Path $OutputPath -Force -Verbose -Wait

Disable NTFS permissions inheritance

This example shows how to use the cNtfsPermissionsInheritance DSC resource to disable NTFS permissions inheritance.

Configuration Sample_cNtfsPermissionsInheritance
{
    param
    (
        [Parameter(Mandatory = $false)]
        [ValidateNotNullOrEmpty()]
        [String]
        $Path = (Join-Path -Path ([System.IO.Path]::GetTempPath()) -ChildPath ([Guid]::NewGuid().Guid))
    )

    Import-DscResource -ModuleName cNtfsAccessControl
    Import-DscResource -ModuleName PSDesiredStateConfiguration

    File TestDirectory
    {
        Ensure = 'Present'
        DestinationPath = $Path
        Type = 'Directory'
    }

    # Disable NTFS permissions inheritance.
    cNtfsPermissionsInheritance DisableInheritance
    {
        Path = $Path
        Enabled = $false
        PreserveInherited = $true
        DependsOn = '[File]TestDirectory'
    }
}

$OutputPath = Join-Path -Path ([System.IO.Path]::GetTempPath()) -ChildPath 'Sample_cNtfsPermissionsInheritance'
Sample_cNtfsPermissionsInheritance -OutputPath $OutputPath
Start-DscConfiguration -Path $OutputPath -Force -Verbose -Wait