Exports¶
The following methods allow for interaction into the Tenable Vulnerability Management exports API endpoints.
Methods available on tio.exports
:
- class ExportsAPI(api: APISession)[source]¶
- assets(**kwargs) → ExportsIterator | UUID[source]¶
Initiate an asset export.
- Parameters:
last_scan_id (str, optional) – Scan uuid of the scan to be exported.
created_at (int, optional) – Assets created after this timestamp will be returned.
deleted_at (int, optional) – Assets deleted after this timestamp will be returned.
first_scan_time (int, optional) – Assets with a first_scan time later that this timestamp will be returned.
last_assessed (int, optional) – Assets last scanned after this timestamp will be returned.
last_authenticated_scan_time (int, optional) – Assets last scanned with an authenticated scan after this timestamp will be returned.
terminated_at (int, optional) – Assets terminated after this timestamp will be returned.
updated_at (int, optional) – Assets updated after this timestamp will be returned.
has_plugin_results (bool, optional) – Should assets only be returned if they have plugin results?
is_deleted (bool, optional) – Should we return only assets that have been deleted?
is_licensed (bool, optional) – Should we return only assets that are licensed?
is_terminated (bool, optional) – Should we return assets that have been terminated?
servicenow_sysid (bool, optional) – Should we return assets that have a ServiceNOW sysid? if
True
only assets with an id will be returned. ifFalse
only assets without an id will be returned.include_open_ports (bool, optional) – Should we include open ports of assets in the exported chunks?
chunk_size (int, optional) – How many asset objects should be returned per chunk of data? The default is
1000
.network_id (str, optional) – Only assets within the specified network UUID will be returned.
sources (list[str], optional) – Only assets with a source matching one of these source values will be returned. Note that this value is case-sensitive.
tags (list[tuple[str, str]], optional) – A list of tag pairs to filter the results on. The tag pairs should be presented as
('CATEGORY', 'VALUE')
.uuid (str, optional) – A predefined export UUID to use for generating an ExportIterator. Using this parameter will ignore all of the filter arguments.
use_iterator (bool, optional) – Determines if we should return an iterator, or simply the export job UUID. The default is to return an iterator.
when_done (bool, optional) – When creating the iterator, setting this flag to true will tell the iterator to wait until the export job has completed before processing the first chunk. The default behaviour is to start processing chunks of data as soon as they become available.
timeout (int, optional) – If specified, determines a timeout in seconds to wait for the export job to sit in the queue before cancelling the job and raising a
TioExportsTimeout
error. Once a job has started to be processed, the timeout is ignored.iterator (Iterator, optional) – Supports overloading the iterator class to be used to process the datachunks.
adopt_existing (bool, optional) – Should we automatically adopt an existing Job UUID with we receive a 409 conflict? Defaults to True.
Examples
Iterating over the results of an asset export:
>>> for asset in tio.exports.assets(): ... print(asset)
Getting hosts that have been updated within the last 24 hours
>>> assets = tio.exports.assets( ... updated_at=int(arrow.now().shift(days=-1).timestamp()) ... )
Getting assets that have the the
Region:Chicago
tag:>>> assets = tio.exports.assets( ... tags=[('Region', 'Chicago')] ... )
- assets_v2(**kwargs) → ExportsIterator | UUID[source]¶
Initiate an asset v2 export.
- Parameters:
last_scan_id (str, optional) – Scan uuid of the scan to be exported.
created_at (int, optional) – Assets created after this timestamp will be returned.
deleted_at (int, optional) – Assets deleted after this timestamp will be returned.
first_scan_time (int, optional) – Assets with a first_scan time later that this timestamp will be returned.
last_assessed (int, optional) – Assets last scanned after this timestamp will be returned.
last_authenticated_scan_time (int, optional) – Assets last scanned with an authenticated scan after this timestamp will be returned.
terminated_at (int, optional) – Assets terminated after this timestamp will be returned.
updated_at (int, optional) – Assets updated after this timestamp will be returned.
has_plugin_results (bool, optional) – Should assets only be returned if they have plugin results?
is_deleted (bool, optional) – Should we return only assets that have been deleted?
is_licensed (bool, optional) – Should we return only assets that are licensed?
is_terminated (bool, optional) – Should we return assets that have been terminated?
servicenow_sysid (bool, optional) – Should we return assets that have a ServiceNOW sysid? if
True
only assets with an id will be returned. ifFalse
only assets without an id will be returned.include_open_ports (bool, optional) – Should we include open ports of assets in the exported chunks?
chunk_size (int, optional) – How many asset objects should be returned per chunk of data? The default is
1000
.network_id (str, optional) – Only assets within the specified network UUID will be returned.
sources (list[str], optional) – Only assets with a source matching one of these source values will be returned. Note that this value is case-sensitive.
types (list[str], optional) – Only assets with specified type will be returned.
since (int, optional) – Assets terminated after this timestamp will be returned.
uuid (str, optional) – A predefined export UUID to use for generating an ExportIterator. Using this parameter will ignore all of the filter arguments.
use_iterator (bool, optional) – Determines if we should return an iterator, or simply the export job UUID. The default is to return an iterator.
when_done (bool, optional) – When creating the iterator, setting this flag to true will tell the iterator to wait until the export job has completed before processing the first chunk. The default behaviour is to start processing chunks of data as soon as they become available.
timeout (int, optional) – If specified, determines a timeout in seconds to wait for the export job to sit in the queue before cancelling the job and raising a
TioExportsTimeout
error. Once a job has started to be processed, the timeout is ignored.iterator (Iterator, optional) – Supports overloading the iterator class to be used to process the datachunks.
adopt_existing (bool, optional) – Should we automatically adopt an existing Job UUID with we receive a 409 conflict? Defaults to True.
Examples
Iterating over the results of an asset export:
>>> for asset in tio.exports.assets_v2(): ... print(asset)
Getting hosts that have been updated within the last 24 hours
>>> assets = tio.exports.assets_v2( ... updated_at=int(arrow.now().shift(days=-1).timestamp()) ... )
Getting assets that have the the
host
type:>>> assets = tio.exports.assets_v2( ... types=['host'] ... )
- cancel(export_type: Literal['vulns', 'assets', 'compliance', 'was'], export_uuid: UUID, version: str | None = None, **kwargs) → str[source]¶
Cancels the specified export job.
API Documentation for cancel export jobs with assets, compliance, and vulnerabilities datatypes.
- Parameters:
export_type – The type of export job that we are to cancel.
export_uuid – The export job’s unique identifier.
version – The export type version.
- Returns:
The status of the job.
- Return type:
Example
>>> tio.exports.cancel('vuln', '{UUID}') 'CANCELLED'
- compliance(**kwargs) → ExportsIterator | UUID[source]¶
Initiate a compliance export.
- Parameters:
asset (list[str], optional) – A list of assets to return compliance results for.
first_seen (int, optional) – Returns findings with a first seen time newer than the specified unix timestamp.
last_seen (int, optional) – Returns findings with a last seen time newer than the specified unix timestamp.
ipv4_addresses (list[str], optional) – Returns Compliance findings found for the provided list of ipv4 addresses.
ipv6_addresses (list[str], optional) – Returns Compliance findings found for the provided list of ipv6 addresses.
plugin_name (list[str], optional) – Returns Compliance findings for the specified list of plugin names.
plugin_id (list[int], optional) – Returns Compliance findings for the specified list of plugin IDs.
audit_name (str, optional) – Restricts compliance findings to those associated with the specified audit.
audit_file_name (str, optional) – Restricts compliance findings to those associated with the specified audit file name.
compliance_results (list[str], optional) – Restricts compliance findings to those associated with the specified list of compliance results, such as PASSED, FAILED, SKIPPED, ERROR, UNKNOWN etc.
last_observed (int,optional) – Restricts compliance findings to those that were last observed on or after the specified unix timestamp.
indexed_at (int, optional) –
- Restricts compliance findings to those that were updated or indexed into Tenable Vulnerability Management
on or after the specified unix timestamp.
since (int, optional) – Same as indexed_at. Restricts compliance findings to those that were updated or indexed into Tenable Vulnerability Management on or after the specified unix timestamp.
state (list[str], optional) – Restricts compliance findings to those associated with the provided list of states, such as open, reopened and fixed.
tags (list[tuple[str, list[str]]], optional) – A list of tag pairs to filter the results on. The tag pairs should be presented as
('CATEGORY', ['VALUE'])
.network_id (str, optional) – Returns Compliance findings for the specified network ID.
num_findings (int) – The number of findings to return per chunk of data. If left unspecified, the default is
5000
.uuid (str, optional) – A predefined export UUID to use for generating an ExportIterator. Using this parameter will ignore all of the filter arguments.
use_iterator (bool, optional) – Determines if we should return an iterator, or simply the export job UUID. The default is to return an iterator.
when_done (bool, optional) – When creating the iterator, setting this flag to true will tell the iterator to wait until the export job has completed before processing the first chunk. The default behaviour is to start processing chunks of data as soon as they become available.
timeout (int, optional) – If specified, determines a timeout in seconds to wait for the export job to sit in the queue before cancelling the job and raising a
TioExportsTimeout
error. Once a job has started to be processed, the timeout is ignored.iterator (Iterator, optional) – Supports overloading the iterator class to be used to process the datachunks.
adopt_existing (bool, optional) – Should we automatically adopt an existing Job UUID with we receive a 409 conflict? Defaults to True.
Examples
>>> for findings in tio.exports.compliance(): ... print(finding)
- download_chunk(export_type: Literal['vulns', 'assets', 'compliance', 'was'], export_uuid: UUID, chunk_id: int, version: str | None = None, retries: int = 3, **kwargs) → List[source]¶
Downloads an export chunk from the specified job.
API Documentation for downloading an export chunk for assets, compliance, and vulnerabilities.
- Parameters:
export_type – The type of export job
export_uuid – The export job’s unique identifier.
chunk_id – The identifier for the specific chunk to download.
version – The export type version.
- Returns:
The list of objects that entail the chunk of data requested.
- Return type:
List
Example
>>> chunk = tio.exports.download_chunk('vulns', '{UUID}', 1)
- initiate_export(export_type: Literal['vulns', 'assets', 'compliance', 'was'], version: str | None = None, **kwargs)[source]¶
Initiate an export job of the specified export type, and return the export UUID.
This method accepts the key-value arguments supported by the methods assets(), vulns(), and compliance() for the matching export_type. For example, when the export_type is “assets”, this function will only support the kwargs supported by the assets() method; if export_type is “vulns”, the method will accept only those supported by the vulns() method, and so forth.
- Parameters:
export_type – The datatype of export to get the jobs for.
version – The export type version.
Examples
Initiating an assets export with no extra params.
>>> export_uuid = tio.exports.initiate_export("assets")
Initiating a vulns export with the params supported by vulns()
>>> export_uuid = tio.exports.initiate_export("vulns", timeout=10)
- jobs(export_type: Literal['vulns', 'assets', 'was'], version: str | None = None, **kwargs) → Dict[source]¶
Returns the list of jobs available for a given datatype.
API Documentation for the job listing APIs for assets, and vulnerabilities datatypes.
- Parameters:
export_type (str) – The datatype of export to get the jobs for.
version – The export type version.
Examples
>>> jobs = tio.exports.jobs('vulns')
- list_compliance_export_jobs()[source]¶
Returns a list of the last 1,000 compliance export requests along with their statuses and related metadata.
- Returns:
List of job records.
- Return type:
Examples
>>> for compliance_job in tio.exports.list_compliance_export_jobs(): ... pprint(compliance_job)
- status(export_type: Literal['vulns', 'assets', 'compliance', 'was'], export_uuid: UUID, version: str | None = None, **kwargs) → Dict[source]¶
Gets the status of the export job.
API Documentation for the status of an export job for the assets, compliance, and vulnerabilities datatypes.
- Parameters:
Examples
>>> status = tio.exports.status('vulns', '{UUID}')
- vulns(**kwargs) → ExportsIterator | UUID[source]¶
Initiate a vulnerability export.
- Parameters:
first_found (int, optional) – Findings first discovered after this timestamp will be returned.
indexed_at (int, optional) – Findings indexed into Tenable Vulnerability Management after this timestamp will be returned.
last_fixed (int, optional) – Findings fixed after this timestamp will be returned. Note that this filter only applies to fixed data and should not be used when searching for active findings.
last_found (int, optional) – Findings last observed after this timestamp will be returned.
since (int, optional) – Findings last observed in any state after this timestamp will be returned. Cannot be used with
last_found
,first_found
, orlast_fixed
.plugin_family (list[str], optional) – Only return findings from the specified plugin families.
plugin_id (list[int], optional) – Only return findings from the specified plugin ids.
plugin_type (str, optional) – Only return findings with the specified plugin type.
scan_uuid (uuid, optional) – Only return findings with the specified scan UUID.
source (list[str], optional) – Only return vulnerabilities for assets that have the specified scan source.
severity_modification_type (list[str], optional) – Only return vulnerabilities with the specified severity modification type.
severity (list[str], optional) – Only return findings with the specified severities.
state (list[str], optional) – Only return findings with the specified states.
vpr_score (dict, optional) –
Only returns findings that meet the specified VPR criteria. The filter is formatted as a dictionary with the mathematical operation as the key. Supported operations are:
Supported Operations¶ Operation
Type
Description
eq
list[float]
List of VPR scores that the findings must match.
neq
list[float]
List of VPR scores that the findings can not match.
gt
float
VPR scores must be greater than the specified value.
gte
float
VPR scores must be greater than or equal to the specified value.
lt
float
VPR scores must be less than the specified value.
lte
float
VPR scores must be less than or equal to the specified value.
network_id (str, optional) – Only findings within the specified network UUID will be returned.
cidr_range (str, optional) – Restrict the export to only vulns assigned to assets within the CIDR range specified.
tags (list[tuple[str, str]], optional) – A list of tag pairs to filter the results on. The tag pairs should be presented as
('CATEGORY', 'VALUE')
.include_unlicensed (bool, optional) – Should findings for assets that are not licensed be included in the results?
num_assets (int, optional) – As findings are grouped by asset, how many assets’s findings should exist within each data chunk? If left unspecified the default is
500
.uuid (str, optional) – A predefined export UUID to use for generating an ExportIterator. Using this parameter will ignore all of the filter arguments.
use_iterator (bool, optional) – Determines if we should return an iterator, or simply the export job UUID. The default is to return an iterator.
when_done (bool, optional) – When creating the iterator, setting this flag to true will tell the iterator to wait until the export job has completed before processing the first chunk. The default behaviour is to start processing chunks of data as soon as they become available.
timeout (int, optional) – If specified, determines a timeout in seconds to wait for the export job to sit in the queue before cancelling the job and raising a
TioExportsTimeout
error. Once a job has started to be processed, the timeout is ignored.iterator (Iterator, optional) – Supports overloading the iterator class to be used to process the datachunks.
adopt_existing (bool, optional) – Should we automatically adopt an existing Job UUID with we receive a 409 conflict? Defaults to True.
Examples
Examples:
Iterating over the results of an vuln export:
>>> for vuln in tio.exports.vulns(): ... print(vuln)
Getting findings that have been observed within the last 24 hours
>>> vulns = tio.exports.vulns( ... since=int(arrow.now().shift(days=-1).timestamp()) ... )
Getting findings that have the the
Region:Chicago
tag:>>> vulns = tio.exports.vulns( ... tags=[('Region', 'Chicago')] ... )
- was(**kwargs) → ExportsIterator | UUID[source]¶
Initiate a WAS vulnerability export. API Documentation :param first_found: Findings first discovered after this timestamp will be
returned.
- Parameters:
indexed_at (int, optional) – Findings indexed into Tenable Vulnerability Management after this timestamp will be returned.
last_fixed (int, optional) – Findings fixed after this timestamp will be returned. Note that this filter only applies to fixed data and should not be used when searching for active findings.
last_found (int, optional) – Findings last observed after this timestamp will be returned.
since (int, optional) – Findings last observed in any state after this timestamp will be returned. Cannot be used with
last_found
,first_found
, orlast_fixed
.plugin_ids (list[int], optional) – Only return findings from the specified plugin ids.
asset_uuid (list[str], optional) – Only return findings for the assets with specific asset-uuids.
asset_name (str, optional) – Only return findings for the asset with given name.
owasp_2010 (list[str], optional) – A list of chapters from the OWASP Categories 2010 report for which you want to filter findings returned in the findings export.
owasp_2013 (list[str], optional) – A list of chapters from the OWASP Categories 2013 report for which you want to filter findings returned in the findings export.
owasp_2017 (list[str], optional) – A list of chapters from the OWASP Categories 2017 report for which you want to filter findings returned in the findings export.
owasp_2021 (list[str], optional) – A list of chapters from the OWASP Categories 2021 report for which you want to filter findings returned in the findings export.
owasp_api_2019 (list[str], optional) – A list of chapters from the OWASP Categories API 2019 report for which you want to filter findings returned in the findings export.
severity_modification_type (list[str], optional) – Only return vulnerabilities with the specified severity modification type.
severity (list[str], optional) – Only return findings with the specified severities.
state (list[str], optional) – Only return findings with the specified states.
vpr_score (dict, optional) –
Only returns findings that meet the specified VPR criteria. The filter is formatted as a dictionary with the mathematical operation as the key. Supported operations are: .. list-table:: Supported Operations
- widths:
auto
- header-rows:
1
Operation
Type
Description
eq
list[float]
List of VPR scores that the findings must match.
neq
list[float]
List of VPR scores that the findings can not match.
gt
float
VPR scores must be greater than the specified value.
gte
float
VPR scores must be greater than or equal to the specified value.
lt
float
VPR scores must be less than the specified value.
lte
float
VPR scores must be less than or equal to the specified value.
ipv4s (list[str], optional) – Restrict the export to only vulns assigned to assets with specific ip-addresses.
include_unlicensed (bool, optional) – Should findings for assets that are not licensed be included in the results?
num_assets (int, optional) – As findings are grouped by asset, how many assets’ findings should exist within each data chunk? If left unspecified the default is
500
.uuid (str, optional) – A predefined export UUID to use for generating an ExportIterator. Using this parameter will ignore all the filter arguments.
use_iterator (bool, optional) – Determines if we should return an iterator, or simply the export job UUID. The default is to return an iterator.
when_done (bool, optional) – When creating the iterator, setting this flag to true will tell the iterator to wait until the export job has completed before processing the first chunk. The default behaviour is to start processing chunks of data as soon as they become available.
timeout (int, optional) – If specified, determines a timeout in seconds to wait for the export job to sit in the queue before cancelling the job and raising a
TioExportsTimeout
error. Once a job has started to be processed, the timeout is ignored.iterator (Iterator, optional) – Supports overloading the iterator class to be used to process the datachunks.
adopt_existing (bool, optional) – Should we automatically adopt an existing Job UUID with we receive a 409 conflict? Defaults to True.
Examples
Examples: Iterating over the results of a WAS vuln export: >>> from tenable.io import TenableIO >>> tio = TenableIO(“<apiKey>”, “secret”) >>> for vuln in tio.exports.was_vulns(): … print(vuln) Getting findings that have been observed within the last 24 hours >>> import arrow >>> vulns = tio.exports.was_vulns( … since=int(arrow.now().shift(days=-1).timestamp()) … ) Getting findings that have the
Region:Chicago
tag: >>> vulns = tio.exports.was_vulns( … tags=[(‘Region’, ‘Chicago’)] … )
As exports are asynchronous, pyTenable by default will return an iterator to handle the state tracking, data chunking, and presentation of the data in order to reduce the amount of boilerplate code that would otherwise have to be created. These iterators support both serial iteration and threaded handling of data depending on how the data is accessed.
- class ExportsIterator(api, **kwargs)[source]¶
The export iterator can be used to handle the downloading and processing of the data chunks from an export request.
- page_count¶
The current total count of items that have been processed on the current chunk/page.
- Type:
- run_threaded(func: Any, kwargs: Dict | None = None, num_threads: int = 2) → List[source]¶
Initiate a multi-threaded export using the provided function and keyword arguments. The following field names are reserved and must be accepted either as an optional keyword argument, or as a named param.
data (list[dict]): Receiver of the data-chunk.
export_uuid (str): Receiver for the export job UUID.
export_type (str): Receiver for the export data-type.
export_chunk_id (int): Receiver for the export chunk id.
version (int): Receiver for the export version.
- Parameters:
func – The function to pass to the thread executor.
kwargs – Any additional keyword arguments that are to be passed to the function as part of execution.
num_threads – How many concurrent threads should be run. The default is
2
.
Examples
A simple example to download the chunks and write them to disk.
>>> def write_chunk(data, ... export_uuid: str, ... export_type: str, ... export_chunk_id: int, ... version: int ... ): ... fn = f'{export_type}-{export_uuid}-{export_chunk_id}-{version}.json' ... with open(fn, 'w') as fobj: ... json.dump(data, fobj) >>> >>> export = tio.exports.vulns() >>> export.run_threaded(write_chunk, num_threads=4)