diff --git a/docs/api/io/access_groups.rst b/docs/api/io/access_groups.rst deleted file mode 100644 index 93304b0eb..000000000 --- a/docs/api/io/access_groups.rst +++ /dev/null @@ -1 +0,0 @@ -.. automodule:: tenable.io.access_groups diff --git a/docs/api/io/access_groups_v2.rst b/docs/api/io/access_groups_v2.rst deleted file mode 100644 index e47af3e60..000000000 --- a/docs/api/io/access_groups_v2.rst +++ /dev/null @@ -1 +0,0 @@ -.. automodule:: tenable.io.access_groups_v2 diff --git a/docs/api/io/pci/attestations.rst b/docs/api/io/pci/attestations.rst new file mode 100644 index 000000000..d910f7ec8 --- /dev/null +++ b/docs/api/io/pci/attestations.rst @@ -0,0 +1 @@ +.. automodule:: tenable.io.pci.attestations diff --git a/docs/api/io/pci/index.rst b/docs/api/io/pci/index.rst new file mode 100644 index 000000000..7c07d0288 --- /dev/null +++ b/docs/api/io/pci/index.rst @@ -0,0 +1 @@ +.. automodule:: tenable.io.pci diff --git a/docs/api/io/pci/scans.rst b/docs/api/io/pci/scans.rst new file mode 100644 index 000000000..32056b225 --- /dev/null +++ b/docs/api/io/pci/scans.rst @@ -0,0 +1 @@ +.. automodule:: tenable.io.pci.scans diff --git a/docs/api/io/target_groups.rst b/docs/api/io/target_groups.rst deleted file mode 100644 index 889c6d18c..000000000 --- a/docs/api/io/target_groups.rst +++ /dev/null @@ -1 +0,0 @@ -.. automodule:: tenable.io.target_groups diff --git a/docs/api/nessus/plugin_rules.rst b/docs/api/nessus/plugin_rules.rst new file mode 100644 index 000000000..b9e0ff93d --- /dev/null +++ b/docs/api/nessus/plugin_rules.rst @@ -0,0 +1,4 @@ +.. important:: + The Nessus Package is currently a Technology Preview + +.. automodule:: tenable.nessus.plugin_rules diff --git a/docs/api/sc/license.rst b/docs/api/sc/license.rst new file mode 100644 index 000000000..4168a6390 --- /dev/null +++ b/docs/api/sc/license.rst @@ -0,0 +1 @@ +.. automodule:: tenable.sc.license diff --git a/docs/api/sc/report_definition.rst b/docs/api/sc/report_definition.rst new file mode 100644 index 000000000..d1e7828ab --- /dev/null +++ b/docs/api/sc/report_definition.rst @@ -0,0 +1 @@ +.. automodule:: tenable.sc.report_definition diff --git a/docs/api/sc/tickets.rst b/docs/api/sc/tickets.rst new file mode 100644 index 000000000..31271dd4f --- /dev/null +++ b/docs/api/sc/tickets.rst @@ -0,0 +1 @@ +.. automodule:: tenable.sc.tickets diff --git a/docs/api/tenableone/inventory/findings/schema.rst b/docs/api/tenableone/inventory/findings/schema.rst deleted file mode 100644 index 7aa2003ba..000000000 --- a/docs/api/tenableone/inventory/findings/schema.rst +++ /dev/null @@ -1 +0,0 @@ -.. automodule:: tenable.tenableone.inventory.findings.schema diff --git a/tenable/__init__.py b/tenable/__init__.py index ebe9c149f..fb8106a88 100644 --- a/tenable/__init__.py +++ b/tenable/__init__.py @@ -7,7 +7,6 @@ .. image:: https://img.shields.io/readthedocs/pytenable .. image:: https://img.shields.io/pypi/dm/pytenable .. image:: https://img.shields.io/github/license/tenable/pyTenable.svg -.. image:: https://sonarcloud.io/api/project_badges/measure?project=tenable_pyTenable&metric=alert_status pyTenable is intended to be a pythonic interface into the Tenable application APIs. Further by providing a common interface and a common structure between diff --git a/tenable/io/__init__.py b/tenable/io/__init__.py index f054d12e9..fd7fabbbd 100644 --- a/tenable/io/__init__.py +++ b/tenable/io/__init__.py @@ -11,6 +11,7 @@ :glob: cs/index + pci/index access_control agent_config agent_exclusions @@ -436,10 +437,6 @@ def workbenches(self): @property def v3(self): - """ - The interface object for the - :doc:`Tenable Vulnerability Management v3 APIs `. - """ warnings.warn( 'The V3 sub-pkg have been deprecated from the TVM ' 'package. This method will be removed in a future ' diff --git a/tenable/io/exports/api.py b/tenable/io/exports/api.py index edb147e0a..e2dec92b0 100644 --- a/tenable/io/exports/api.py +++ b/tenable/io/exports/api.py @@ -932,7 +932,7 @@ def vulns( cve_category: Returns findings the match the specified CVE category. For more information about categories, see the *Vulnerability Categories* - section in the _Tenable Vulnerability Management User Guide_. + section in the Tenable Vulnerability Management User Guide. exploit_maturity: Returns findings that match the specified exploit maturity. Tenable assigns exploit maturity values to vulnerabilities based on the @@ -1079,6 +1079,7 @@ def was( """ Initiate a WAS vulnerability export. :devportal:`API Documentation ` + Args: first_found: Findings first discovered after this timestamp will be returned. diff --git a/tenable/io/pci/__init__.py b/tenable/io/pci/__init__.py index 17d52d878..6773bdc55 100644 --- a/tenable/io/pci/__init__.py +++ b/tenable/io/pci/__init__.py @@ -10,6 +10,13 @@ .. autoclass:: PCIASVAPI :members: +.. toctree:: + :hidden: + :glob: + + attestations + scans + """ from typing import Any, Literal, Type diff --git a/tenable/nessus/api.py b/tenable/nessus/api.py index 10276939f..743f3d0ae 100644 --- a/tenable/nessus/api.py +++ b/tenable/nessus/api.py @@ -1,4 +1,4 @@ -''' +""" Nessus ====== @@ -20,6 +20,7 @@ groups mail permissions + plugin_rules plugins policies proxy @@ -31,8 +32,10 @@ software_update tokens users -''' +""" + from tenable.base.platform import APIPlatform + from .agent_groups import AgentGroupsAPI from .agents import AgentsAPI from .editor import EditorAPI @@ -42,9 +45,9 @@ from .mail import MailAPI from .permissions import PermissionsAPI from .plugin_rules import PluginRulesAPI +from .plugins import PluginsAPI from .policies import PoliciesAPI from .proxy import ProxyAPI -from .plugins import PluginsAPI from .scanners import ScannersAPI from .scans import ScansAPI from .server import ServerAPI @@ -56,165 +59,163 @@ class Nessus(APIPlatform): - ''' + """ The Nessus object is the primary interaction point for users to interface with Tenable Nessus via the pyTenable library. All of the API endpoint classes that have been written will be grafted onto this class. - ''' + """ + _env_base = 'NESSUS' _ssl_verify = False _conv_json = True def _session_auth(self, username, password): # noqa: PLW0221,PLW0613 - token = self.post('session', json={ - 'username': username, - 'password': password - }).get('token') - self._session.headers.update({ - 'X-Cookie': f'token={token}' - }) + token = self.post( + 'session', json={'username': username, 'password': password} + ).get('token') + self._session.headers.update({'X-Cookie': f'token={token}'}) self._auth_mech = 'user' @property def agent_groups(self): - ''' + """ The interface object for the :doc:`Tenable Nessus Agent Groups APIs `. - ''' + """ return AgentGroupsAPI(self) @property def agents(self): - ''' + """ The interface object for the :doc:`Tenable Nessus Agents APIs `. - ''' + """ return AgentsAPI(self) @property def editor(self): - ''' + """ The interface object for the :doc:`Tenable Nessus Editor APIs `. - ''' + """ return EditorAPI(self) @property def files(self): - ''' + """ The interface object for the :doc:`Tenable Nessus File APIs `. - ''' + """ return FilesAPI(self) @property def folders(self): - ''' + """ The interface object for the :doc:`Tenable Nessus Folders APIs `. - ''' + """ return FoldersAPI(self) @property def groups(self): - ''' + """ The interface object for the :doc:`Tenable Nessus Groups APIs `. - ''' + """ return GroupsAPI(self) @property def mail(self): - ''' + """ The interface object for the :doc:`Tenable Nessus Mail APIs `. - ''' + """ return MailAPI(self) @property def permissions(self): - ''' + """ The interface object for the :doc:`Tenable Nessus Permissions APIs `. - ''' + """ return PermissionsAPI(self) @property def plugin_rules(self): - ''' + """ The interface object for the :doc:`Tenable Nessus Plugin Rules APIs `. - ''' + """ return PluginRulesAPI(self) @property def plugins(self): - ''' + """ The interface object for the :doc:`Tenable Nessus Plugins APIs `. - ''' + """ return PluginsAPI(self) @property def policies(self): - ''' + """ The interface object for the :doc:`Tenable Nessus Policies APIs `. - ''' + """ return PoliciesAPI(self) @property def proxy(self): - ''' + """ The interface object for the :doc:`Tenable Nessus Proxy APIs `. - ''' + """ return ProxyAPI(self) @property def scanners(self): - ''' + """ The interface object for the :doc:`Tenable Nessus Scanners APIs `. - ''' + """ return ScannersAPI(self) @property def scans(self): - ''' + """ The interface object for the :doc:`Tenable Nessus Scans APIs `. - ''' + """ return ScansAPI(self) @property def server(self): - ''' + """ The interface object for the :doc:`Tenable Nessus Server APIs `. - ''' + """ return ServerAPI(self) @property def session(self): - ''' + """ The interface object for the :doc:`Tenable Nessus Session APIs `. - ''' + """ return SessionAPI(self) @property def settings(self): - ''' + """ The interface object for the :doc:`Tenable Nessus Settings APIs `. - ''' + """ return SettingsAPI(self) @property def software_update(self): - ''' + """ The interface object for the :doc:`Tenable Nessus Software Update APIs `. - ''' + """ return SoftwareUpdateAPI(self) @property def tokens(self): - ''' + """ The interface object for the :doc:`Tenable Nessus Tokens APIs `. - ''' + """ return TokensAPI(self) @property def users(self): - ''' + """ The interface object for the :doc:`Tenable Nessus Users APIs `. - ''' + """ return UsersAPI(self) diff --git a/tenable/sc/__init__.py b/tenable/sc/__init__.py index 7a469173a..090eab88f 100644 --- a/tenable/sc/__init__.py +++ b/tenable/sc/__init__.py @@ -29,6 +29,7 @@ feeds files groups + hosts license organizations plugins @@ -68,8 +69,8 @@ from .feeds import FeedAPI from .files import FileAPI from .groups import GroupAPI -from .license import LicenseAPI from .hosts import HostsAPI +from .license import LicenseAPI from .organizations import OrganizationAPI from .plugins import PluginAPI from .policies import ScanPolicyAPI @@ -230,8 +231,7 @@ def __init__( stacklevel=2, ) kwargs['url'] = ( - f'{kwargs.get("scheme", "https")}://' - f'{host}:{kwargs.get("port", 443)}' + f'{kwargs.get("scheme", "https")}://{host}:{kwargs.get("port", 443)}' ) kwargs['access_key'] = access_key @@ -509,12 +509,12 @@ def hosts(self): @property def license(self): - ''' + """ The interface object for the :doc:`Tenable Security Center License APIs `. - ''' - return LicenseAPI(self) - + """ + return LicenseAPI(self) + @property def organizations(self): """ @@ -626,15 +626,15 @@ def system(self): :doc:`Tenable Security Center System APIs `. """ return SystemAPI(self) - + @property def tickets(self): - ''' + """ The interface object for the :doc:`Tenable Security Center Ticket APIs `. - ''' + """ return TicketAPI(self) - + @property def users(self): """ diff --git a/tenable/sc/hosts.py b/tenable/sc/hosts.py index 7fbedecaf..4cd976f68 100644 --- a/tenable/sc/hosts.py +++ b/tenable/sc/hosts.py @@ -3,7 +3,7 @@ ===== The following methods allow for interaction with the Tenable Security Center -:sc-api:`Hosts ` API. These items are typically seen under the +:sc-api:`Hosts ` API. These items are typically seen under the **Hosts** section of Tenable Security Center. Methods available on ``sc.hosts``: @@ -36,7 +36,7 @@ def list( return_json: bool = False, ) -> Union[HostsResultsIterator, Dict]: """ - Retreive the list of hosts from the system. + Retrieve the list of hosts from the system. Args: fields (list[str], optional): @@ -55,10 +55,9 @@ def list( Response: The response will be either the HostResultsIterator to handle pagination of the data (preferred) or the raw response from the - api (if return_json is set to `True`). + API (if return_json is set to `True`). Examples: - >>> for host in sc.hosts.list(): ... print(host) """ @@ -112,7 +111,7 @@ def search( return_json: bool = False, ) -> Union[HostsResultsIterator, Dict]: """ - Retreive the list of hosts from the system. + Retrieve the list of hosts from the system. Args: filters (list[tuple[str, str, str]], optional): @@ -136,7 +135,7 @@ def search( Response: The response will be either the HostResultsIterator to handle pagination of the data (preferred) or the raw response from the - api (if return_json is set to `True`). + API (if return_json is set to `True`). Examples: @@ -201,7 +200,7 @@ def update_acr( ) -> Dict: """ Override the Asset Criticality Rating (ACR) score and the reasons for the - specified Host + specified host. Args: host_uuid (str): The Host UUID to modify diff --git a/tenable/sc/report_definition.py b/tenable/sc/report_definition.py index 629637a9b..47a2bbe00 100644 --- a/tenable/sc/report_definition.py +++ b/tenable/sc/report_definition.py @@ -1,6 +1,6 @@ -''' +""" Reports Definition -============ +================== The following methods allow for interaction into the Tenable.sc :sc-api:`ReportsDefinition ` API. @@ -10,12 +10,14 @@ .. rst-class:: hide-signature .. autoclass:: ReportDefinitionAPI :members: -''' +""" + from .base import SCEndpoint + class ReportDefinitionAPI(SCEndpoint): def launch(self, id): - ''' + """ Launches a Report definition. :sc-api:`report-definition: launch ` Args: @@ -27,7 +29,8 @@ def launch(self, id): >>> running = sc.report_definition.launch(1) >>> print('The Scan Result ID is {}'.format( ... running['scanResult']['id'])) - ''' + """ - return self._api.post('reportDefinition/{}/launch'.format( - self._check('id', id, int))).json()['response'] + return self._api.post( + 'reportDefinition/{}/launch'.format(self._check('id', id, int)) + ).json()['response'] diff --git a/tenable/sc/tickets.py b/tenable/sc/tickets.py index 3d01d14b7..d7fdfc4ab 100644 --- a/tenable/sc/tickets.py +++ b/tenable/sc/tickets.py @@ -1,25 +1,27 @@ -''' -tickets -===== +""" +Tickets +======= + The following methods allow for interaction into the Tenable.sc :sc-api:`Ticket ` API. These items are typically seen under the Worklow --> Tickets section of Tenable.sc. Methods available on ``sc.tickets``: + .. rst-class:: hide-signature .. autoclass:: TicketAPI - .. automethod:: create - .. automethod:: details - .. automethod:: edit - .. automethod:: list - Note: you cannot delete tickets, must set them to resolved and they will be auto-purged via system configured retention period -''' + :members: + +Note: you cannot delete tickets, must set them to resolved and they will be auto-purged via system configured retention period +""" + from .base import SCEndpoint + class TicketAPI(SCEndpoint): def _constructor(self, **kw): - ''' + """ Handles parsing the keywords and returns a ticket document - ''' + """ # Validate as dict and pass to assignee if 'assignee' in kw: @@ -60,8 +62,8 @@ def _constructor(self, **kw): 'Bad Credentials', 'Unauthorized Software', 'Unauthorized System', - 'Unauthorized User' - ] + 'Unauthorized User', + ], ) if 'status' in kw: @@ -76,15 +78,16 @@ def _constructor(self, **kw): 'More Information', 'Not Applicable', 'Duplicate', - 'Closed' - ] + 'Closed', + ], ) return kw def create(self, name, assignee, **kw): - ''' + """ Creates a ticket. :sc-api:`ticket: create ` + Args: name (str): Required: The name for the ticket @@ -102,33 +105,38 @@ def create(self, name, assignee, **kw): Optional list of IDs of queries to associate with the ticket query (object, optional): Optional query object + Returns: :obj:`dict`: The newly created ticket. + Examples: >>> ticket = sc.tickets.create('Example Ticket', {'id':1}, status='assigned', classification='information', description='This is an example ticket', notes='Example notes') - ''' + """ kw['name'] = name kw['assignee'] = assignee payload = self._constructor(**kw) return self._api.post('ticket', json=payload).json()['response'] def details(self, id, fields=None): - ''' + """ Returns the details for a specific ticket. :sc-api:`ticket: details ` + Args: - id (int): + id (int): Required: the unique identifier for the ticket to be returned - fields (list): + fields (list): An optional list of attributes to return. + Returns: :obj:`dict`: The ticket resource record. + Examples: >>> ticket = sc.tickets.details(1) >>> pprint(ticket) - ''' + """ params = {} if fields: params['fields'] = ','.join([self._check('field', f, str) for f in fields]) @@ -136,9 +144,10 @@ def details(self, id, fields=None): return self._api.get(f'ticket/{ticket_id}', params=params).json()['response'] def edit(self, id, **kw): - ''' + """ Edits a ticket. :sc-api:`ticket: edit ` + Args: id (int): Required: unique identifier of the ticket to be edited @@ -162,30 +171,33 @@ def edit(self, id, **kw): Returns: :obj:`dict`: The newly updated ticket. + Examples: >>> ticket = sc.tickets.edit(1, status='Resolved', notes='ran updates') - ''' + """ payload = self._constructor(**kw) ticket_id = self._check('id', id, int) return self._api.patch(f'ticket/{ticket_id}', json=payload).json()['response'] def list(self, fields=None): - ''' + """ Outputs a dictionary of usable and manageable tickets, within which is a list of tickets. :sc-api:`ticket: list ` + Args: fields (list): Optional list of attributes to return for each ticket, e.g. ["name","description"]. If not specified, only a list of ticket IDs will return + Returns: :obj:`dict`: A dictionary with two lists of ticket resources. + Examples: >>> for ticket in sc.tickets.list(): ... pprint(ticket) - ''' + """ params = {} if fields: - params['fields'] = ','.join([self._check('field', f, str) - for f in fields]) + params['fields'] = ','.join([self._check('field', f, str) for f in fields]) return self._api.get('ticket', params=params).json()['response'] diff --git a/tenable/tenableone/attack_path/vectors/api.py b/tenable/tenableone/attack_path/vectors/api.py index 3b8bd6395..0456cc9bc 100644 --- a/tenable/tenableone/attack_path/vectors/api.py +++ b/tenable/tenableone/attack_path/vectors/api.py @@ -8,13 +8,6 @@ .. rst-class:: hide-signature .. autoclass:: VectorsAPI :members: - -.. toctree:: - :hidden: - :glob: - - findings/index - vectors/index """ from copy import copy