Leveraging Data Export APIs with the Tenable Python SDK

avatar guy _By Andrew Scott, Tenable Software Engineer_

🚧

Caution

Tenable is deprecating the Tenable.io Python SDK in favor of the more widely used library, pyTenable. pyTenable offers all of the same functionality as the SDK, as well as support for Tenable.sc. However, it should be noted that pyTenable functions are not compatible with SDK functions. Support for the Tenable.io Python SDK will end on August 1, 2020.

In an effort to provide our customers with all the tools they need to accurately assess and analyze their Cyber Expose gap, we have added two new APIs to Tenable.io®. With the introduction of the Vulnerability Export API and the Asset Export API, customers now have filterable, chunkable and – most importantly – unlimited access to all their asset and vulnerability data.

Managing hundreds of thousands or millions of vulnerabilities and assets is a daunting task for any security or IT administrator. While the ability to filter down to your most critical exposures is great, prior to these new APIs customers did not have a straightforward path to exfiltrate this data in a way that could easily be integrated with third-party or custom solutions.

We’re also aware that our customers do not use Tenable.io in a vacuum and many would like the ability to export their asset and vulnerability data into different products and systems to fit their own management and workflow needs. While our partner efforts have come a long way and are continuing to expand, until now this left anyone attempting to build a homegrown integration in a difficult situation.

By combining these new APIs and the existing Tenable Python SDK, we’ve opened the doors for everyone from our largest enterprise customers to individual developers to begin integrating all of Tenable.io’s rich asset and vulnerability data into their own custom solutions.

This post will give a brief overview of how to utilize both of these new APIs using the Python SDK. If you’re unfamiliar with how to get started using the Python SDK, refer to this past blog post or see the README for the project in GitHub.

Prerequisites

The examples used in the post assume:

  • Python 2.7 or 3.4-3.7 installed
  • An administrator account in Tenable.io with generated API keys
  • Existing asset/vulnerability data within Tenable.io

Exporting vulnerabilities

In the past vulnerability data has been available for exports in formats such as CSV, HTML, and PDF. While being friendly for humans, these formats are not easily digestible to for most programmatic integrations and often lack the ability to express complex structures and relationships within the data. For this reason the new Vulnerability Export API will produce easily consumable JSON. The SDK goes a step beyond this and will structure the export response as a list of vulnerability objects.

The Code

from tenable_io.client import TenableIOClient

client = TenableIOClient()

vulnerabilities = client.export_helper.download_vulns(num_assets=5000, state=['open'])

The first few lines are just import statements. If you’re planning on doing anything meaningful with the exported data you’ll likely need some additional modules, but to export your data only the SDK import is required

from tenable_io.client import TenableIOClient

The next line initializes the Tenable.io client. In the example you are manually passing in your API Keys for simplicity. This can also be done by using environment variables or an .ini file, which removes the need for hardcoded keys; always a smart idea when you can avoid it.

client = TenableIOClient(access_key='{YOUR ACCESS KEY}', secret_key='{YOUR SECRET KEY}')

The next line contains the real bulk of the export operation. Here you will use the “export_helper” “download_vulns” method to export all vulns with a state of “open” using a partition of 5,000 assets per export chunk. These values are just used here to illustrate a possible export scenario. You can find more in depth documentation of the available export options here. Generally, using larger values for “num_assets” will result in exports completing more quickly. This value is capped at 5,000. This method will handle the polling of the export API and once all chunks are available it will retrieve them all and assign them to the “vulnerabilities” as a list.

vulnerabilities = client.export_helper.download_vulns(num_assets=5000, state=['open'])

At this point all of your exported vulnerability data should exist in memory within the python program in the “vulnerabilities” variable. From here you can further filter or modify the data, do analytics, or save the data to a json file.

Exporting assets

Unlike Vulnerabilities, asset data in Tenable.io has never been readily available for export in bulk. Like the Vulnerability Export API this asset data is also exported as JSON.

The Code

from tenable_io.client import TenableIOClient

client = TenableIOClient()

assets = client.export_helper.download_assets(chunk_size=1000, has_plugin_results=True)

We won’t go through this example line-by-line as above since the code is largely the same. The notable differences here are that the “export_helper” will use the “download_assets” method this time and that you are storing the asset details in a list named “assets”. You can find more information about the available asset export options here. Similar to the description above, expanding the “chunk_size” can improve export times. The Asset Export API’s “chunk_size” accepts a range between 100 and 10,000.

What comes next?

Whether you just want do a one-time export of all asset and vulnerability data or poll the new APIs on a regular cadence for incremental updates using a variety of different filtering options, Tenable.io’s new export APIs are perfectly suited for all your data egress needs.

For more information