Merge branch 'master' into feature/NNM-Module

.github/workflows/testing.yml

@@ -11,7 +11,7 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        python-version: ["3.6", "3.7", "3.8", "3.9", "3.10"]
+        python-version: ["3.7", "3.8", "3.9", "3.10", "3.11"]
     steps:
       - uses: actions/checkout@v2
       - name: Set up Python ${{ matrix.python-version }}

.gitignore

@@ -21,3 +21,4 @@ __pycache__
 /pyTenable.egg-info
 Jenkinsfile
 /ex_*.py
+.idea

CHANGELOG.md

@@ -4,6 +4,82 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.4.12]
+
+### Added
+- Support for Python 3.11
+
+### Fixed
+- `tsc.analysis.scan(1)` not honoring Scan ID with Tenable.sc 6.0.0.
+- pyTenable crashes when pagination key with a null value is in the HTTP response in Tenable.io v3 APIs.
+
+[1.4.12]: https://github.com/tenable/pyTenable/compare/1.4.11...1.4.12
+
+## [1.4.11]
+
+### Added
+- Support for Scan UUID (`last_scan_id`) filter for assets exports.
+
+[1.4.11]: https://github.com/tenable/pyTenable/compare/1.4.10...1.4.11 
+
+## [1.4.10]
+
+### Added
+- Support for `scan_uuid` filter for vulnerability exports.
+
+### Fixed
+- Bug in `tenable/io/scanners.py` that invoked the `/settings/{}` endpoint instead of the correct `/scanners/{}` endpoint.
+- Error in the documentation of the `sc.scans.edit()` method. The property - `policy` was renamed to `policy_id`.
+- tests module getting into the pypi package. Now, the module will no longer be part of pypi package.
+
+### Removed
+- `plugin_id` param from the `sc.scans.create()` method as it is no longer supported by Tenable.sc.
+- Python 3.6 references from all documentation.
+- `search_host_audit()` method from `io/v3/explore/findings`.
+
+[1.4.10]: https://github.com/tenable/pyTenable/compare/1.4.9...1.4.10 
+
+## [1.4.9]
+### Added
+
+- Support for initiating exports (and getting the export UUID).
+- Support for Tenable.ot plugins, events, more support for asset details.
+
+### Fixed
+
+- Bug in `tio.scans.results()` fixed to pass `history_id` and `history_uuid`.
+
+### Changed
+
+- Refactored Tenable.ot session client.
+
+### Removed
+
+- Support for Python Version 3.6.
+
+
+ [1.4.9]: https://github.com/tenable/pyTenable/compare/1.4.8...1.4.9 
+
+## [1.4.8]
+### Added
+
+- Support for Role Based Access Control endpoints.
+- Support for specifying Agent UUIDs instead of numeric IDs for bulk group addition.
+
+[1.4.8]: https://github.com/tenable/pyTenable/compare/1.4.7...1.4.8 
+
+## [1.4.7]
+### Added
+
+- Added support for querying v3 Findings for Hosts, Cloud Resources, Web Applications and Host Audits modules. #592 #595
+- Added support for querying v3 Assets data for Hosts, Cloud Resources, and Web Applications modules. #592 #594
+
+### Fixed
+
+- Fixed Tenable.io - Tags example #590
+- Fixed Nessus import issue #589
+
+[1.4.7]: https://github.com/tenable/pyTenable/compare/1.4.6...1.4.7
 
 ## [1.4.6]
 ### Added

README.rst

@@ -5,7 +5,7 @@ Welcome to pyTenable's documentation!
    :target: https://github.com/tenable/pyTenable/actions
 .. image:: https://img.shields.io/pypi/v/pytenable.svg
    :target: https://pypi.org/project/pyTenable/
-.. image:: https://img.shields.io/badge/python-3.6%203.7%203.8%203.9-blue
+.. image:: https://img.shields.io/badge/python-3.7%203.8%203.9%203.10%203.11-blue
    :target: https://pypi.org/project/pyTenable/
 .. image:: https://img.shields.io/pypi/dm/pytenable
    :target: https://github.com/tenable/pytenable

docs/api/io/v3/access_control.rst

@@ -0,0 +1 @@
+.. automodule:: tenable.io.v3.access_control

docs/api/io/v3/explore/assets.rst

@@ -0,0 +1 @@
+.. automodule:: tenable.io.v3.explore.assets.api

docs/api/io/v3/explore/findings.rst

@@ -0,0 +1 @@
+.. automodule:: tenable.io.v3.explore.findings.api

docs/api/io/v3/explore/index.rst

@@ -0,0 +1 @@
+.. automodule:: tenable.io.v3.explore

docs/api/io/v3/index.rst

@@ -0,0 +1 @@
+.. automodule:: tenable.io.v3

docs/api/ot/events.rst

@@ -0,0 +1 @@
+.. automodule:: tenable.ot.events

docs/api/ot/graphql.rst

@@ -0,0 +1 @@
+.. automodule:: tenable.ot.graphql

docs/api/ot/index.rst

@@ -1 +1,10 @@
-.. automodule:: tenable.ot.session
+Tenable.ot
+==========
+.. toctree::
+    :hidden:
+    :glob:
+
+    graphql
+    schema
+
+.. automodule:: tenable.ot

docs/api/ot/plugins.rst

@@ -0,0 +1 @@
+.. automodule:: tenable.ot.plugins

docs/api/ot/schema.rst

@@ -0,0 +1,3 @@
+Schema
+======
+.. automodule:: tenable.ot.schema

requirements.txt

@@ -1,9 +1,9 @@
 dataclasses>=0.8;python_version=="3.6"
 requests>=2.26
 python-dateutil>=2.6
-semver>=2.8.1
+semver>=2.10.0
 restfly>=1.4.5
-marshmallow>=3.6
+marshmallow>=3.8
 python-box>=4.0
 defusedxml>=0.5.0
 urllib3>=1.26.5

setup.py

@@ -1,50 +1,48 @@
 from setuptools import setup, find_packages
 import os
 
-with open('tenable/version.py', 'r') as vfile:
+with open("tenable/version.py", "r") as vfile:
     exec(vfile.read())
 
 try:
     long_description = open(
-        os.path.join(
-            os.path.abspath(os.path.dirname(__file__)),
-            'README.rst')).read()
+        os.path.join(os.path.abspath(os.path.dirname(__file__)), "README.rst")
+    ).read()
 except:
-    long_description = 'Please refer to https://pytenable.readthedocs.io'
-    print('! could not read README.rst file.')
+    long_description = "Please refer to https://pytenable.readthedocs.io"
+    print("! could not read README.rst file.")
 
 setup(
-    name='pyTenable',
+    name="pyTenable",
     version=version,  # noqa
-    description=('Python library to interface into Tenable\'s '
-                 'products and applications'
-                 ),
-    author='Tenable, Inc.',
+    description=(
+        "Python library to interface into Tenable's " "products and applications"
+    ),
+    author="Tenable, Inc.",
     long_description=long_description,
-    author_email='smcgrath@tenable.com',
-    url='https://github.com/tenable/pytenable',
-    license='MIT',
+    author_email="smcgrath@tenable.com",
+    url="https://github.com/tenable/pytenable",
+    license="MIT",
     classifiers=[
-        'Development Status :: 5 - Production/Stable',
-        'Intended Audience :: Developers',
-        'Topic :: Software Development',
-        'Topic :: Software Development :: Libraries',
-        'Topic :: Software Development :: Libraries :: Application Frameworks',
-        'License :: OSI Approved :: MIT License',
-        'Programming Language :: Python :: 3.6',
-        'Programming Language :: Python :: 3.7',
-        'Programming Language :: Python :: 3.8',
-        'Programming Language :: Python :: 3.9',
-        'Programming Language :: Python :: 3.10',
+        "Development Status :: 5 - Production/Stable",
+        "Intended Audience :: Developers",
+        "Topic :: Software Development",
+        "Topic :: Software Development :: Libraries",
+        "Topic :: Software Development :: Libraries :: Application Frameworks",
+        "License :: OSI Approved :: MIT License",
+        "Programming Language :: Python :: 3.7",
+        "Programming Language :: Python :: 3.8",
+        "Programming Language :: Python :: 3.9",
+        "Programming Language :: Python :: 3.10",
     ],
-    keywords='tenable tenable_io securitycenter containersecurity',
-    packages=find_packages(exclude=['docs', 'tests']),
+    keywords="tenable tenable_io securitycenter containersecurity",
+    packages=find_packages(exclude=["docs", "tests", "tests.*"]),
     install_requires=[
         'requests>=2.26',
         'python-dateutil>=2.6',
-        'semver>=2.8.1',
+        'semver>=2.10.0',
         'restfly>=1.4.5',
-        'marshmallow>=3.6',
+        'marshmallow>=3.8',
         'python-box>=4.0',
         'defusedxml>=0.5.0',
         'urllib3>=1.26.5',

sonar-project.properties

@@ -2,5 +2,5 @@ sonar.projectKey=tenable_pyTenable
 sonar.organization=tenable
 sonar.sources=tenable
 sonar.tests=tests
-sonar.python.version=3.6, 3.7, 3.8, 3.9, 3.10
+sonar.python.version=3.7, 3.8, 3.9, 3.10
 sonar.python.coverage.reportPaths=cov/coverage.xml

tenable/__init__.py

@@ -23,7 +23,7 @@
 
 .. note::
     pyTenable version 1.2 is the first release to drop support for Python
-    versions less than 3.6.  If you are still using any of these deprecated
+    versions less than 3.7.  If you are still using any of these deprecated
     python versions the 1.1 release will still work, however is no longer being
     actively developed or maintained.
 

tenable/io/__init__.py

@@ -40,10 +40,13 @@
     tags
     target_groups
     users
+    v3/index
     workbenches
 '''
-from typing import Dict, List, Optional
+from typing import Dict, Optional
+
 from requests import Response
+
 from tenable.base.platform import APIPlatform
 from .access_groups import AccessGroupsAPI
 from .access_groups_v2 import AccessGroupsV2API
@@ -66,15 +69,16 @@
 from .permissions import PermissionsAPI
 from .plugins import PluginsAPI
 from .policies import PoliciesAPI
+from .remediation_scans import RemediationScansAPI
 from .scanner_groups import ScannerGroupsAPI
 from .scanners import ScannersAPI
 from .scans import ScansAPI
-from .remediation_scans import RemediationScansAPI
 from .server import ServerAPI
 from .session import SessionAPI
 from .tags import TagsAPI
 from .target_groups import TargetGroupsAPI
 from .users import UsersAPI
+from .v3 import Version3API
 from .workbenches import WorkbenchesAPI
 
 
@@ -429,3 +433,12 @@ def workbenches(self):
         :doc:`Tenable.io Workbenches APIs <workbenches>`.
         '''
         return WorkbenchesAPI(self)
+
+    @property
+    def v3(self):
+        '''
+        The interface object for the
+        :doc:`Tenable.io v3 APIs <v3/index>`.
+        '''
+        return Version3API(self)
+

tenable/io/agent_groups.py

@@ -23,7 +23,7 @@ def add_agent(self, group_id, *agent_ids, **kw):
 
         Args:
             group_id (int): The id of the group
-            *agent_ids (int): The id of the agent
+            *agent_ids (int): The id or uuid of the agent.  If passing multiple, they must all be either numeric id or uuid.
             scanner_id (int, optional): The id of the scanner
 
         Returns:
@@ -40,17 +40,24 @@ def add_agent(self, group_id, *agent_ids, **kw):
             Adding multiple agents:
 
             >>> tio.agent_groups.add_agent(1, 1, 2, 3)
+
+            Adding multiple agents by uuid:
+
+            >>> tio.agent_groups.add_agent(1, 'uuid-1', 'uuid-2', 'uuid-3')
         '''
         scanner_id = 1
         if 'scanner_id' in kw:
             scanner_id = kw['scanner_id']
 
+        # we can handle either ids or uuids as the list of items.
+        useUuids = len(agent_ids) > 0 and isinstance(agent_ids[0], str)
+
         if len(agent_ids) <= 1:
             # if there is only 1 agent id, we will perform a singular add.
             self._api.put('scanners/{}/agent-groups/{}/agents/{}'.format(
                 self._check('scanner_id', scanner_id, int),
                 self._check('group_id', group_id, int),
-                self._check('agent_id', agent_ids[0], int)
+                self._check('agent_id', agent_ids[0], 'uuid' if useUuids else int)
             ))
         else:
             # If there are many agent_ids, then we will want to perform a bulk
@@ -59,7 +66,7 @@ def add_agent(self, group_id, *agent_ids, **kw):
                 'scanners/{}/agent-groups/{}/agents/_bulk/add'.format(
                     self._check('scanner_id', scanner_id, int),
                     self._check('group_id', group_id, int)),
-                json={'items': [self._check('agent_id', i, int) for i in agent_ids]}).json()
+                json={'items': [self._check('agent_id', i, 'uuid' if useUuids else int) for i in agent_ids]}).json()
 
     def configure(self, group_id, name, scanner_id=1):
         '''
@@ -173,7 +180,7 @@ def delete_agent(self, group_id, *agent_ids, **kw):
                     self._check('group_id', group_id, int)),
                 json={'items': [self._check('agent_ids', i, int) for i in agent_ids]}).json()
 
-    def details(self, group_id, scanner_id=1, *filters, **kw):
+    def details(self, group_id, *filters, **kw):
         '''
         Retrieve the details about the specified agent group.
 

tenable/io/base/schemas/filters/base.py

@@ -1,6 +1,5 @@
 from typing import Optional, Dict, List
 from marshmallow import Schema, ValidationError
-from tenable.io.base.session import TenableIO
 import re
 
 
@@ -14,7 +13,7 @@ class BaseFilterSchema(Schema):
 
     @classmethod
     def populate_filters(cls,
-                         tio: TenableIO,
+                         tio,
                          path: str,
                          envelope: str = 'filters',
                          force: bool = False,