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]¶

Initiate an asset export.

API Documentation

Parameters:

last_scan_id – Scan uuid of the scan to be exported.
created_at – Assets created after this timestamp will be returned.
deleted_at – Assets deleted after this timestamp will be returned.
first_scan_time – Assets with a first_scan time later that this timestamp will be returned.
last_assessed – Assets last scanned after this timestamp will be returned.
last_authenticated_scan_time – Assets last scanned with an authenticated scan after this timestamp will be returned.
terminated_at – Assets terminated after this timestamp will be returned.
updated_at – Assets updated after this timestamp will be returned.
has_plugin_results – Should assets only be returned if they have plugin results?
is_deleted – Should we return only assets that have been deleted?
is_licensed – Should we return only assets that are licensed?
is_terminated – Should we return assets that have been terminated?
servicenow_sysid – Should we return assets that have a ServiceNOW sysid? if True only assets with an id will be returned. if False only assets without an id will be returned.
include_open_ports – Should we include open ports of assets in the exported chunks?
chunk_size – How many asset objects should be returned per chunk of data?
network_id – Only assets within the specified network UUID will be returned.
sources – 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 – A predefined export UUID to use for generating an ExportIterator. Using this parameter will ignore all of the filter arguments.
when_done – 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 – 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 – Supports overloading the iterator class to be used to process the datachunks. If set to None, then the job UUID will be returned instead of an iterator.
adopt_existing – Should we automatically adopt an existing Job UUID with we receive a 409 conflict?

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')]
... )

Initiate an asset v2 export.

API Documentation

Parameters:

last_scan_id – Scan uuid of the scan to be exported.
created_at – Assets created after this timestamp will be returned.
deleted_at – Assets deleted after this timestamp will be returned.
first_scan_time – Return Assets with a first_scan time later that this timestamp will.
last_assessed – Assets last scanned after this timestamp will be returned.
last_authenticated_scan_time – Return Assets last scanned with an authenticated scan after this timestamp.
terminated_at – Assets terminated after this timestamp will be returned.
updated_at – Assets updated after this timestamp will be returned.
has_plugin_results – Should assets only be returned if they have plugin results?
is_deleted – Should we return only assets that have been deleted?
is_licensed – Should we return only assets that are licensed?
is_terminated – Should we return assets that have been terminated?
servicenow_sysid – Should we return assets that have a ServiceNOW sysid? If True only assets with an id will be returned. If False only assets without an id will be returned.
include_open_ports – Should we include open ports of assets in the exported chunks?
chunk_size – How many asset objects should be returned per chunk of data?
network_id – Only assets within the specified network UUID will be returned.
sources – Only assets with a source matching one of these source values will be returned. Note that this value is case-sensitive.
types – Only assets with specified type will be returned.
since – Returns all assets that were updated, deleted, or terminated since the specified date regardless of state. The timestamp is specified in seconds since epoc (unix timestamp).
uuid – A predefined export UUID to use for generating an ExportIterator. Using this parameter will ignore all of the filter arguments.
when_done – 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 – 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 o be processed, the timeout is ignored.
iterator – Supports overloading the iterator class to be used to process the datachunks. If set to None, then the job UUID will be returned instead of an iterator.
adopt_existing – Should we automatically adopt an existing Job UUID with we receive a 409 conflict?

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) → 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:

str

Example

>>> tio.exports.cancel('vuln', '{UUID}')
'CANCELLED'

Initiate a compliance export.

API Documentation

Parameters:

asset – A list of assets to return compliance results for.
first_seen – Returns findings with a first seen time newer than the specified unix timestamp.
last_seen – Returns findings with a last seen time newer than the specified unix timestamp.
ipv4_addresses – Returns Compliance findings found for the provided list of ipv4 addresses.
ipv6_addresses – Returns Compliance findings found for the provided list of ipv6 addresses.
plugin_name – Returns Compliance findings for the specified list of plugin names.
plugin_id – Returns Compliance findings for the specified list of plugin IDs.
audit_name – Restricts compliance findings to those associated with the specified audit.
audit_file_name – Restricts compliance findings to those associated with the specified audit file name.
compliance_results – Restricts compliance findings to those associated with the specified list of compliance results, such as PASSED, FAILED, SKIPPED, ERROR, UNKNOWN etc.
last_observed – Restricts compliance findings to those that were last observed on or after the specified unix timestamp.
indexed_at – Restricts compliance findings to those that were updated or indexed into Tenable Vulnerability Management on or after the specified unix timestamp.
since – 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 – Restricts compliance findings to those associated with the provided list of states, such as open, reopened and fixed.
tags – A list of tag pairs to filter the results on. The tag pairs should be presented as ('CATEGORY', ['VALUE']).
network_id – Returns Compliance findings for the specified network ID.
num_findings – The number of findings to return per chunk of data.
uuid – A predefined export UUID to use for generating an ExportIterator. Using this parameter will ignore all of the filter arguments.
when_done – 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 – 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 – Supports overloading the iterator class to be used to process the datachunks. If set to None, then the job ID will be returned instead of an iterator.
adopt_existing – Should we automatically adopt an existing Job UUID with we receive a 409 conflict?

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) → list[dict[str, Any]][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.

Example

>>> chunk = tio.exports.download_chunk('vulns', '{UUID}', 1)

initiate_export(export_type: ~typing.Literal['vulns', 'assets', 'compliance', 'was'], *, version: str | None = None, when_done: bool = False, iterator: ~typing.Type[~tenable.io.exports.iterator.ExportsIterator] | None = <class 'tenable.io.exports.iterator.ExportsIterator'>, timeout: int | None = None, export_uuid: ~uuid.UUID | None = None, uuid: ~uuid.UUID | None = None, adopt_existing: bool = True, **payload) → UUID[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.

Deprecated since version 1.9.0: This method duplicates functionality that has existed within the bespoke export methods since 1.4.x. Thereforce this method has been flagged for removal. Please switch to using the appropriate export method and pass iterator=None in order to return a UUID instead of ExportIterator.

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) → dict[str, Any][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')

status(export_type: Literal['vulns', 'assets', 'compliance', 'was'], export_uuid: UUID, version: str | None = None) → dict[str, Any][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:

export_type (str) – The datatype of the export job.
export_uuid (str) – The UUID of the export job.
version – The export type version.

Examples

>>> status = tio.exports.status('vulns', '{UUID}')

vulns(*, num_assets: int = 500, include_unlicensed: bool = True, since: ~datetime.datetime | int | None = None, first_found: ~datetime.datetime | int | None = None, first_seen: ~datetime.datetime | int | None = None, last_found: ~datetime.datetime | int | None = None, last_seen: ~datetime.datetime | int | None = None, last_fixed: ~datetime.datetime | int | None = None, resurfaced_date: ~datetime.datetime | int | None = None, indexed_at: ~datetime.datetime | int | None = None, time_taken_to_fix: dict[str, int] | None = None, cvss4_base_score: dict[str, float] | None = None, epss_score: dict[str, float] | None = None, cidr_range: ~ipaddress.IPv4Network | str | None = None, cve_id: list[str] | None = None, cve_category: list[~typing.Literal['cisa known exploitable', 'emerging threats', 'in the news', 'persistently exploited', 'ransomware', 'recent active exploitation', 'top 50 vpr']] | None = None, exploit_maturity: list[~typing.Literal['high', 'functional', 'poc', 'unproven']] | None = None, initiative_id: ~uuid.UUID | str | None = None, network_id: ~uuid.UUID | str | None = None, plugin_family: list[str] | None = None, plugin_id: list[int] | None = None, plugin_type: str | None = None, scan_uuid: ~uuid.UUID | str | None = None, severity: list[~typing.Literal['info', 'low', 'medium', 'high', 'critical']] | None = None, severity_modification_type: list[~typing.Literal['NONE', 'ACCEPTED', 'RECASTED']] | None = None, state: list[~typing.Literal['OPEN', 'REOPENED', 'FIXED']] | None = None, source: list[str] | None = None, vpr_score: dict[str, float] | None = None, vpr_v2_score: dict[str, float] | None = None, vpr_threat_intensity: list[~typing.Literal['very high', 'high', 'medium', 'low', 'very low']] | None = None, weaponization: list[~typing.Literal['apt', 'botnet', 'malware', 'ransomware', 'rootkit']] | None = None, tags: list[tuple[str, list[str] | str]] | None = None, uuid: ~uuid.UUID | str | None = None, timeout: int | None = None, when_done: bool = False, adopt_existing: bool = True, iterator: ~typing.Type[~tenable.io.exports.iterator.ExportsIterator] | None = <class 'tenable.io.exports.iterator.ExportsIterator'>) → ExportsIterator | UUID[source]¶

Initiate a vulnerability export.

API Documentation

Parameters:

first_found – Findings first discovered after this timestamp will be returned.
indexed_at – Findings indexed into Tenable Vulnerability Management after this timestamp will be returned.
last_fixed – 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 – Findings last observed after this timestamp will be returned.
since – Findings last observed in any state after this timestamp will be returned. Cannot be used with last_found, first_found, or last_fixed.
resurfaced_date – Returns findings that have been resurfaced on or after this datetime.
time_taken_to_fix – Returns findings based on how long that it took the organization to resolve. The export will only inclucled FIXED findings when this filter is applied. Supported keys are lte for Less Than or Equal to or gte for Greater Than or Equal to. The values should be in seconds.
plugin_family – Only return findings from the specified plugin families.
plugin_id – Only return findings from the specified plugin ids.
plugin_type – Only return findings with the specified plugin type.
scan_uuid – Only return findings with the specified scan UUID.
source – Only return vulnerabilities for assets that have the specified scan source.
severity_modification_type – Only return vulnerabilities with the specified severity modification type.
severity – Only return findings with the specified severities.
state – Only return findings with the specified states.

vpr_score –

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 – Only findings within the specified network UUID will be returned.
cidr_range – Restrict the export to only vulns assigned to assets within the CIDR range specified.
tags – A list of tag pairs to filter the results on. The tag pairs should be presented as ('CATEGORY', 'VALUE').
include_unlicensed – Should findings for unlicensed assets that be included in the results?
num_assets – As findings are grouped by asset, how many assets’s findings should exist within each data chunk?
uuid – A predefined export UUID to use for generating an ExportIterator. Using this parameter will ignore all of the filter arguments.
when_done – 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 – 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 – Supports overloading the iterator class to be used to process the datachunks. If set to None, then the job ID will be returned instead of an iterator.
adopt_existing – Should we automatically adopt an existing Job UUID with we receive a 409 conflict?
cve_id – Returns findings that match the specified CVE IDs.
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.
exploit_maturity – Returns findings that match the specified exploit maturity. Tenable assigns exploit maturity values to vulnerabilities based on the availability and sophistication of exploit code. Supported values are high, functional, poc, unproven.
vpr_threat_intensity – Returns findings that match the specified threat intensity. The threat intensity of a vulnerability is based onf the number and frequency of recently observed events. Supported values are very high, high, medium, low, very low.
weaponization – Returns findings that match the specified weaponizations. Weaponized vulnerabilities are vulnerabilities that are ready for use in a particular type of attack. Supported values are apt, botnet, malware, ransomware, rootkit.

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(*, num_assets: int = 500, include_unlicensed: bool = True, since: ~datetime.datetime | int | None = None, first_found: ~datetime.datetime | int | None = None, last_fixed: ~datetime.datetime | int | None = None, last_found: ~datetime.datetime | int | None = None, indexed_at: ~datetime.datetime | int | None = None, asset_uuid: list[~uuid.UUID | str] | None = None, asset_name: str | None = None, cvss4_base_score: dict[str, float] | None = None, epss_score: dict[str, float] | None = None, ipv4s: list[~ipaddress.IPv4Address | str] | None = None, owasp_2010: list[~typing.Literal['A1', 'A2', 'A3', 'A4', 'A5', 'A6', 'A7', 'A8', 'A9', 'A10']] | None = None, owasp_2013: list[~typing.Literal['A1', 'A2', 'A3', 'A4', 'A5', 'A6', 'A7', 'A8', 'A9', 'A10']] | None = None, owasp_2017: list[~typing.Literal['A1', 'A2', 'A3', 'A4', 'A5', 'A6', 'A7', 'A8', 'A9', 'A10']] | None = None, owasp_2021: list[~typing.Literal['A1', 'A2', 'A3', 'A4', 'A5', 'A6', 'A7', 'A8', 'A9', 'A10']] | None = None, owasp_api_2019: list[~typing.Literal['API1', 'API2', 'API3', 'API4', 'API5', 'API6', 'API7', 'API8', 'API9', 'API10']] | None = None, plugin_ids: list[int] | None = None, severity: list[~typing.Literal['info', 'low', 'medium', 'high', 'critical']] | None = None, severity_modification_type: list[~typing.Literal['NONE', 'ACCEPTED', 'RECASTED']] | None = None, state: list[~typing.Literal['OPEN', 'REOPENED', 'FIXED']] | None = None, vpr_score: dict[str, float] | None = None, vpr_v2_score: dict[str, float] | None = None, uuid: ~uuid.UUID | str | None = None, timeout: int | None = None, when_done: bool = False, adopt_existing: bool = True, iterator: ~typing.Type[~tenable.io.exports.iterator.ExportsIterator] | None = <class 'tenable.io.exports.iterator.ExportsIterator'>) → ExportsIterator | UUID[source]¶

Initiate a WAS vulnerability export. API Documentation

Parameters:

first_found – Findings first discovered after this timestamp will be returned.
indexed_at – Findings indexed after this timestamp will be returned.
last_fixed – 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 – Findings last observed after this timestamp will be returned.
since – Findings last observed in any state after this timestamp will be returned. Cannot be used with last_found, first_found, or last_fixed.
plugin_ids – Only return findings from the specified plugin ids.
asset_uuid – Only return findings for the assets with specific asset-uuids.
asset_name – Only return findings for the asset with given name.
owasp_2010 – A list of chapters from the OWASP Categories 2010 report for which you want to filter findings returned in the findings export.
owasp_2013 – A list of chapters from the OWASP Categories 2013 report for which you want to filter findings returned in the findings export.
owasp_2017 – A list of chapters from the OWASP Categories 2017 report for which you want to filter findings returned in the findings export.
owasp_2021 – 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 – 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 – Only return vulnerabilities with the specified modification type.
severity – Only return findings with the specified severities.
state – Only return findings with the specified states.

vpr_score –

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.

ipv4s – Restrict the export to only vulns assigned to assets with specific ip-addresses.
include_unlicensed – Should findings for assets that are not licensed be included in the results?
num_assets – As findings are grouped by asset, how many assets’ findings should exist within each data chunk.
uuid – A predefined export UUID to use for generating an ExportIterator. Using this parameter will ignore all the filter arguments.
when_done – 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 – 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 – Supports overloading the iterator class to be used to process the datachunks. If set to None, then the job ID will be returned instead of an iterator.
adopt_existing – Should we automatically adopt an existing Job UUID with we receive a 409 conflict?

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( … since=int(arrow.now().shift(days=-1).timestamp()) … )

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.

boxify: bool = False¶: Should items be returned as box objects?

cancel() → None[source]¶: Cancels the current export

chunk_id: int | None = None¶: Id of the chunk currently being processed.

chunks: list[int]¶: Current list of available chunks.

count: int = 0¶: Number of objects processed so far within the current page (chunk).

next()[source]¶: Get the next item in the current page

page_count: int = 0¶: Number of pages (chunks) processed so far across the entire export job.

processed: list[int]¶: Chunks that have already been processed.

run_threaded(func: Callable, kwargs: dict[str, Any] | None = None, num_threads: int = 2) → list[Future][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)

start_time: int¶: Export job start time (unix timestamp).

status: str¶: Export job status.

timeout: int | None = None¶: Max seconds to wait in pending before cancelling the job.

type: str¶: Export job type.

uuid: str¶: Export job id.

version: str¶: Export job version.