inital commit win_acl

lib/ansible/modules/extras/windows/win_acl.ps1

@@ -0,0 +1,146 @@
+#!powershell
+# This file is part of Ansible
+#
+# Copyright 2014, Phil Schwartz <schwartzmx@gmail.com>
+#
+# Ansible is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# Ansible is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with Ansible.  If not, see <http://www.gnu.org/licenses/>.
+
+# WANT_JSON
+# POWERSHELL_COMMON
+
+# win_acl module (File/Resources Permission Additions/Removal)
+$params = Parse-Args $args;
+
+$result = New-Object psobject @{
+    win_acl = New-Object psobject
+    changed = $false
+}
+
+If ($params.src) {
+    $src = $params.src.toString()
+
+    If (-Not (Test-Path -Path $src -PathType Leaf -Or Test-Path -Path $src -PathType Container)) {
+        Fail-Json $result "$src is not a valid file or directory on the host"
+    }
+}
+Else {
+    Fail-Json $result "missing required argument: src"
+}
+
+If ($params.user) {
+    $user = $params.user.toString()
+
+    # Test that the user/group exists on the local machine
+    $localComputer = [ADSI]("WinNT://"+[System.Net.Dns]::GetHostName())
+    $list = ($localComputer.psbase.children | Where-Object { (($_.psBase.schemaClassName -eq "User") -Or ($_.psBase.schemaClassName -eq "Group"))} | Select-Object -expand Name)
+    If (-Not ($list -contains "$user")) {
+        Fail-Json $result "$user is not a valid user or group on the host machine"
+    }
+}
+Else {
+    Fail-Json $result "missing required argument: user.  specify the user or group to apply permission changes."
+}
+
+If ($params.type -eq "allow") {
+    $type = $true
+}
+ElseIf ($params.type -eq "deny") {
+    $type = $false
+}
+Else {
+    Fail-Json $result "missing required argument: type. specify whether to allow or deny the specified rights."
+}
+
+If ($params.inherit) {
+    # If it's a file then no flags can be set or an exception will be thrown
+    If (Test-Path -Path $src -PathType Leaf) {
+        $inherit = "None"
+    }
+    Else {
+        $inherit = $params.inherit.toString()
+    }
+}
+Else {
+    # If it's a file then no flags can be set or an exception will be thrown
+    If (Test-Path -Path $src -PathType Leaf) {
+        $inherit = "None"
+    }
+    Else {
+        $inherit = "ContainerInherit, ObjectInherit"
+    }
+}
+
+If ($params.propagation) {
+    $propagation = $params.propagation.toString()
+}
+Else {
+    $propagation = "None"
+}
+
+If ($params.rights) {
+    $rights = $params.rights.toString()
+}
+Else {
+    Fail-Json $result "missing required argument: rights"
+}
+
+If ($params.state -eq "absent") {
+    $state = "remove"
+}
+Else {
+    $state = "add"
+}
+
+Try {
+    $colRights = [System.Security.AccessControl.FileSystemRights]$rights
+    $InheritanceFlag = [System.Security.AccessControl.InheritanceFlags]$inherit
+    $PropagationFlag = [System.Security.AccessControl.PropagationFlags]$propagation
+
+    If ($type) {
+        $objType =[System.Security.AccessControl.AccessControlType]::Allow
+    }
+    Else {
+        $objType =[System.Security.AccessControl.AccessControlType]::Deny
+    }
+
+    $objUser = New-Object System.Security.Principal.NTAccount($user)
+    $objACE = New-Object System.Security.AccessControl.FileSystemAccessRule ($objUser, $colRights, $InheritanceFlag, $PropagationFlag, $objType)
+    $objACL = Get-ACL $src
+
+    If ($state -eq "add") {
+        Try {
+            $objACL.AddAccessRule($objACE)
+        }
+        Catch {
+            Fail-Json $result "an exception occured when adding the specified rule.  it may already exist."
+        }
+    }
+    Else {
+        Try {
+            $objACL.RemoveAccessRule($objACE)
+        }
+        Catch {
+            Fail-Json $result "an exception occured when removing the specified rule.  it may not exist."
+        }
+    }
+
+    Set-ACL $src $objACL
+
+    $result.changed = $true
+}
+Catch {
+    Fail-Json $result "an error occured when attempting to $state $rights permission(s) on $src for $user"
+}
+
+Exit-Json $result

lib/ansible/modules/extras/windows/win_acl.py

@@ -0,0 +1,147 @@
+#!/usr/bin/python
+# -*- coding: utf-8 -*-
+
+# (c) 2014, Phil Schwartz <schwartzmx@gmail.com>
+#
+# This file is part of Ansible
+#
+# Ansible is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# Ansible is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with Ansible.  If not, see <http://www.gnu.org/licenses/>.
+
+# this is a windows documentation stub.  actual code lives in the .ps1
+# file of the same name
+
+DOCUMENTATION = '''
+---
+module: win_acl
+version_added: ""
+short_description: Set file/directory permissions for a system user or group.
+description:
+     - Add or remove rights/permissions for a given user or group for the specified src file or folder.
+options:
+  src:
+    description:
+      - File or Directory
+    required: yes
+    default: none
+    aliases: []
+  user:
+    description:
+      - User or Group to add specified rights to act on src file/folder
+    required: yes
+    default: none
+    aliases: []
+  state:
+    description:
+      - Specify whether to add (present) or remove (absent) the specified access rule
+    required: no
+    choices:
+      - present
+      - absent
+    default: present
+    aliases: []
+  type:
+    description:
+      - Specify whether to allow or deny the rights specified
+    required: yes
+    choices:
+      - allow
+      - deny
+    default: none
+    aliases: []
+  rights:
+    description:
+      - The rights/permissions that are to be allowed/denyed for the specified user or group for the given src file or directory.  Can be entered as a comma separated list (Ex. "Modify, Delete, ExecuteFile").  For more information on the choices see MSDN FileSystemRights Enumeration.
+    required: yes
+    choices:
+      - AppendData
+      - ChangePermissions
+      - Delete
+      - DeleteSubdirectoriesAndFiles
+      - ExecuteFile
+      - FullControl
+      - ListDirectory
+      - Modify
+      - Read
+      - ReadAndExecute
+      - ReadAttributes
+      - ReadData
+      - ReadExtendedAttributes
+      - ReadPermissions
+      - Synchronize
+      - TakeOwnership
+      - Traverse
+      - Write
+      - WriteAttributes
+      - WriteData
+      - WriteExtendedAttributes
+    default: none
+    aliases: []
+  inherit:
+    description:
+      - Inherit flags on the ACL rules.  Can be specified as a comma separated list (Ex. "ContainerInherit, ObjectInherit").  For more information on the choices see MSDN InheritanceFlags Enumeration.
+    required: no
+    choices:
+      - ContainerInherit
+      - ObjectInherit
+      - None
+    default: For Leaf File: None; For Directory: ContainerInherit, ObjectInherit;
+    aliases: []
+  propagation:
+    description:
+      - Propagation flag on the ACL rules.  For more information on the choices see MSDN PropagationFlags Enumeration.
+    required: no
+    choices:
+      - None
+      - NoPropagateInherit
+      - InheritOnly
+    default: "None"
+    aliases: []
+author: Phil Schwartz
+'''
+
+EXAMPLES = '''
+# Restrict write,execute access to User Fed-Phil
+$ ansible -i hosts -m win_acl -a "user=Fed-Phil src=C:\Important\Executable.exe type=deny rights='ExecuteFile,Write'" all
+
+# Playbook example
+# Add access rule to allow IIS_IUSRS FullControl to MySite
+---
+- name: Add IIS_IUSRS allow rights
+  win_acl:
+    src: 'C:\inetpub\wwwroot\MySite'
+    user: 'IIS_IUSRS'
+    rights: 'FullControl'
+    type: 'allow'
+    state: 'present'
+    inherit: 'ContainerInherit, ObjectInherit'
+    propagation: 'None'
+
+# Remove previously added rule for IIS_IUSRS
+- name: Remove FullControl AccessRule for IIS_IUSRS
+    src: 'C:\inetpub\wwwroot\MySite'
+    user: 'IIS_IUSRS'
+    rights: 'FullControl'
+    type: 'allow'
+    state: 'absent'
+    inherit: 'ContainerInherit, ObjectInherit'
+    propagation: 'None'
+
+# Deny Intern
+- name: Deny Deny
+    src: 'C:\Administrator\Documents'
+    user: 'Intern'
+    rights: 'Read,Write,Modify,FullControl,Delete'
+    type: 'deny'
+    state: 'present'
+'''