Integrate with the world's first Cyber Exposure platform using Tenable APIs

Get Started    API Explorer

Introduction to pyTenable

avatar guyavatar guy
By Steve McGrath, Tenable Senior Solutions Architect


All the capabilities of Vulnerability Management are available in the API, a robust platform for users of all experience levels. Using the API, you can seamlessly integrate into your cybersecurity infrastructure; for example, you can:

  • Automate asset data import into
  • Import third-party scan data.
  • Export scan results from into a workflow management system for remediation.

You can automate almost any task within the platform via the API. For some, this thought can seem daunting; however, Tenable has made the learning curve as low as possible with a API Python library called pyTenable.

The pyTenable library gives users a low-level interface into the API, and it uses pythonic nomenclature to make interacting with the API simple, empowering, and ultimately pain-free. This article provides an introduction to pyTenable to help you develop your integrations as quickly and as easily as possible.


Before using pyTenable, you need the following prerequisites:

  • Python 3.6 or later—pyTenable requires Python 3.6 or later.
  • API Keys—You need an account in with a set of generated API keys. To generate API keys for use with the API, see Generate API Keys in the Vulnerability Management User Guide. For information on how to use the API keys, see Authorization in the Tenable Developer Portal. It's worth noting that to use many endpoints, you may need elevated permissions or an administrator account to perform the action.

Environment Configuration

This article assumes that you already have a working Python 3.6 installation or later. I could write a whole guide on the different ways in which you could configure your environment, but for the sake of brevity, you can refer to My Development Setup on my developer blog if you're curious about my personal development environment.

  1. Install the pyTenable package

    Installing pyTenable is generally a simple one-line command using pip (Python Package Index). Pip can pull all of the required dependencies needed for the pyTenable library, and it's the recommended approach for installation. To install pyTenable via pip, simply execute the following command:
pip install pytenable
  1. (OPTIONAL) Set your API keys as environment variables

    pyTenable supports the use of environment variables for retrieving your API keys. Using environment variables can be quite useful when prototyping or writing a quick script. To set your API keys as environment variables, simply execute the following commands:

Once you have completed these steps, you are done with the environment configuration and ready to dive in!

Diving In

Instantiate an Object

The pyTenable library uses the concept of a connection class to act as the primary interface to the API. Connection classes are commonly used in many libraries, and allows for developers to have multiple connection objects within the code. This is useful if you need to use different users or interface into different instances. In practice, the pyTenable library is easy to use, simply instantiate an object and you have everything you need within that object.

For example, to instantiate an object named tio:

from import TenableIO

tio = TenableIO(

If you have configured your API keys as environment variables, the instantiation is even easier:

from import TenableIO

tio = TenableIO()

In either case, you now have an object named tio that you can interact with.

Identify Your Integration

When you develop an integration for, Tenable recommends that you identify yourself to the API. Identification allows Tenable to identify your integrations and API calls and it assists with debugging and troubleshooting if you have issues with the API, rate limits, or concurrency limits. Additionally, this is generally a requirement for partner integrations.

In the pyTenable library, adding identification is easy. You just pass a couple of additional parameters when instantiating an object, for example:

from import TenableIO

tio = TenableIO(
    vendor='Widgets Inc.',
    product='Widget Maker 5000',

With these parameters, the pyTenable library now has the information needed to construct a User-Agent header string with the appropriate information. For more information about using User-Agent headers with the API, see User-Agent Header.

Make Your First API Call

Now that you have the tio object instantiated you can make a simple call to the API. For this first call, let's get a list of configured scans from the platform:

scans = tio.scans.list()
for scan in scans:
    print(f'Scan {scan["id"]} is named {scan["name"]}')

You should see a list of every scan that you have access to along with their ID and name.

Creating and Launching Scans

One of the basic functions of the platform is data acquisition through scanning. Scanning can be simple or complicated depending on your environment and your specific need. The pyTenable library attempts to make scanning as simple as possible. For this introduction, we'll focus on pre-defined scan policy templates and save more complex scanning for another article.

External Scanning

External scanning is the simplest type, since you don't need to deploy a scanner within your environment to scan the perimeter. Conveniently, the pyTenable library makes pre-defined assumptions in order to reduce the amount of parameters you to pass.

For example, to run a Basic Network Scan against a host (called in the following examples), you only need a few lines:

scan = tio.scans.create(
    name='External Example Scan',

We only had to specify the name of the scan and the list of targets to scan. If you want to do something a little more complex, such as a PCI-ASV scan, you just need to specify the scan template name:

scan = tio.scans.create(
    name='External Example ASV Scan',

If you happen to know the UUID of the scan template, you can pass the UUID instead since the library is intelligent enough to know what is being passed:

scan = tio.scans.create(
    name='External Example Advanced Scan',

To get a list of policy template names and UUIDs:


Internal Scanning

Internal scanning is only marginally more difficult than external scanning. When you run an internal scan, you are required to define a scanner or scanner group as part of the scan definition. You can define the scanner or scanner group by either the name or UUID, just like with the scan policy templates in the external scanning examples.

To create an external scan using the name of the scanner:

internal_scan = tio.scans.create(
    name='Example Internal Scan',

To create an external scan using the UUID of the scanner:

internal_scan = tio.scans.create(
    name='Example Internal Scan',

Just like before, you can get the list of scanners and scanner groups through the library:


Tracking the Status of a Scan

The platform is generally asynchronous in practice, giving you the option to track the state of stateful actions, such as scans, however you see fit. When you launch a scan via the API or pyTenable library, it's never a blocking call, and a response is returned immediately. There are a variety of endpoints to track the state of a given job, for example, to see if a scan has been completed. In the example of scans, pyTenable has exposed this capability with the status method. This method can be used like so:

import time
status = 'pending'
while status[-2:] != 'ed':
    status = tio.scans.status(scan['id'])

While the example may seem odd, if you look at the Scan Status documentation, all of the end-state statuses are past-tense ("ed"), whereas the intermediary statuses are present tense ("ing"). This means you can make the while loop's condition to continue a check on the last two characters of the status.

What's Next?

As you can see, the capabilities of the API, when coupled with the pyTenable library as an interface layer, is quite easy to work with using a minimal amount of code. This article is just the first in a series of articles to explore some common API use cases. If you would like to see more, look for the next expert article in this series, where we will discuss exporting data from the platform.

For More Information

Updated about a month ago

Introduction to pyTenable

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.