Source code for tenable.nessus.scanners

'''
Scanners
========

Methods described in this section relate to the scanners API.
These methods can be accessed at ``Nessus.scanners``.

.. rst-class:: hide-signature
.. autoclass:: ScannersAPI
    :members:
'''
from typing import List, Dict, Optional
from typing_extensions import Literal
from restfly.utils import dict_clean
from tenable.base.endpoint import APIEndpoint




[docs]
class ScannersAPI(APIEndpoint):
    _path = 'scanners'
    


[docs]
    def control_scan(self, 
                     scanner_id: int,
                     scan_uuid: str,
                     action: Literal['stop', 'pause', 'resume']
                     ) -> None:
        '''
        Controls a scan currently running on a scanner.
        
        Args:
            scanner_id (int): Id of the scanner to control
            scan_uuid (str): UUID of the scan to control
            action (str): The action to perform on the scan.
        
        Example:
            
            >>> nessus.scanners.control_scan(scanner_id, scan_uuid, 'pause')
        '''
        self._post(f'{scanner_id}/scans/{scan_uuid}/control', 
                   json={'action': action}
                   )


    


[docs]
    def delete(self, scanner_id: int) -> None:
        '''
        Delete and unlink the scanner.
        
        Args:
            scanner_id (int): Id of the scanner to delete
        
        Example:
            
            >>> nessus.scanners.delete(1)
        '''
        self._delete(f'{scanner_id}')


    


[docs]
    def delete_many(self, scanner_ids: List[int]) -> None:
        '''
        Delete and unlink many scanners.
        
        Args:
            scanner_ids (list[int]): List of scanner ids to delete
        
        Example:
            
            >>> nessus.scanners.delete_many([1, 2, 3])
        '''
        self._delete(json={'ids': scanner_ids})


    


[docs]
    def details(self, scanner_id: int) -> Dict:
        '''
        Retrieve the details for a scanner.
        
        Args:
            scanner_id (int): Id of the scanner to retrieve
        
        Example:
            
            >>> nessus.scanners.details(1)
        '''
        return self._get(f'{scanner_id}')


    


[docs]
    def update(self,
               scanner_id: int,
               force_plugin_update: Optional[bool] = None,
               force_ui_update: Optional[bool] = None,
               finish_update: Optional[bool] = None,
               registration_code: Optional[str] = None,
               aws_update_interval: Optional[int] = None
               ) -> None:
        '''
        Update the scanner
        
        Args:
            scanner_id (int): 
                Id of the scanner to update
            force_plugin_update (bool, optional):
                Should the scanner plugins be forcibly updated?
            force_ui_update (bool, optional):
                Should the scanner UI be forcibly updated?
            finish_update (bool, optional):
                Should the scanner service be restarted to run the latest
                software update?  This is only valid if automatic updates on
                the scanner are disabled.
            registration_code (str, optional):
                Sets the registration code for the scanner.
            aws_update_interval (int, optional):
                Informs the scanner how often to check into the controlling
                Tenable Nessus service.  This is only valid for AWS scanners.
        
        Example:
            
            >>> nessus.scanners.update(1,
            ...                        force_plugin_update=True,
            ...                        force_ui_update=True
            ...                        )
        '''
        if force_plugin_update is not None:
            force_plugin_update = int(force_plugin_update)
        if force_ui_update is not None:
            force_ui_update = int(force_ui_update)
        if finish_update is not None:
            finish_update = int(finish_update)
        self._put(f'{scanner_id}', json=dict_clean({
            'force_plugin_update': force_plugin_update,
            'force_ui_update': force_ui_update,
            'finish_update': finish_update,
            'registration_code': registration_code,
            'aws_update_interval': aws_update_interval
        }))


    


[docs]
    def aws_targets(self, scanner_id: int) -> List[Dict]:
        '''
        Retrieves the AWS targets from the scanner.  Only applies to AWS
        scanners.
        
        Args:
            scanner_id (int): Id of the scanner to call
        
        Returns:
            List:
                List of AWS target objects.
        
        Example:
            
            >>> for target in nessus.scanners.aws_targets(1):
            ...     print(target)
        '''
        return self._get(f'{scanner_id}/aws-targets')['targets']


    


[docs]
    def scanner_key(self, scanner_id: int) -> str:
        '''
        Retrieves the scanner key for the requested scanner.
        
        Args:
            scanner_id (int): Id of the scanner to call
        
        Returns:
            str:
                The scanner key
        
        Example:
        
            >>> nessus.scanners.scanner_key(1)
        '''
        return self._get(f'{scanner_id}/key')['key']


    


[docs]
    def running_scans(self, scanner_id: int) -> List[Dict]:
        '''
        Retrieves the list of running scans on the scanner.
        
        Args:
            scanner_id (int): Id of the scanner to call
        
        Returns:
            List:
                If scans are running on the scanner, a list of scan objects
                will be returned.  If no scans are currently running on the
                scanner, then a None object will be returned.
        
        Example:
            
            >>> scans = nessus.scanners.active_scans(1)
            >>> if scans:
            ...     for scan in scans:
            ...         print(scan)
        '''
        return self._get(f'{scanner_id}/scans')['scans']


    


[docs]
    def list(self) -> List[Dict]:
        '''
        Returns a list of scanners.
        
        Returns:
            List:
                List of scanners connected to this scanner.
        
        Example:
            
            >>> for scanner in nessus.scanners.list():
            ...     print(scanner)
        '''
        return self._get()['scanners']