'''
Findings V3 endpoints
=====================
The following methods allow for interaction into the Tenable.io
:devportal:`findings <io-v3-uw-vulnerabilities-search>` API.
Methods available on ``tio.v3.explore.findings``:
.. rst-class:: hide-signature
.. autoclass:: FindingsAPI
:members:
'''
import warnings
from typing import Union
from requests import Response
from tenable.io.v3.base.endpoints.explore import ExploreBaseEndpoint
from tenable.io.v3.base.iterators.explore_iterator import (CSVChunkIterator,
SearchIterator)
[docs]class FindingsAPI(ExploreBaseEndpoint):
'''
API class containing all the methods related to Findings.
Tenable.io Findings V3 APIs are deprecated. Tenable recommends that you use `tio.exports.vulns()`,
which is the equivalent V2 API for `search_host()`.
'''
_path = 'api/v3/findings/vulnerabilities'
_conv_json = True
[docs] def search_webapp(self,
**kw
) -> Union[SearchIterator, CSVChunkIterator, Response]:
'''
Search and retrieve the WAS Vulnerabilities based on supported conditions.
Tenable.io Findings V3 APIs are deprecated and must no longer be used.
Args:
fields (list, optional):
The list of field names to return from the Tenable API.
Example:
>>> ['field1', 'field2']
filter (tuple, dict, optional):
A nestable filter object detailing how to filter the results
down to the desired subset.
Examples:
>>> ('or', ('and', ('test', 'oper', '1'),
... ('test', 'oper', '2')
... ),
... 'and', ('test', 'oper', 3)
... )
>>> {
... 'or': [{
... 'and': [{
... 'value': '1',
... 'operator': 'oper',
... 'property': '1'
... },
... {
... 'value': '2',
... 'operator': 'oper',
... 'property': '2'
... }
... ]
... }],
... 'and': [{
... 'value': '3',
... 'operator': 'oper',
... 'property': 3
... }]
... }
sort (list[tuple], optional):
A list of dictionaries describing how to sort the data
that is to be returned.
Examples:
>>> [('field_name_1', 'asc'),
... ('field_name_2', 'desc')]
limit (int, optional):
Number of objects to be returned in each request.
Default and max_limit is 200.
next (str, optional):
The pagination token to use when requesting the next page of
results. This token is presented in the previous response.
return_resp (bool, optional):
If set to true, will override the default behavior to return
a requests.Response Object as is to the user.
return_csv (bool, optional):
If set to true, it will return the CSV response or
iterable (based on return_resp flag). Iterator returns all
rows in text/csv format for each call with row headers.
Returns:
Iterable:
The iterable that handles the pagination for the job.
requests.Response:
If ``return_resp`` is set to ``True``, then a response
object is returned instead of an iterable.
Examples:
>>> tio.v3.explore.findings.search_webapp(
... fields=['finding_id'], limit=2)
'''
warnings.warn("Tenable.io Findings V3 APIs are deprecated and must no longer be used.")
iclass = SearchIterator
if kw.get('return_csv', False):
iclass = CSVChunkIterator
return super()._search(iterator_cls=iclass,
sort_type=self._sort_type.property_based,
resource='findings',
api_path=f'{self._path}/webapp/search',
**kw
)
[docs] def search_cloud_resource(self,
**kw
) -> Union[SearchIterator, CSVChunkIterator, Response]:
'''
Search and retrieve the Cloud Resource Vulnerabilities based on supported conditions.
Tenable.io Findings V3 APIs are deprecated and must no longer be used.
Args:
fields (list, optional):
The list of field names to return from the Tenable API.
Example:
>>> ['field1', 'field2']
filter (tuple, dict, optional):
A nestable filter object detailing how to filter the results
down to the desired subset.
Examples:
>>> ('or', ('and', ('test', 'oper', '1'),
... ('test', 'oper', '2')
... ),
... 'and', ('test', 'oper', 3)
... )
>>> {
... 'or': [{
... 'and': [{
... 'value': '1',
... 'operator': 'oper',
... 'property': '1'
... },
... {
... 'value': '2',
... 'operator': 'oper',
... 'property': '2'
... }
... ]
... }],
... 'and': [{
... 'value': '3',
... 'operator': 'oper',
... 'property': 3
... }]
... }
sort (list[tuple], optional):
A list of dictionaries describing how to sort the data
that is to be returned.
Examples:
>>> [('field_name_1', 'asc'),
... ('field_name_2', 'desc')]
limit (int, optional):
Number of objects to be returned in each request.
Default and max_limit is 200.
next (str, optional):
The pagination token to use when requesting the next page of
results. This token is presented in the previous response.
return_resp (bool, optional):
If set to true, will override the default behavior to return
a requests.Response Object as is to the user.
return_csv (bool, optional):
If set to true, it will return the CSV response or
iterable (based on return_resp flag). Iterator returns all
rows in text/csv format for each call with row headers.
Returns:
Iterable:
The iterable that handles the pagination for the job.
requests.Response:
If ``return_resp`` is set to ``True``, then a response
object is returned instead of an iterable.
Examples:
>>> tio.v3.explore.findings.search_cloud_resource(
... fields=['risk_factor_num','last_found_time'], limit=2)
'''
warnings.warn("Tenable.io Findings V3 APIs are deprecated and must no longer be used.")
iclass = SearchIterator
if kw.get('return_csv', False):
iclass = CSVChunkIterator
return super()._search(iterator_cls=iclass,
sort_type=self._sort_type.property_based,
resource='findings',
api_path=f'{self._path}/cloud_resource/search',
**kw
)
[docs] def search_host(self,
**kw
) -> Union[SearchIterator, CSVChunkIterator, Response]:
'''
Search and retrieve the Host Vulnerabilities based on supported conditions.
Tenable.io Findings V3 APIs are deprecated. Tenable recommends that you use the `tio.exports.vulns()` method instead.
Args:
fields (list, optional):
The list of field names to return from the Tenable API.
Example:
>>> ['field1', 'field2']
filter (tuple, dict, optional):
A nestable filter object detailing how to filter the results
down to the desired subset.
Examples:
>>> ('or', ('and', ('test', 'oper', '1'),
... ('test', 'oper', '2')
... ),
... 'and', ('test', 'oper', 3)
... )
>>> {
... 'or': [{
... 'and': [{
... 'value': '1',
... 'operator': 'oper',
... 'property': '1'
... },
... {
... 'value': '2',
... 'operator': 'oper',
... 'property': '2'
... }
... ]
... }],
... 'and': [{
... 'value': '3',
... 'operator': 'oper',
... 'property': 3
... }]
... }
sort (list[tuple], optional):
A list of dictionaries describing how to sort the data
that is to be returned.
Examples:
>>> [('field_name_1', 'asc'),
... ('field_name_2', 'desc')]
limit (int, optional):
Number of objects to be returned in each request.
Default and max_limit is 200.
next (str, optional):
The pagination token to use when requesting the next page of
results. This token is presented in the previous response.
return_resp (bool, optional):
If set to true, will override the default behavior to return
a requests.Response Object as is to the user.
return_csv (bool, optional):
If set to true, it will return the CSV response or
iterable (based on return_resp flag). Iterator returns all
rows in text/csv format for each call with row headers.
Returns:
Iterable:
The iterable that handles the pagination for the job.
requests.Response:
If ``return_resp`` is set to ``True``, then a response
object is returned instead of an iterable.
Examples:
>>> tio.v3.explore.findings.search_host(
... fields=['finding_id'], limit=2)
'''
warnings.warn("Tenable.io Findings V3 APIs are deprecated. Tenable recommends that you use the `tio.exports.vulns()` method instead.")
iclass = SearchIterator
if kw.get('return_csv', False):
iclass = CSVChunkIterator
return super()._search(iterator_cls=iclass,
sort_type=self._sort_type.property_based,
resource='findings',
api_path=f'{self._path}/host/search',
**kw
)