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