1#!/usr/local/bin/python3.8 2# -*- coding: utf-8 -*- 3 4# Copyright: (c) 2017, Noah Sparks <nsparks@outlook.com> 5# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt) 6 7DOCUMENTATION = r''' 8--- 9module: win_audit_rule 10short_description: Adds an audit rule to files, folders, or registry keys 11description: 12 - Used to apply audit rules to files, folders or registry keys. 13 - Once applied, it will begin recording the user who performed the operation defined into the Security 14 Log in the Event viewer. 15 - The behavior is designed to ignore inherited rules since those cannot be adjusted without first disabling 16 the inheritance behavior. It will still print inherited rules in the output though for debugging purposes. 17options: 18 path: 19 description: 20 - Path to the file, folder, or registry key. 21 - Registry paths should be in Powershell format, beginning with an abbreviation for the root 22 such as, C(HKLM:\Software). 23 type: path 24 required: yes 25 aliases: [ dest, destination ] 26 user: 27 description: 28 - The user or group to adjust rules for. 29 type: str 30 required: yes 31 rights: 32 description: 33 - Comma separated list of the rights desired. Only required for adding a rule. 34 - If I(path) is a file or directory, rights can be any right under MSDN 35 FileSystemRights U(https://msdn.microsoft.com/en-us/library/system.security.accesscontrol.filesystemrights.aspx). 36 - If I(path) is a registry key, rights can be any right under MSDN 37 RegistryRights U(https://msdn.microsoft.com/en-us/library/system.security.accesscontrol.registryrights.aspx). 38 type: list 39 required: yes 40 inheritance_flags: 41 description: 42 - Defines what objects inside of a folder or registry key will inherit the settings. 43 - If you are setting a rule on a file, this value has to be changed to C(none). 44 - For more information on the choices see MSDN PropagationFlags enumeration 45 at U(https://msdn.microsoft.com/en-us/library/system.security.accesscontrol.inheritanceflags.aspx). 46 type: list 47 choices: [ ContainerInherit, ObjectInherit ] 48 default: ContainerInherit,ObjectInherit 49 propagation_flags: 50 description: 51 - Propagation flag on the audit rules. 52 - This value is ignored when the path type is a file. 53 - For more information on the choices see MSDN PropagationFlags enumeration 54 at U(https://msdn.microsoft.com/en-us/library/system.security.accesscontrol.propagationflags.aspx). 55 choices: [ None, InherityOnly, NoPropagateInherit ] 56 default: "None" 57 audit_flags: 58 description: 59 - Defines whether to log on failure, success, or both. 60 - To log both define as comma separated list "Success, Failure". 61 type: list 62 required: yes 63 choices: [ Failure, Success ] 64 state: 65 description: 66 - Whether the rule should be C(present) or C(absent). 67 - For absent, only I(path), I(user), and I(state) are required. 68 - Specifying C(absent) will remove all rules matching the defined I(user). 69 type: str 70 choices: [ absent, present ] 71 default: present 72seealso: 73- module: community.windows.win_audit_policy_system 74author: 75 - Noah Sparks (@nwsparks) 76''' 77 78EXAMPLES = r''' 79- name: Add filesystem audit rule for a folder 80 community.windows.win_audit_rule: 81 path: C:\inetpub\wwwroot\website 82 user: BUILTIN\Users 83 rights: write,delete,changepermissions 84 audit_flags: success,failure 85 inheritance_flags: ContainerInherit,ObjectInherit 86 87- name: Add filesystem audit rule for a file 88 community.windows.win_audit_rule: 89 path: C:\inetpub\wwwroot\website\web.config 90 user: BUILTIN\Users 91 rights: write,delete,changepermissions 92 audit_flags: success,failure 93 inheritance_flags: None 94 95- name: Add registry audit rule 96 community.windows.win_audit_rule: 97 path: HKLM:\software 98 user: BUILTIN\Users 99 rights: delete 100 audit_flags: 'success' 101 102- name: Remove filesystem audit rule 103 community.windows.win_audit_rule: 104 path: C:\inetpub\wwwroot\website 105 user: BUILTIN\Users 106 state: absent 107 108- name: Remove registry audit rule 109 community.windows.win_audit_rule: 110 path: HKLM:\software 111 user: BUILTIN\Users 112 state: absent 113''' 114 115RETURN = r''' 116current_audit_rules: 117 description: 118 - The current rules on the defined I(path) 119 - Will return "No audit rules defined on I(path)" 120 returned: always 121 type: dict 122 sample: | 123 { 124 "audit_flags": "Success", 125 "user": "Everyone", 126 "inheritance_flags": "False", 127 "is_inherited": "False", 128 "propagation_flags": "None", 129 "rights": "Delete" 130 } 131path_type: 132 description: 133 - The type of I(path) being targetted. 134 - Will be one of file, directory, registry. 135 returned: always 136 type: str 137''' 138