'''
Policies
========
Methods described in this section relate to the files API.
These methods can be accessed at ``Nessus.policies``.
.. rst-class:: hide-signature
.. autoclass:: PoliciesAPI
:members:
'''
from io import BytesIO
from typing import Optional, Dict, List
from tenable.base.endpoint import APIEndpoint
[docs]class PoliciesAPI(APIEndpoint): # noqa PLC0115
_path = 'policies'
[docs] def copy(self, policy_id: int) -> Dict:
'''
Duplicates an existing scan policy.
Args:
policy_id (int): The id of the policy to clone.
Returns:
Dict:
The cloned policy object.
Example:
>>> nessus.policies.copy(1)
'''
return self._post(f'{policy_id}/copy')
[docs] def create(self, uuid: str, **kwargs) -> Dict:
'''
Creates a new scan policy using the provided settings.
Args:
uuid (str): The UUID for the editor template to use.
**kwargs (dict): Additional settings to use to create the policy.
Returns:
Dict:
Response object with identifying information on the new policy
Example:
>>> tmpl = '731a8e52-3ea6-a291-ec0a-d2ff0619c19d7bd788d6be818b65'
>>> nessus.policies.create(tmpl_uuid, settings={
... 'name': 'Sample Policy'
... })
'''
kwargs['uuid'] = uuid
return self._post(json=kwargs)
[docs] def delete(self, policy_id: int) -> None:
'''
Deletes the specified scan policy.
Args:
policy_id (int): The id of the policy to delete.
Example:
>>> nessus.policies.delete(1)
'''
return self._delete(f'{policy_id}')
[docs] def delete_many(self, policy_ids: List[int]) -> List[int]:
'''
Deletes the specified scan policies.
Args:
policy_ids (list[int]): The list of policy ids to delete.
Example:
>>> nessus.policies.delete_many([1, 2, 3])
'''
return self._delete(json={'ids': policy_ids})['deleted']
[docs] def details(self, policy_id: int) -> Dict:
'''
Returns the details of the selected policy.
Args:
policy_id (int): The id of the policy to retrieve.
Returns:
Dict:
The policy object.
Example:
>>> nessus.policies.details(1)
'''
return self._get(f'{policy_id}')
[docs] def edit(self, policy_id: int, **kwargs) -> None:
'''
Updates an existing scan policy.
Args:
policy_id (int): The id of the policy to edit.
**kwargs (dict): Attributes to be passed into the JSON body.
Example:
>>> policy = nessus.policies.details(1)
>>> policy['settings']['name'] = 'Updated Policy'
>>> nessus.policies.edit(1, **policy)
'''
return self._put(f'{policy_id}', json=kwargs)
[docs] def import_policy(self, fobj: BytesIO) -> Dict:
'''
Imports the policy into the nessus scanner.
Args:
fobj (BytesIO): The file object containing the policy.
Returns:
Dict:
The imported policy object.
Example:
>>> with open('policy.xml', 'rb') as policy:
... nessus.policies.import_policy(policy)
'''
filename = self._api.files.upload(fobj)
return self._post('import', json={'file': filename})
[docs] def export_policy(self,
policy_id: int,
fobj: Optional[BytesIO] = None,
**kwargs
) -> BytesIO:
'''
Export the specified policy and download it.
Args:
policy_id (int): The id of the policy to export.
fobj (BytexIO, optional):
The file object to write the exported file to. If none is
specified then a BytesIO object is written to in memory.
chunk_size (int, optional):
The chunk sizing for the download itself.
stream_hook (callable, optional):
Overload the default downloading behavior with a custom
stream hook.
hook_kwargs (dict, optional):
keyword arguments to pass to the stream_hook callable in
addition to the default passed params.
'''
kwargs['fobj'] = fobj
token = self._get(f'{policy_id}/export/prepare')['token']
return self._api.tokens._fetch(token, **kwargs) # noqa PLW0212
[docs] def list(self,) -> List[Dict]:
'''
Lists the available policies.
Returns:
List[Dict]:
List of policy objects.
Example:
>>> for policy in nessus.policies.list():
... print(policy)
'''
return self._get()['policies']