Get Started with pyTenable for Tenable OT

Introduction

The pyTenable python library provides an easy interface for customers and partners to interact with the Tenable OT Security API. pyTenable was created to help users easily develop their own custom tools, scripts, and integrations. Additionally, pyTenable also supports Tenable Vulnerability Management and Tenable Security Center if you plan to develop integrations for other Tenable products and solutions.

Tenable recommends that you use this library for both testing and production since it provides standard interfaces that handle authentication and request construction for you. The pyTenable GitHub repository provides detailed explanations for getting started, and the recipes page provides pyTenable samples for common Tenable OT Security API tasks.

Prerequisites

Before using pyTenable, you need the following prerequisites:

  • Python 3.6 or later—pyTenable requires Python 3.6 or later.
  • API Key—You need to generate an API key. To generate an API key for Tenable OT Security, see Generate an API Key.

Install pyTenable

This guide assumes that you already have a working Python 3.6 installation or later.

Installing pyTenable is 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:

pip3 install pytenable

Diving In

Instantiate an Object

The pyTenable library uses the concept of a connection class to act as the primary interface to the Tenable OT Security 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 tot:

from tenable.ot import TenableOT
tot = TenableOT(api_key='REPLACE_WITH_YOUR_API_KEY', url='https://REPLACE_WITH_SERVER_IP_OR_URL')

Identify Your Integration

When you develop an integration for Tenable OT Security, 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 tenable.ot import TenableOT
tot = TenableOT(
  	api_key='REPLACE_WITH_YOUR_API_KEY',
  	url='https://REPLACE_WITH_SERVER_IP_OR_URL',
  	vendor='Widgets Inc.',
    product='Widget Maker 5000',
    build='0.0.1'
)

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 Tenable OT Security and Tenable Vulnerability Management API, see User-Agent Header.

Make Your First API Call

Now that you have the tot object instantiated you can make a simple call to the Tenable OT Security API. For this first call, let's pull a list of assets. Copy the code in the snippet below to an editor of your choice and save the file as pytenable-tot-assets-BasicPull.py.

from tenable.ot import TenableOT

tot = TenableOT(
  	api_key='REPLACE_WITH_YOUR_API_KEY',
  	url='https://REPLACE_WITH_SERVER_IP_OR_URL',
  	vendor='Widgets Inc.',
    product='Widget Maker 5000',
    build='0.0.1'
)

for asset in tot.assets.list():
    print(vars(asset))
    print('\n')

You can execute the script above by running it on the command line:

# python3 pytenable-tot-assets-BasicPull.py

After running the pyTenable code, you should see a list of assets in Tenable OT Security. As you can see, the capabilities of the Tenable OT Security API, when coupled with the pyTenable library as an interface layer, is quite easy to work with using a minimal amount of code.

Recipes

Tenable provides some pre-built pyTenable recipes for common Tenable OT Security API tasks. For example, querying asset data.

  1. Basic Asset Query:
  1. Advanced Asset Query:
  1. Fetch Asset Group by Name

For a full list of pyTenable recipes, see Recipes.

For More Information