Debian Codegraph @

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

raw
1 #!/usr/bin/python
2
3 # (c) 2018-2025, 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
8 __metaclass__ = type
9
10
11 DOCUMENTATION = '''
12 module: na_ontap_vscan_on_access_policy
13 short_description: NetApp ONTAP Vscan on access policy configuration.
14 extends_documentation_fragment:
15 - netapp.ontap.netapp.na_ontap
16 version_added: 2.8.0
17 author: NetApp Ansible Team (@carchi8py) <[email protected]>
18 description:
19 - Configure on access policy for Vscan (virus scan)
20 options:
21 state:
22 description:
23 - Whether a Vscan on Access policy is present or not
24 choices: ['present', 'absent']
25 type: str
26 default: present
27
28 vserver:
29 description:
30 - the name of the data vserver to use.
31 required: true
32 type: str
33
34 policy_name:
35 description:
36 - The name of the policy
37 required: true
38 type: str
39
40 file_ext_to_exclude:
41 description:
42 - File extensions for which On-Access scanning must not be performed.
43 type: list
44 elements: str
45
46 file_ext_to_include:
47 description:
48 - File extensions for which On-Access scanning is considered. The default value is '*', which means that all files are considered for scanning except
49 - those which are excluded from scanning.
50 type: list
51 elements: str
52
53 filters:
54 description:
55 - A list of filters which can be used to define the scope of the On-Access policy more precisely. The filters can be added in any order. Possible values
56 - scan_ro_volume Enable scans for read-only volume,
57 - scan_execute_access Scan only files opened with execute-access (CIFS only).
58 - deprecated with REST, use C(scan_readonly_volumes) or C(only_execute_access).
59 type: list
60 elements: str
61
62 is_scan_mandatory:
63 description:
64 - Specifies whether access to a file is allowed if there are no external virus-scanning servers available for virus scanning.
65 - If not specified, default value is False in ZAPI.
66 type: bool
67
68 max_file_size:
69 description:
70 - Max file-size (in bytes) allowed for scanning. The default value of 2147483648 (2GB) is taken if not provided at the time of creating a policy.
71 type: int
72
73 paths_to_exclude:
74 description:
75 - File paths for which On-Access scanning must not be performed.
76 type: list
77 elements: str
78
79 scan_files_with_no_ext:
80 description:
81 - Specifies whether files without any extension are considered for scanning or not.
82 - If not specified, default value is True in ZAPI.
83 type: bool
84
85 policy_status:
86 description:
87 - Status for the created policy
88 type: bool
89 version_added: 20.8.0
90
91 scan_readonly_volumes:
92 description:
93 - Specifies whether or not read-only volume can be scanned.
94 - If not specified, default value is False in creating policy.
95 type: bool
96 version_added: 21.20.0
97
98 only_execute_access:
99 description:
100 - Scan only files opened with execute-access.
101 - If not specified, default value is False in creating policy.
102 type: bool
103 version_added: 21.20.0
104 '''
105
106 EXAMPLES = """
107 - name: Create Vscan On Access Policy
108 netapp.ontap.na_ontap_vscan_on_access_policy:
109 state: present
110 username: '{{ netapp_username }}'
111 password: '{{ netapp_password }}'
112 hostname: '{{ netapp_hostname }}'
113 vserver: carchi-vsim2
114 policy_name: carchi_policy
115 file_ext_to_exclude: ['exe', 'yml']
116 - name: Create Vscan On Access Policy with Policy Status enabled
117 netapp.ontap.na_ontap_vscan_on_access_policy:
118 state: present
119 username: '{{ netapp_username }}'
120 password: '{{ netapp_password }}'
121 hostname: '{{ netapp_hostname }}'
122 vserver: carchi-vsim2
123 policy_name: carchi_policy
124 file_ext_to_exclude: ['exe', 'yml']
125 policy_status: true
126 - name: Modify Vscan on Access Policy
127 netapp.ontap.na_ontap_vscan_on_access_policy:
128 state: present
129 username: '{{ netapp_username }}'
130 password: '{{ netapp_password }}'
131 hostname: '{{ netapp_hostname }}'
132 vserver: carchi-vsim2
133 policy_name: carchi_policy
134 file_ext_to_exclude: ['exe', 'yml', 'py']
135 - name: Delete On Access Policy
136 netapp.ontap.na_ontap_vscan_on_access_policy:
137 state: absent
138 username: '{{ netapp_username }}'
139 password: '{{ netapp_password }}'
140 hostname: '{{ netapp_hostname }}'
141 vserver: carchi-vsim2
142 policy_name: carchi_policy
143 """
144
145 RETURN = """
146
147 """
148
149 import traceback
150
151 from ansible.module_utils.basic import AnsibleModule
152 from ansible.module_utils._text import to_native
153 import ansible_collections.netapp.ontap.plugins.module_utils.netapp as netapp_utils
154 from ansible_collections.netapp.ontap.plugins.module_utils.netapp_module import NetAppModule
155 from ansible_collections.netapp.ontap.plugins.module_utils.netapp import OntapRestAPI
156 from ansible_collections.netapp.ontap.plugins.module_utils import rest_generic, rest_vserver
157
158
159 class NetAppOntapVscanOnAccessPolicy:
160 """
161 Create/Modify/Delete a Vscan OnAccess policy
162 """
163 def __init__(self):
164 self.argument_spec = netapp_utils.na_ontap_host_argument_spec()
165 self.argument_spec.update(dict(
166 state=dict(required=False, type='str', choices=['present', 'absent'], default='present'),
167 vserver=dict(required=True, type='str'),
168 policy_name=dict(required=True, type='str'),
169 file_ext_to_exclude=dict(required=False, type='list', elements='str'),
170 file_ext_to_include=dict(required=False, type='list', elements='str'),
171 filters=dict(required=False, type='list', elements='str'),
172 is_scan_mandatory=dict(required=False, type='bool'),
173 max_file_size=dict(required=False, type="int"),
174 paths_to_exclude=dict(required=False, type='list', elements='str'),
175 scan_files_with_no_ext=dict(required=False, type='bool'),
176 policy_status=dict(required=False, type='bool'),
177 scan_readonly_volumes=dict(required=False, type='bool'),
178 only_execute_access=dict(required=False, type='bool')
179 ))
180 self.module = AnsibleModule(
181 argument_spec=self.argument_spec,
182 supports_check_mode=True,
183 mutually_exclusive=[
184 ['filters', 'scan_readonly_volumes'],
185 ['filters', 'only_execute_access']
186 ]
187 )
188 self.na_helper = NetAppModule()
189 self.parameters = self.na_helper.set_parameters(self.module.params)
190
191 # Set up Rest API
192 self.rest_api = OntapRestAPI(self.module)
193 self.use_rest = self.rest_api.is_rest()
194 self.svm_uuid = None
195
196 # validate list options not contains '' in it in REST.
197 if self.use_rest:
198 self.validate_options()
199
200 # file_ext_to_include cannot be empty in both ZAPI and REST.
201 if 'file_ext_to_include' in self.parameters and len(self.parameters['file_ext_to_include']) < 1:
202 self.module.fail_json(msg="Error: The value for file_ext_include cannot be empty")
203
204 # map filters options to rest equivalent options.
205 if self.use_rest and 'filters' in self.parameters:
206 self.parameters['only_execute_access'], self.parameters['scan_readonly_volumes'] = False, False
207 for filter in self.parameters['filters']:
208 if filter.lower() not in ['scan_execute_access', 'scan_ro_volume']:
209 self.module.fail_json(msg="Error: Invalid value %s specified for filters %s" % filter)
210 if filter.lower() == 'scan_execute_access':
211 self.parameters['only_execute_access'] = True
212 if filter.lower() == 'scan_ro_volume':
213 self.parameters['scan_readonly_volumes'] = True
214
215 if not self.use_rest:
216 if not netapp_utils.has_netapp_lib():
217 self.module.fail_json(msg=netapp_utils.netapp_lib_is_required())
218 self.server = netapp_utils.setup_na_ontap_zapi(module=self.module, vserver=self.parameters['vserver'])
219 self.set_playbook_zapi_key_map()
220
221 # set default value for is_scan_mandatory and scan_files_with_no_ext if not set.
222 if self.parameters.get('is_scan_mandatory') is None:
223 self.parameters['is_scan_mandatory'] = False
224 if self.parameters.get('scan_files_with_no_ext') is None:
225 self.parameters['scan_files_with_no_ext'] = True
226
227 # form filters from REST options only_execute_access and scan_readonly_volumes.
228 filters = []
229 if self.parameters.get('only_execute_access'):
230 filters.append('scan_execute_access')
231 if self.parameters.get('scan_readonly_volumes'):
232 filters.append('scan_ro_volume')
233 if filters:
234 self.parameters['filters'] = filters
235
236 def validate_options(self):
237 list_options = ['filters', 'file_ext_to_exclude', 'file_ext_to_include', 'paths_to_exclude']
238 invalid_options = []
239 for option in list_options:
240 if option in self.parameters:
241 for value in self.parameters[option]:
242 # '' is an invalid value.
243 if len(value.strip()) < 1:
244 invalid_options.append(option)
245 if invalid_options:
246 self.module.fail_json(msg="Error: Invalid value specified for option(s): %s" % ', '.join(invalid_options))
247
248 def set_playbook_zapi_key_map(self):
249 self.na_helper.zapi_int_keys = {
250 'max_file_size': 'max-file-size'
251 }
252 self.na_helper.zapi_str_keys = {
253 'vserver': 'vserver',
254 'policy_name': 'policy-name'
255 }
256 self.na_helper.zapi_bool_keys = {
257 'is_scan_mandatory': 'is-scan-mandatory',
258 'policy_status': 'is-policy-enabled',
259 'scan_files_with_no_ext': 'scan-files-with-no-ext'
260 }
261 self.na_helper.zapi_list_keys = {
262 'file_ext_to_exclude': 'file-ext-to-exclude',
263 'file_ext_to_include': 'file-ext-to-include',
264 'paths_to_exclude': 'paths-to-exclude',
265 'filters': 'filters'
266 }
267
268 def get_on_access_policy(self):
269 """
270 Return a Vscan on Access Policy
271 :return: None if there is no access policy, return the policy if there is
272 """
273 if self.use_rest:
274 return self.get_on_access_policy_rest()
275 access_policy_obj = netapp_utils.zapi.NaElement('vscan-on-access-policy-get-iter')
276 access_policy_info = netapp_utils.zapi.NaElement('vscan-on-access-policy-info')
277 access_policy_info.add_new_child('policy-name', self.parameters['policy_name'])
278 access_policy_info.add_new_child('vserver', self.parameters['vserver'])
279 query = netapp_utils.zapi.NaElement('query')
280 query.add_child_elem(access_policy_info)
281 access_policy_obj.add_child_elem(query)
282 try:
283 result = self.server.invoke_successfully(access_policy_obj, True)
284 except netapp_utils.zapi.NaApiError as error:
285 self.module.fail_json(msg='Error searching Vscan on Access Policy %s: %s' %
286 (self.parameters['policy_name'], to_native(error)), exception=traceback.format_exc())
287 return_value = {}
288 if result.get_child_by_name('num-records'):
289 if int(result.get_child_content('num-records')) == 1:
290 attributes_list = result.get_child_by_name('attributes-list')
291 vscan_info = attributes_list.get_child_by_name('vscan-on-access-policy-info')
292 for option, zapi_key in self.na_helper.zapi_int_keys.items():
293 return_value[option] = self.na_helper.get_value_for_int(from_zapi=True, value=vscan_info.get_child_content(zapi_key))
294 for option, zapi_key in self.na_helper.zapi_bool_keys.items():
295 return_value[option] = self.na_helper.get_value_for_bool(from_zapi=True, value=vscan_info.get_child_content(zapi_key))
296 for option, zapi_key in self.na_helper.zapi_list_keys.items():
297 return_value[option] = self.na_helper.get_value_for_list(from_zapi=True, zapi_parent=vscan_info.get_child_by_name(zapi_key))
298 for option, zapi_key in self.na_helper.zapi_str_keys.items():
299 return_value[option] = vscan_info.get_child_content(zapi_key)
300 return return_value
301 elif int(result.get_child_content('num-records')) > 1:
302 self.module.fail_json(msg='Mutiple Vscan on Access Policy matching %s:' % self.parameters['policy_name'])
303 return None
304
305 def create_on_access_policy(self):
306 """
307 Create a Vscan on Access policy
308 :return: none
309 """
310 if self.use_rest:
311 return self.create_on_access_policy_rest()
312 access_policy_obj = netapp_utils.zapi.NaElement('vscan-on-access-policy-create')
313 access_policy_obj.add_new_child('policy-name', self.parameters['policy_name'])
314 access_policy_obj.add_new_child('protocol', 'cifs')
315 access_policy_obj = self._fill_in_access_policy(access_policy_obj)
316
317 try:
318 self.server.invoke_successfully(access_policy_obj, True)
319 except netapp_utils.zapi.NaApiError as error:
320 self.module.fail_json(msg='Error creating Vscan on Access Policy %s: %s' %
321 (self.parameters['policy_name'], to_native(error)), exception=traceback.format_exc())
322
323 def status_modify_on_access_policy(self):
324 """
325 Update the status of policy
326 """
327 if self.use_rest:
328 return self.modify_on_access_policy_rest({'policy_status': False})
329 access_policy_obj = netapp_utils.zapi.NaElement('vscan-on-access-policy-status-modify')
330 access_policy_obj.add_new_child('policy-name', self.parameters['policy_name'])
331 access_policy_obj.add_new_child('policy-status', str(self.parameters['policy_status']).lower())
332
333 try:
334 self.server.invoke_successfully(access_policy_obj, True)
335 except netapp_utils.zapi.NaApiError as error:
336 self.module.fail_json(msg='Error modifying status Vscan on Access Policy %s: %s' %
337 (self.parameters['policy_name'], to_native(error)), exception=traceback.format_exc())
338
339 def delete_on_access_policy(self):
340 """
341 Delete a Vscan On Access Policy
342 :return:
343 """
344 if self.use_rest:
345 return self.delete_on_access_policy_rest()
346 access_policy_obj = netapp_utils.zapi.NaElement('vscan-on-access-policy-delete')
347 access_policy_obj.add_new_child('policy-name', self.parameters['policy_name'])
348 try:
349 self.server.invoke_successfully(access_policy_obj, True)
350 except netapp_utils.zapi.NaApiError as error:
351 self.module.fail_json(msg='Error Deleting Vscan on Access Policy %s: %s' %
352 (self.parameters['policy_name'], to_native(error)), exception=traceback.format_exc())
353
354 def modify_on_access_policy(self, modify=None):
355 """
356 Modify a Vscan On Access policy
357 :return: nothing
358 """
359 if self.use_rest:
360 return self.modify_on_access_policy_rest(modify)
361 access_policy_obj = netapp_utils.zapi.NaElement('vscan-on-access-policy-modify')
362 access_policy_obj.add_new_child('policy-name', self.parameters['policy_name'])
363 access_policy_obj = self._fill_in_access_policy(access_policy_obj)
364 try:
365 self.server.invoke_successfully(access_policy_obj, True)
366 except netapp_utils.zapi.NaApiError as error:
367 self.module.fail_json(msg='Error Modifying Vscan on Access Policy %s: %s' %
368 (self.parameters['policy_name'], to_native(error)), exception=traceback.format_exc())
369
370 def _fill_in_access_policy(self, access_policy_obj):
371 if self.parameters.get('is_scan_mandatory') is not None:
372 access_policy_obj.add_new_child('is-scan-mandatory', str(self.parameters['is_scan_mandatory']).lower())
373 if self.parameters.get('max_file_size'):
374 access_policy_obj.add_new_child('max-file-size', str(self.parameters['max_file_size']))
375 if self.parameters.get('scan_files_with_no_ext') is not None:
376 access_policy_obj.add_new_child('scan-files-with-no-ext', str(self.parameters['scan_files_with_no_ext']))
377 if 'file_ext_to_exclude' in self.parameters:
378 ext_obj = netapp_utils.zapi.NaElement('file-ext-to-exclude')
379 access_policy_obj.add_child_elem(ext_obj)
380 if len(self.parameters['file_ext_to_exclude']) < 1:
381 ext_obj.add_new_child('file-extension', "")
382 else:
383 for extension in self.parameters['file_ext_to_exclude']:
384 ext_obj.add_new_child('file-extension', extension)
385 if 'file_ext_to_include' in self.parameters:
386 ext_obj = netapp_utils.zapi.NaElement('file-ext-to-include')
387 access_policy_obj.add_child_elem(ext_obj)
388 for extension in self.parameters['file_ext_to_include']:
389 ext_obj.add_new_child('file-extension', extension)
390 if 'filters' in self.parameters:
391 ui_filter_obj = netapp_utils.zapi.NaElement('filters')
392 access_policy_obj.add_child_elem(ui_filter_obj)
393 if len(self.parameters['filters']) < 1:
394 ui_filter_obj.add_new_child('vscan-on-access-policy-ui-filter', "")
395 else:
396 for filter in self.parameters['filters']:
397 ui_filter_obj.add_new_child('vscan-on-access-policy-ui-filter', filter)
398 if 'paths_to_exclude' in self.parameters:
399 path_obj = netapp_utils.zapi.NaElement('paths-to-exclude')
400 access_policy_obj.add_child_elem(path_obj)
401 if len(self.parameters['paths_to_exclude']) < 1:
402 path_obj.add_new_child('file-path', "")
403 else:
404 for path in self.parameters['paths_to_exclude']:
405 path_obj.add_new_child('file-path', path)
406 return access_policy_obj
407
408 def get_on_access_policy_rest(self):
409 self.svm_uuid = self.get_svm_uuid()
410 if self.svm_uuid is None:
411 self.module.fail_json(msg="Error: vserver %s not found" % self.parameters['vserver'])
412 api = "protocols/vscan/%s/on-access-policies" % self.svm_uuid
413 query = {'name': self.parameters['policy_name']}
414 fields = 'svm,name,mandatory,scope,enabled'
415 record, error = rest_generic.get_one_record(self.rest_api, api, query, fields)
416 if error:
417 self.module.fail_json(msg='Error searching Vscan on Access Policy %s: %s' %
418 (self.parameters['policy_name'], to_native(error)))
419 if record:
420 return {
421 'max_file_size': self.na_helper.safe_get(record, ['scope', 'max_file_size']),
422 'vserver': self.na_helper.safe_get(record, ['svm', 'name']),
423 'policy_name': record['name'],
424 'is_scan_mandatory': record['mandatory'],
425 'policy_status': record['enabled'],
426 'scan_files_with_no_ext': self.na_helper.safe_get(record, ['scope', 'scan_without_extension']),
427 'file_ext_to_exclude': self.na_helper.safe_get(record, ['scope', 'exclude_extensions']),
428 'file_ext_to_include': self.na_helper.safe_get(record, ['scope', 'include_extensions']),
429 'paths_to_exclude': self.na_helper.safe_get(record, ['scope', 'exclude_paths']),
430 'scan_readonly_volumes': self.na_helper.safe_get(record, ['scope', 'scan_readonly_volumes']),
431 'only_execute_access': self.na_helper.safe_get(record, ['scope', 'only_execute_access'])
432 }
433 return None
434
435 def get_svm_uuid(self):
436 uuid, error = rest_vserver.get_vserver_uuid(self.rest_api, self.parameters['vserver'], self.module, True)
437 return uuid
438
439 def create_on_access_policy_rest(self):
440 api = "protocols/vscan/%s/on-access-policies" % self.svm_uuid
441 body = {'name': self.parameters['policy_name']}
442 body.update(self.form_create_or_modify_body(self.parameters))
443 dummy, error = rest_generic.post_async(self.rest_api, api, body)
444 if error:
445 self.module.fail_json(msg='Error creating Vscan on Access Policy %s: %s' %
446 (self.parameters['policy_name'], to_native(error)))
447
448 def modify_on_access_policy_rest(self, modify):
449 api = "protocols/vscan/%s/on-access-policies" % self.svm_uuid
450 body = self.form_create_or_modify_body(modify)
451 dummy, error = rest_generic.patch_async(self.rest_api, api, self.parameters['policy_name'], body)
452 if error:
453 self.module.fail_json(msg='Error Modifying Vscan on Access Policy %s: %s' %
454 (self.parameters['policy_name'], to_native(error)))
455
456 def form_create_or_modify_body(self, params):
457 body = {}
458 if params.get('is_scan_mandatory') is not None:
459 body['mandatory'] = params['is_scan_mandatory']
460 if params.get('policy_status') is not None:
461 body['enabled'] = params['policy_status']
462 if params.get('max_file_size'):
463 body['scope.max_file_size'] = params['max_file_size']
464 if params.get('scan_files_with_no_ext') is not None:
465 body['scope.scan_without_extension'] = params['scan_files_with_no_ext']
466 if 'file_ext_to_exclude' in params:
467 body['scope.exclude_extensions'] = params['file_ext_to_exclude']
468 if 'file_ext_to_include' in params:
469 body['scope.include_extensions'] = params['file_ext_to_include']
470 if 'paths_to_exclude' in params:
471 body['scope.exclude_paths'] = params['paths_to_exclude']
472 if params.get('scan_readonly_volumes') is not None:
473 body['scope.scan_readonly_volumes'] = params['scan_readonly_volumes']
474 if params.get('only_execute_access') is not None:
475 body['scope.only_execute_access'] = params['only_execute_access']
476 return body
477
478 def delete_on_access_policy_rest(self):
479 api = "protocols/vscan/%s/on-access-policies" % self.svm_uuid
480 dummy, error = rest_generic.delete_async(self.rest_api, api, self.parameters['policy_name'])
481 if error:
482 self.module.fail_json(msg='Error Deleting Vscan on Access Policy %s: %s' %
483 (self.parameters['policy_name'], to_native(error)))
484
485 def apply(self):
486 modify_policy_state, modify = None, None
487 current = self.get_on_access_policy()
488 cd_action = self.na_helper.get_cd_action(current, self.parameters)
489 if cd_action is None and self.parameters['state'] == 'present':
490 modify = self.na_helper.get_modified_attributes(current, self.parameters)
491 # enable/disable policy handled in single modify api with REST.
492 if not self.use_rest and modify.get('policy_status') is not None:
493 modify_policy_state = True
494 # policy cannot be deleted unless its disabled, so disable it before delete.
495 if cd_action == 'delete' and current['policy_status'] is True and self.parameters.get('policy_status') is False:
496 modify_policy_state = True
497 if self.na_helper.changed and not self.module.check_mode:
498 if cd_action == 'create':
499 self.create_on_access_policy()
500 # by default newly created policy will be in disabled state, enable if policy_status is set in ZAPI.
501 # REST enable policy on create itself.
502 if not self.use_rest and self.parameters.get('policy_status'):
503 modify_policy_state = True
504 if modify_policy_state:
505 self.status_modify_on_access_policy()
506 if cd_action == 'delete':
507 self.delete_on_access_policy()
508 if modify:
509 self.modify_on_access_policy(modify)
510 result = netapp_utils.generate_result(self.na_helper.changed, cd_action, modify,
511 extra_responses={'modify_policy_state': modify_policy_state})
512 self.module.exit_json(**result)
513
514
515 def main():
516 """
517 Execute action from playbook
518 """
519 command = NetAppOntapVscanOnAccessPolicy()
520 command.apply()
521
522
523 if __name__ == '__main__':
524 main()