Debian Codegraph @

ansible_collections/netapp/ontap/plugins/modules/na_ontap_vserver_audit.py

raw
1 #!/usr/bin/python
2
3 # (c) 2023-2026, NetApp, Inc
4 # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
5
6 from __future__ import absolute_import, division, print_function
7 __metaclass__ = type
8
9 DOCUMENTATION = """
10 module: na_ontap_vserver_audit
11 short_description: NetApp Ontap - create, delete or modify vserver audit configuration.
12 extends_documentation_fragment:
13 - netapp.ontap.netapp.na_ontap_rest
14 version_added: '22.3.0'
15 author: NetApp Ansible Team (@carchi8py) <[email protected]>
16 description:
17 - Create, delete or modify vserver audit configuration.
18 options:
19 state:
20 description:
21 - Whether the specified vserver audit configuration should exist or not.
22 choices: ['present', 'absent']
23 default: present
24 type: str
25 vserver:
26 description:
27 - Specifies name of the Vserver.
28 required: true
29 type: str
30 log_path:
31 description:
32 - The audit log destination path where consolidated audit logs are stored.
33 type: str
34 guarantee:
35 description:
36 - Indicates whether there is a strict Guarantee of Auditing.
37 - This option requires ONTAP 9.10.1 or later.
38 type: bool
39 enabled:
40 description:
41 - Specifies whether or not auditing is enabled on the SVM.
42 type: bool
43 events:
44 description:
45 - Specifies events for which auditing is enabled on the SVM.
46 type: dict
47 suboptions:
48 authorization_policy:
49 description:
50 - Authorization policy change events.
51 type: bool
52 cap_staging:
53 description:
54 - Central access policy staging events.
55 type: bool
56 cifs_logon_logoff:
57 description:
58 - CIFS logon and logoff events.
59 type: bool
60 file_operations:
61 description:
62 - File operation events.
63 type: bool
64 file_share:
65 description:
66 - File share category events.
67 type: bool
68 security_group:
69 description:
70 - Local security group management events.
71 type: bool
72 user_account:
73 description:
74 - Local user account management events.
75 type: bool
76 log:
77 description:
78 - Specifies the configuration options for audit log files.
79 type: dict
80 suboptions:
81 format:
82 description:
83 - This option describes the format in which the logs are generated by consolidation process.
84 Possible values are,
85 - xml - Data ONTAP-specific XML log format
86 - evtx - Microsoft Windows EVTX log format
87 choices: ['xml', 'evtx']
88 type: str
89 retention:
90 description:
91 - This option describes the count and time to retain the audit log file.
92 type: dict
93 suboptions:
94 count:
95 description:
96 - Determines how many audit log files to retain before rotating the oldest log file out.
97 - This is mutually exclusive with duration.
98 type: int
99 duration:
100 description:
101 - Specifies an ISO-8601 format date and time to retain the audit log file.
102 - The audit log files are deleted once they reach the specified date/time.
103 - This is mutually exclusive with count.
104 type: str
105 rotation:
106 description:
107 - Audit event log files are rotated when they reach a configured threshold log size or are on a configured schedule.
108 - When an event log file is rotated, the scheduled consolidation task first renames the active converted file to a time-stamped archive file,
109 and then creates a new active converted event log file.
110 type: dict
111 suboptions:
112 size:
113 description:
114 - Rotates logs based on log size in bytes.
115 - Default value is 104857600.
116 type: int
117 schedule:
118 description:
119 - Rotates the audit logs based on a schedule by using the time-based rotation parameters in any combination.
120 - The rotation schedule is calculated by using all the time-related values.
121 type: dict
122 version_added: '22.11.0'
123 suboptions:
124 days:
125 description:
126 - Specifies the day of the month schedule to rotate audit log. Specify -1 to rotate the audit logs all days of a month.
127 type: list
128 elements: int
129 hours:
130 description:
131 - Specifies the hourly schedule to rotate audit log. Specify -1 to rotate the audit logs every hour.
132 type: list
133 elements: int
134 minutes:
135 description:
136 - Specifies the minutes schedule to rotate the audit log.
137 type: list
138 elements: int
139 months:
140 description:
141 - Specifies the months schedule to rotate audit log. Specify -1 to rotate the audit logs every month.
142 type: list
143 elements: int
144 weekdays:
145 description:
146 - Specifies the weekdays schedule to rotate audit log. Specify -1 to rotate the audit logs every day.
147 type: list
148 elements: int
149
150 notes:
151 - This module supports REST only.
152 - At least one event should be enabled.
153 - No other fields can be specified when enabled is specified for modify.
154 """
155
156 EXAMPLES = """
157 - name: Create vserver audit configuration
158 netapp.ontap.na_ontap_vserver_audit:
159 state: present
160 vserver: ansible
161 enabled: true
162 events:
163 authorization_policy: false
164 cap_staging: false
165 cifs_logon_logoff: true
166 file_operations: true
167 file_share: false
168 security_group: false
169 user_account: false
170 log_path: "/"
171 log:
172 format: xml
173 retention:
174 count: 4
175 rotation:
176 size: "1048576"
177 guarantee: false
178 hostname: "{{ netapp_hostname }}"
179 username: "{{ netapp_username }}"
180 password: "{{ netapp_password }}"
181
182 - name: Modify vserver audit configuration
183 netapp.ontap.na_ontap_vserver_audit:
184 state: present
185 vserver: ansible
186 enabled: true
187 events:
188 authorization_policy: true
189 cap_staging: true
190 cifs_logon_logoff: true
191 file_operations: true
192 file_share: true
193 security_group: true
194 user_account: true
195 log_path: "/tmp"
196 log:
197 format: evtx
198 retention:
199 count: 5
200 rotation:
201 size: "104857600"
202 guarantee: true
203 hostname: "{{ netapp_hostname }}"
204 username: "{{ netapp_username }}"
205 password: "{{ netapp_password }}"
206
207 - name: Delete vserver audit configuration
208 netapp.ontap.na_ontap_vserver_audit:
209 state: absent
210 vserver: ansible
211 hostname: "{{ netapp_hostname }}"
212 username: "{{ netapp_username }}"
213 password: "{{ netapp_password }}"
214
215 # The audit logs are rotated in January and March on Monday, Wednesday, and Friday,
216 # at 6:15, 6:30, 6:45, 12:15, 12:30, 12:45, 18:15, 18:30, and 18:45
217 # The last 6 audit logs are retained
218 - name: Create vserver audit configuration
219 netapp.ontap.na_ontap_vserver_audit:
220 state: present
221 vserver: ansible
222 enabled: true
223 events:
224 authorization_policy: false
225 cap_staging: false
226 cifs_logon_logoff: true
227 file_operations: true
228 file_share: false
229 security_group: false
230 user_account: false
231 log_path: "/"
232 log:
233 format: xml
234 retention:
235 count: 6
236 rotation:
237 schedule:
238 hours: [6, 12, 18]
239 minutes: [15, 30, 45]
240 months: [1, 3]
241 weekdays: [1, 3, 5]
242 guarantee: false
243 hostname: "{{ netapp_hostname }}"
244 username: "{{ netapp_username }}"
245 password: "{{ netapp_password }}"
246
247 # The audit logs are rotated monthly, all days of the week, at 12:30
248 - name: Modify vserver audit configuration
249 netapp.ontap.na_ontap_vserver_audit:
250 state: present
251 vserver: ansible
252 enabled: true
253 events:
254 authorization_policy: false
255 cap_staging: false
256 cifs_logon_logoff: true
257 file_operations: true
258 file_share: false
259 security_group: false
260 user_account: false
261 log_path: "/"
262 log:
263 format: xml
264 rotation:
265 schedule:
266 hours: [12]
267 minutes: [30]
268 months: [-1]
269 weekdays: [-1]
270 guarantee: false
271 hostname: "{{ netapp_hostname }}"
272 username: "{{ netapp_username }}"
273 password: "{{ netapp_password }}"
274 """
275
276 RETURN = """
277 """
278
279 import time
280 from ansible.module_utils.basic import AnsibleModule
281 import ansible_collections.netapp.ontap.plugins.module_utils.netapp as netapp_utils
282 from ansible_collections.netapp.ontap.plugins.module_utils.netapp_module import NetAppModule
283 from ansible_collections.netapp.ontap.plugins.module_utils import rest_generic
284
285
286 class NetAppONTAPVserverAudit:
287 """
288 Class with vserver audit configuration methods
289 """
290
291 def __init__(self):
292
293 self.argument_spec = netapp_utils.na_ontap_rest_only_spec()
294 self.argument_spec.update(dict(
295 state=dict(required=False, type='str', choices=['present', 'absent'], default='present'),
296 vserver=dict(required=True, type='str'),
297 enabled=dict(required=False, type='bool'),
298 guarantee=dict(required=False, type='bool'),
299 log_path=dict(required=False, type='str'),
300 log=dict(type='dict', options=dict(
301 format=dict(type='str', choices=['xml', 'evtx']),
302 retention=dict(type='dict', options=dict(
303 count=dict(type='int'),
304 duration=dict(type='str'),
305 )),
306 rotation=dict(type='dict', options=dict(
307 size=dict(type='int'),
308 schedule=dict(type='dict', options=dict(
309 days=dict(type='list', elements='int'),
310 hours=dict(type='list', elements='int'),
311 minutes=dict(type='list', elements='int'),
312 months=dict(type='list', elements='int'),
313 weekdays=dict(type='list', elements='int'),
314 )),
315 )),
316 )),
317 events=dict(type='dict', options=dict(
318 authorization_policy=dict(type='bool'),
319 cap_staging=dict(type='bool'),
320 cifs_logon_logoff=dict(type='bool'),
321 file_operations=dict(type='bool'),
322 file_share=dict(type='bool'),
323 security_group=dict(type='bool'),
324 user_account=dict(type='bool'),
325 ))
326 ))
327
328 self.module = AnsibleModule(
329 argument_spec=self.argument_spec,
330 supports_check_mode=True
331 )
332
333 # set up variables
334 self.na_helper = NetAppModule()
335 self.parameters = self.na_helper.filter_out_none_entries(self.na_helper.set_parameters(self.module.params))
336
337 self.rest_api = netapp_utils.OntapRestAPI(self.module)
338 self.rest_api.fail_if_not_rest_minimum_version('na_ontap_vserver_audit', 9, 6)
339 partially_supported_rest_properties = [['guarantee', (9, 10, 1)]]
340 self.use_rest = self.rest_api.is_rest_supported_properties(self.parameters, None, partially_supported_rest_properties)
341 self.svm_uuid = None
342 if 'events' in self.parameters and self.parameters['state'] == 'present':
343 if all(self.parameters['events'][value] is False for value in self.parameters['events']) is True:
344 self.module.fail_json(msg="Error: At least one event should be enabled")
345
346 def get_vserver_audit_configuration_rest(self):
347 """
348 Retrieves audit configurations.
349 """
350 api = "protocols/audit"
351 query = {
352 'svm.name': self.parameters['vserver'],
353 'fields': 'svm.uuid,enabled,events,log,log_path,'
354 }
355 if self.rest_api.meets_rest_minimum_version(self.use_rest, 9, 10, 1):
356 query['fields'] += 'guarantee,'
357 record, error = rest_generic.get_one_record(self.rest_api, api, query)
358 if error:
359 self.module.fail_json(msg="Error on fetching vserver audit configuration: %s" % error)
360 if record:
361 self.svm_uuid = self.na_helper.safe_get(record, ['svm', 'uuid'])
362 return {
363 'enabled': self.na_helper.safe_get(record, ['enabled']),
364 'events': self.na_helper.safe_get(record, ['events']),
365 'log': self.na_helper.safe_get(record, ['log']),
366 'log_path': self.na_helper.safe_get(record, ['log_path']),
367 'guarantee': record.get('guarantee', False),
368 }
369 return record
370
371 def schedule_rotation_key_value(self, key):
372 value = self.na_helper.safe_get(self.parameters, ['log', 'rotation', 'schedule', key])
373 return [] if -1 in value else value
374
375 def create_vserver_audit_config_body_rest(self):
376 """
377 Vserver audit config body for create and modify with rest API.
378 """
379 body = {}
380 if 'events' in self.parameters:
381 body['events'] = self.parameters['events']
382 if 'guarantee' in self.parameters:
383 body['guarantee'] = self.parameters['guarantee']
384 if self.na_helper.safe_get(self.parameters, ['log', 'retention', 'count']):
385 body['log.retention.count'] = self.parameters['log']['retention']['count']
386 if self.na_helper.safe_get(self.parameters, ['log', 'retention', 'duration']):
387 body['log.retention.duration'] = self.parameters['log']['retention']['duration']
388 if self.na_helper.safe_get(self.parameters, ['log', 'rotation']):
389 if self.na_helper.safe_get(self.parameters, ['log', 'rotation', 'size']):
390 body['log.rotation.size'] = self.parameters['log']['rotation']['size']
391 else:
392 for schedule_rotation_key in ['days', 'hours', 'minutes', 'months', 'weekdays']:
393 if self.na_helper.safe_get(self.parameters, ['log', 'rotation', 'schedule', schedule_rotation_key]) is not None:
394 key = 'log.rotation.schedule.' + schedule_rotation_key
395 body[key] = self.schedule_rotation_key_value(schedule_rotation_key)
396 if self.na_helper.safe_get(self.parameters, ['log', 'format']):
397 body['log.format'] = self.parameters['log']['format']
398 if 'log_path' in self.parameters:
399 body['log_path'] = self.parameters['log_path']
400 return body
401
402 def create_vserver_audit_configuration_rest(self):
403 """
404 Creates an audit configuration.
405 """
406 api = "protocols/audit"
407 body = self.create_vserver_audit_config_body_rest()
408 if 'vserver' in self.parameters:
409 body['svm.name'] = self.parameters.get('vserver')
410 if 'enabled' in self.parameters:
411 body['enabled'] = self.parameters['enabled']
412 record, error = rest_generic.post_async(self.rest_api, api, body)
413 if error:
414 self.module.fail_json(msg="Error on creating vserver audit configuration: %s" % error)
415
416 def delete_vserver_audit_configuration_rest(self, current):
417 """
418 Deletes an audit configuration.
419 """
420 api = "protocols/audit/%s" % self.svm_uuid
421 if current['enabled'] is True:
422 modify = {'enabled': False}
423 self.modify_vserver_audit_configuration_rest(modify)
424 current = self.get_vserver_audit_configuration_rest()
425 retry = 2
426 while retry > 0:
427 record, error = rest_generic.delete_async(self.rest_api, api, None)
428 # Delete throws retry after sometime error during first run by default, hence retrying after sometime.
429 if error and '9699350' in error:
430 time.sleep(120)
431 retry -= 1
432 elif error:
433 self.module.fail_json(msg="Error on deleting vserver audit configuration: %s" % error)
434 else:
435 return
436
437 def modify_vserver_audit_configuration_rest(self, modify):
438 """
439 Updates audit configuration.
440 """
441 body = {}
442 if 'enabled' in modify:
443 body['enabled'] = modify['enabled']
444 else:
445 body = self.create_vserver_audit_config_body_rest()
446 api = "protocols/audit"
447 record, error = rest_generic.patch_async(self.rest_api, api, self.svm_uuid, body)
448 if error:
449 self.module.fail_json(msg="Error on modifying vserver audit configuration: %s" % error)
450
451 def apply(self):
452 current = self.get_vserver_audit_configuration_rest()
453 cd_action = self.na_helper.get_cd_action(current, self.parameters)
454 modify = self.na_helper.get_modified_attributes(current, self.parameters) if cd_action is None else None
455 if self.na_helper.changed and not self.module.check_mode:
456 if cd_action == 'create':
457 self.create_vserver_audit_configuration_rest()
458 elif cd_action == 'delete':
459 self.delete_vserver_audit_configuration_rest(current)
460 elif modify:
461 # No other fields can be specified when enabled is specified for modify
462 if 'enabled' in modify:
463 self.modify_vserver_audit_configuration_rest(modify)
464 modify.pop('enabled')
465 if modify:
466 # This method will be called to modify fields other than enabled
467 self.modify_vserver_audit_configuration_rest(modify)
468 result = netapp_utils.generate_result(self.na_helper.changed, cd_action)
469 self.module.exit_json(**result)
470
471
472 def main():
473 """
474 Creates the NetApp Ontap vserver audit configuration object and runs the correct play task
475 """
476 obj = NetAppONTAPVserverAudit()
477 obj.apply()
478
479
480 if __name__ == '__main__':
481 main()