pyTenable Documentation

To install the most recent published version of pyTenable from PyPI, use pip:

pip install pytenable

To install the necessary dependencies for the Scan Export Downloader, use pip to install the requirements specified in the project's requirements.txt file.

pip install -r requirements.txt

To install the necessary dependencies for the Vuln Export CSV File Generator, use pip to install the requirements specified in the requirements.txt file.

pip install -r requirements.txt

To run tests against a live Tenable.io container instead of using recorded VCR interactions, you must provide administrative and standard account credentials via environment variables and use the --disable-vcr flag.

Required environment variables:

• TIO_TEST_ADMIN_ACCESS: Admin API Access Key
• TIO_TEST_ADMIN_SECRET: Admin API Secret Key
• TIO_TEST_STD_ACCESS: Standard Account Access Key
• TIO_TEST_STD_SECRET: Standard Account Secret Key

Run the tests using:

pytest --disable-vcr --cov=tenable.io tests/io

export TIO_TEST_ADMIN_ACCESS="ADMIN_API_ACCESS_KEY_HERE"
export TIO_TEST_ADMIN_SECRET="ADMIN_API_SECRET_KEY_HERE"
export TIO_TEST_STD_ACCESS="STANDARD_ACCOUNT_ACCESS_KEY_HERE"
export TIO_TEST_STD_SECRET="STANDARD_ACCOUNT_SECRET_KEY_HERE"
pytest --disable-vcr --cov=tenable.io tests/io

The csvdownload tool is a Python script used to download CSV reports from the Tenable.io vulnerability workbench based on specific filtersets. You can filter by severity, plugin attributes, or plugin names using the -f flag.

By default, multiple filters are treated as an and operation, but you can switch to or logic using the --filter-type flag.

# Download critical and exploitable vulnerabilities
csvdownload -f severity:eq:Critical \
    -f plugin.attributes.exploit_available:eq:true \
    --csv-file crit_and_exploit.csv

# Download High OR Critical vulnerabilities
csvdownload -f severity:eq:High -f severity:eq:Critical --filter-type or \
    --csv-file high_and_crit.csv

To install the necessary dependencies for the Agent CSV File Generator, use pip to install the requirements specified in the requirements.txt file.

pip install -r requirements.txt

To install the bleeding-edge version directly from the GitHub repository, use the following command:

pip install git+git://github.com/tenable/pytenable.git#egg=pytenable

The rawexport.py script generates a directory named <current_time>-vulns containing vulnerability export chunks and pyTenable DEBUG logs. The results can be zipped for easier transport.

Basic Usage

To export all vulnerabilities using default settings, provide your Tenable.io Access Key and Secret Key:

./rawexport.py --access-key <ACCESS_KEY> --secret-key <SECRET_KEY>

Advanced Usage

You can filter exports by plugin IDs, time range, and destination directory. For example, to export specific plugins (e.g., 187240 and 172360) from the last 180 days, write the results to /tmp, and zip the output:

./rawexport.py --access-key <ACCESS_KEY> --secret-key <SECRET_KEY> -w /tmp -p 187240,172360 -d 180 -z

pyTenable uses pytest and VCRpy to run tests against pre-recorded API calls. This allows you to validate code behavior without making live network requests.

First, install the necessary development dependencies:

pip install -r dev-requirements.txt

Then, run the test suite using the following command to ensure no new recordings are created and to collect coverage for the tenable package:

pytest --vcr-record=none --cov=tenable tests

To interact with Tenable.sc, import TenableSC from tenable.sc. You must provide the url, access_key, and secret_key. The following example demonstrates how to iterate through vulnerabilities using the analysis module:

from tenable.sc import TenableSC

sc = TenableSC(url='https://SC_URL', access_key='AKEY', secret_key='SKEY')
for vuln in sc.analysis.vulns():
   print('{ip}:{pluginID}:{pluginName}'.format(**vuln))

To install the necessary dependencies for the Vuln Export RAW Generator, use pip to install the requirements specified in the requirements.txt file.

pip install -r requirements.txt

The agentexport.py script exports agent data to a CSV file. You must provide your Tenable VM API access and secret keys. You can optionally filter the export by agent health status using a comma-separated list of health states.

# Export all agents to agents.csv
./agentexport.py --access-key <access-key> --secret-key <secret-key> agents.csv

# Export unhealthy agents (WARNING or CRITICAL) to agents.csv
./agentexport.py --access-key <access-key> --secret-key <secret-key> --health 'WARNING,CRITICAL' agents.csv

# Export healthy agents to agents.csv
./agentexport.py --access-key <access-key> --secret-key <secret-key> --health 'HEALTHY' agents.csv

# Export unknown agents to agents.csv
./agentexport.py --access-key <access-key> --secret-key <secret-key> --health 'UNKNOWN' agents.csv