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