Tenable.io¶

class TenableIO(access_key=None, secret_key=None, url=None, retries=None, backoff=None, ua_identity=None, session=None, proxies=None, vendor=None, product=None, build=None)[source]¶

The Tenable.io object is the primary interaction point for users to interface with Tenable.io via the pyTenable library. All of the API endpoint classes that have been written will be grafted onto this class.

Parameters:

access_key (str, optional) – The user’s API access key for Tenable.io If an access key isn’t specified, then the library will attempt to read the environment variable TIO_ACCESS_KEY to acquire the key.
secret_key (str, optional) – The user’s API secret key for Tenable.io If a secret key isn’t specified, then the library will attempt to read the environment variable TIO_SECRET_KEY to acquire the key.
url (str, optional) – The base URL that the paths will be appended onto. The default is https://cloud.tenable.com
retries (int, optional) – The number of retries to make before failing a request. The default is 3.
backoff (float, optional) – If a 429 response is returned, how much do we want to backoff if the response didn’t send a Retry-After header. The default backoff is 1 second.
vendor (str, optional) – The vendor name for the User-Agent string.
product (str, optional) – The product name for the User-Agent string.
build (str, optional) – The version or build identifier for the User-Agent string.

Examples

Basic Example:

>>> from tenable.io import TenableIO
>>> tio = TenableIO('ACCESS_KEY', 'SECRET_KEY')

Example with proper identification:

>>> tio = TenableIO('ACCESS_KEY', 'SECRET_KEY',
>>>     vendor='Company Name',
>>>     product='My Awesome Widget',
>>>     build='1.0.0')

Example with proper identification leveraging environment variables for access and secret keys:

>>> tio = TenableIO(
>>>     vendor='Company Name', product='Widget', build='1.0.0')

access_groups¶

The following methods allow for interaction into the Tenable.io access-groups API endpoints.

Methods available on tio.access_groups:

class AccessGroupsAPI(api)[source]¶

create(name, rules, principals=None, all_users=False)[source]¶

Creates a new access group

access-groups: create

Parameters:	name (str) – The name of the access group to create. rules (list) – a list of rule tuples. Tuples are defined in the standardized method of name, operator, value. For example: ('operating_system', 'eq', ['Windows NT']) Rules will be validate against by the filters before being sent to the API. Note that the value field in this context is a list of string values. principals (list, optional) – A list of principal tuples. Each tuple must contain both the type and the identifier for the principal. The identifier can be either a UUID associated to a user/group, or the name of the user/group. For example: ('user', '32a0c314-442b-4aed-bbf5-ba9cf5cafbf4') ('user', 'steve@company.tld') ('group', '32a0c314-442b-4aed-bbf5-ba9cf5cafbf4') all_users (bool, optional) – If enabled, the access group will apply to all users and any principals defined will be ignored.
Returns:	The resource record for the new access list.
Return type:	`dict`

Examples

Allow all users to see 192.168.0.0/24:

>>> tio.access_groups.create('Example',
...     [('ipv4', 'eq', ['192.168.0.0/24'])],
...     all_users=True)

Allow everyone in a specific group id to see specific hosts:

>>> tio.access_groups.create('Example',
...     [('netbios_name', 'eq', ['dc1.company.tld']),
...      ('netbios_name', 'eq', ['dc2.company.tld'])],
...     principals=[
...         ('group', '32a0c314-442b-4aed-bbf5-ba9cf5cafbf4')
... ])

delete(id)[source]¶

Deletes the specified access group.

access-groups: delete

Parameters:	id (str) – The UUID of the access group to remove.

details(id)[source]¶

Retrieves the details of the specified access group.

access-groups: details

Parameters:	id (str) – The UUID of the access group.

edit(id, **kw)[source]¶

Edits an access group

access-groups: update

Parameters:

id (str) – The UUID of the access group to edit.
name (str, optional) – The name of the access group to create.
rules (list, optional) –
a list of rule tuples. Tuples are defined in the standardized method of name, operator, value. For example:
```
('operating_system', 'eq', ['Windows NT'])
```
Rules will be validate against by the filters before being sent to the API. Note that the value field in this context is a list of string values.
principals (list, optional) –
A list of principal tuples. Each tuple must contain both the type and the identifier for the principal. The identifier can be either a UUID associated to a user/group, or the name of the user/group. For example:
```
('user', '32a0c314-442b-4aed-bbf5-ba9cf5cafbf4')
('user', 'steve@company.tld')
('group', '32a0c314-442b-4aed-bbf5-ba9cf5cafbf4')
```
all_users (bool, optional) – If enabled, the access group will apply to all users and any principals defined will be ignored.
all_assets (bool, optional) – Specifies if the access group to modify is the default “all assets” group or a user-defined one.

list(*filters, **kw)[source]¶

Get the listing of configured access groups from Tenable.io.

access-groups: list

Parameters:	filters (tuple, optional) – Filters are tuples in the form of (‘NAME’, ‘OPERATOR’, ‘VALUE’). Multiple filters can be used and will filter down the data being returned from the API. Examples `('distro', 'match', 'win')` `('name', 'nmatch', 'home')` As the filters may change and sortable fields may change over time, it’s highly recommended that you look at the output of the `tio.filters.access_groups_filters()` endpoint to get more details. filter_type* (str, optional) – The filter_type operator determines how the filters are combined together. `and` will inform the API that all of the filter conditions must be met for an access group to be returned, whereas `or` would mean that if any of the conditions are met, the access group record will be returned. limit (int, optional) – The number of records to retrieve. Default is 50 offset (int, optional) – The starting record to retrieve. Default is 0. sort (tuple, optional) – A tuple of tuples identifying the the field and sort order of the field. wildcard (str, optional) – A string to pattern match against all available fields returned. wildcard_fields (list, optional) – A list of fields to optionally restrict the wild-card matching to.
Returns:	An iterator that handles the page management of the requested records.
Return type:	`AccessGroupsIterator`

Examples

Getting the listing of all agents:

>>> for group in tio.access_groups.list():
...     pprint(group)

Retrieving all of the windows agents:

>>> for group in tio.access_groups.list(('name', 'eq', 'win')):
...     pprint(group)

agent_config¶

The following methods allow for interaction into the Tenable.io agent config API endpoints.

Methods available on tio.agent_config:

class AgentConfigAPI(api)[source]¶

edit(scanner_id=1, software_update=None, auto_unlink=None)[source]¶

Edits the agent configuration.

agent-config: edit

Parameters:	scanner_id (int, optional) – The scanner ID. software_update (bool, optional) – If True, software updates are enabled for agents (exclusions may override this). If false, software updates for all agents are disabled. auto_unlink (int, optional) – If true, agent auto-unlinking is enabled, allowing agents to automatically unlink themselves after a given period of time. If the value is 0 or false, auto-unlinking is disabled. True values are between 1 and 365.
Returns:	Dictionary of the applied settings is returned if successfully applied.
Return type:	`dict`

Examples

Enabling auto-unlinking for agents after 30 days:

>>> tio.agent_config.edit(auto_unlink=30)

Disabling auto-unlinking for agents:

>>> tio.agent_config.edit(auto_unlink=False)

Enabling software updates for agents:

>>> tio.agent_config.edit(software_update=True)

details(scanner_id=1)[source]¶

Returns the current agent configuration.

agent-config: details

Parameters:	scanner_id (int, optional) – The scanner ID.
Returns:	Dictionary of the current settings.
Return type:	`dict`

Examples

>>> details = tio.agent_config.details()
>>> pprint(details)

agent_exclusions¶

The following methods allow for interaction into the Tenable.io agent exclusions API endpoints.

Methods available on tio.agent_exclusions:

class AgentExclusionsAPI(api)[source]¶

create(name, scanner_id=1, start_time=None, end_time=None, timezone=None, description=None, frequency=None, interval=None, weekdays=None, day_of_month=None, enabled=True)[source]¶

Creates a new agent exclusion.

agent-exclusions: create

Parameters:	name (str) – The name of the exclusion to create. scanner_id (int, optional) – The scanner id. description (str, optional) – Some further detail about the exclusion. start_time (datetime) – When the exclusion should start. end_time (datetime) – When the exclusion should end. timezone (str, optional) – The timezone to use for the exclusion. The default if none is specified is to use UTC. For the list of usable timezones, please refer to: https://cloud.tenable.com/api#/resources/scans/timezones frequency (str, optional) – The frequency of the rule. The string inputted will be up-cased. Valid values are: `ONETIME`, `DAILY`, `WEEKLY`, `MONTHLY`, `YEARLY`. Default value is `ONETIME`. interval (int, optional) – The interval of the rule. The default interval is 1 weekdays (list, optional) – List of 2-character representations of the days of the week to repeat the frequency rule on. Valid values are: SU, MO, TU, WE, TH, FR, SA Default values: `['SU', 'MO', 'TU', 'WE', 'TH', 'FR', 'SA']` day_of_month (int, optional) – The day of the month to repeat a MONTHLY frequency rule on. The default is today. enabled (bool, optional) – Is the exclusion enabled? The default is `True`
Returns:	Dictionary of the newly minted exclusion.
Return type:	dict

Examples

Creating a one-time exclusion:

>>> from datetime import datetime, timedelta
>>> exclusion = tio.agent_exclusions.create(
...     'Example One-Time Agent Exclusion',
...     ['127.0.0.1'],
...     start_time=datetime.utcnow(),
...     end_time=datetime.utcnow() + timedelta(hours=1))

Creating a daily exclusion:

>>> exclusion = tio.agent_exclusions.create(
...     'Example Daily Agent Exclusion',
...     ['127.0.0.1'],
...     frequency='daily',
...     start_time=datetime.utcnow(),
...     end_time=datetime.utcnow() + timedelta(hours=1))

Creating a weekly exclusion:

>>> exclusion = tio.agent_exclusions.create(
...     'Example Weekly Exclusion',
...     ['127.0.0.1'],
...     frequency='weekly',
...     weekdays=['mo', 'we', 'fr'],
...     start_time=datetime.utcnow(),
...     end_time=datetime.utcnow() + timedelta(hours=1))

Creating a monthly esxclusion:

>>> exclusion = tio.agent_exclusions.create(
...     'Example Monthly Agent Exclusion',
...     ['127.0.0.1'],
...     frequency='monthly',
...     day_of_month=1,
...     start_time=datetime.utcnow(),
...     end_time=datetime.utcnow() + timedelta(hours=1))

Creating a yearly exclusion:

>>> exclusion = tio.agent_exclusions.create(
...     'Example Yearly Agent Exclusion',
...     ['127.0.0.1'],
...     frequency='yearly',
...     start_time=datetime.utcnow(),
...     end_time=datetime.utcnow() + timedelta(hours=1))

delete(exclusion_id, scanner_id=1)[source]¶

Delete an agent exclusion.

agent-exclusions: delete

Parameters:	exclusion_id (int) – The id of the exclusion object in Tenable.io scanner_id (int, optional) – The id of the scanner
Returns:	The Exclusion was successfully deleted
Return type:	None

Examples

>>> tio.agent_exclusions.delete(1)

details(exclusion_id, scanner_id=1)[source]¶

Retrieve the details for a specific agent exclusion.

agent-exclusion: details

Parameters:	exclusion_id (int) – The id of the exclusion object in Tenable.io scanner_id (int, optional) – The id of the scanner
Returns:	The exclusion resource dictionary.
Return type:	dict

Examples

>>> exclusion = tio.agent_exclusions.details(1)

edit(exclusion_id, scanner_id=1, name=None, start_time=None, end_time=None, timezone=None, description=None, frequency=None, interval=None, weekdays=None, day_of_month=None, enabled=None)[source]¶

Edit an existing agent exclusion.

agent-exclusions: edit

The edit function will first gather the details of the exclusion that will be edited and will overlay the changes on top. The result will then be pushed back to the API to modify the exclusion.

Parameters:	exclusion_id (int) – The id of the exclusion object in Tenable.io scanner_id (int, optional) – The scanner id. name (str, optional) – The name of the exclusion to create. description (str, optional) – Some further detail about the exclusion. start_time (datetime, optional) – When the exclusion should start. end_time (datetime, optional) – When the exclusion should end. timezone (str, optional) – The timezone to use for the exclusion. The default if none is specified is to use UTC. frequency (str, optional) – The frequency of the rule. The string inputted will be up-cased. Valid values are: ONETIME, DAILY, WEEKLY, MONTHLY, YEARLY. interval (int, optional) – The interval of the rule. weekdays (list, optional) – List of 2-character representations of the days of the week to repeat the frequency rule on. Valid values are: SU, MO, TU, WE, TH, FR, SA Default values: `['SU', 'MO', 'TU', 'WE', 'TH', 'FR', 'SA']` day_of_month (int, optional) – The day of the month to repeat a MONTHLY frequency rule on.
Returns:	Dictionary of the newly minted exclusion.
Return type:	dict

Examples

>>> exclusion = tio.agent_exclusions.edit(1, name='New Name')

list(scanner_id=1)[source]¶

Lists all of the currently configured agent exclusions.

agent-exclusions: list

Parameters:	scanner_id (int, optional) – The scanner identifier to be used.
Returns:	List of agent exclusions.
Return type:	list

Examples

>>> for exclusion in tio.agent_exclusions.list():
...     pprint(exclusion)

agent_groups¶

The following methods allow for interaction into the Tenable.io agent groups API endpoints.

Methods available on tio.agent_groups:

class AgentGroupsAPI(api)[source]¶

add_agent(group_id, *agent_ids, **kw)[source]¶

Adds an agent or multiple agents to the agent group specified.

agent-groups: add-agent

Parameters:	group_id (int) – The id of the group agent_ids (int) – The id of the agent scanner_id* (int, optional) – The id of the scanner
Returns:	If adding a singular agent, a `None` response will be returned. If adding multiple agents, a `dict` response will be returned with a task record.
Return type:	`dict` or `None`

Examples

Adding a singular agent:

>>> tio.agent_groups.add_agent(1, 1)

Adding multiple agents:

>>> tio.agent_groups.add_agent(1, 1, 2, 3)

configure(group_id, name, scanner_id=1)[source]¶

Renames an existing agent group.

agent-groups: configure

Parameters:	group_id (int) – The id of the group name (str) – The new name for the agent group scanner_id (int, optional) – The id of the scanner
Returns:	`None`

Examples

>>> tio.agent_groups.configure(1, 'New Name')

create(name, scanner_id=1)[source]¶

Creates a new agent group.

agent-groups: create

Parameters:	name (str) – The name of the agent group scanner_id (int, optional) – The id of the scanner to add the agent group to
Returns:	The dictionary object representing the newly minted agent group
Return type:	`dict`

Examples

>>> group = tio.agent_groups.create('New Agent Group')

delete(group_id, scanner_id=1)[source]¶

Delete an agent group.

agent-groups: delete

Parameters:	group_id (int) – The id of the agent group to delete scanner_id (int, optional) – The id of the scanner
Returns:	`None`

Examples

>>> tio.agent_groups.delete(1)

delete_agent(group_id, *agent_ids, **kw)[source]¶

Delete one or many agents from an agent group.

agent-groups: delete-agent

Parameters:	group_id (int) – The id of the agent group to remove the agent from agent_ids (int) – The id of the agent to be removed scanner_id* (int, optional) – The id of the scanner
Returns:	If deleting a singular agent, a `None` response will be returned. If deleting multiple agents, a `dict` response will be returned with a Job resource record.
Return type:	`dict` or `None`

Examples

Delete a singular agent from an agent group:

>>> tio.agent_groups.delete_agent(1, 1)

Delete multiple agents from an agent group:

>>> tio.agent_groups.delete_agent(1, 1, 2, 3)

details(group_id, scanner_id=1)[source]¶

Retrieve the details about the specified agent group.

agent-groups: details

Parameters:	group_id (int) – The id of the agent group to remove the agent from scanner_id (int, optional) – The id of the scanner
Returns:	The dictionary object representing the requested agent group
Return type:	`dict`

Examples

>>> group = tio.agent_groups.details(1)
>>> pprint(group)

list(scanner_id=1)[source]¶

Retrieves the list of agent groups configured

agent-groups: list

Parameters:	scanner_id (int, optional) – The id of the scanner
Returns:	Listing of agent group resource records
Return type:	`list`

Examples

>>>> for agent_group in tio.agent_groups.list(): … pprint(agent_group)

task_status(group_id, task_uuid, scanner_id=1)[source]¶

Retrieves the current status of a bulk task.

bulk-operations: bulk-agent-group-status

Parameters:	group_id (int) – The id of the group task_uuid (str) – The id of the task scanner_id (int, optional) – The id of the scanner
Returns:	Task resource
Return type:	`dict`

Examples

>>> item = tio.agent_groups.add_agent(1, 21, 22, 23)
>>> task = tio.agent_groups.task_status(item['task_uuid'])
>>> pprint(task)

agents¶

The following methods allow for interaction into the Tenable.io agents API endpoints.

Methods available on tio.agents:

class AgentsAPI(api)[source]¶

details(agent_id, scanner_id=1)[source]¶

Retrieves the details of an agent.

agents: get

Parameters:	agent_id (int) – The identifier of the agent. scanner_id (int, optional) – The identifier of the scanner. Default is 1.
Returns:	The agent dictionary record.
Return type:	`dict`

Examples

>>> agent = tio.agents.details(1)
>>> pprint(agent)

list(*filters, **kw)[source]¶

Get the listing of configured agents from Tenable.io.

agents: list

Parameters:	filters (tuple, optional) – Filters are tuples in the form of (‘NAME’, ‘OPERATOR’, ‘VALUE’). Multiple filters can be used and will filter down the data being returned from the API. Examples `('distro', 'match', 'win')` `('name', 'nmatch', 'home')` As the filters may change and sortable fields may change over time, it’s highly recommended that you look at the output of the filters:agents-filters endpoint to get more details. filter_type* (str, optional) – The filter_type operator determines how the filters are combined together. `and` will inform the API that all of the filter conditions must be met for an agent to be returned, whereas `or` would mean that if any of the conditions are met, the agent record will be returned. limit (int, optional) – The number of records to retrieve. Default is 50 offset (int, optional) – The starting record to retrieve. Default is 0. scanner_id (int, optional) – The identifier the scanner that the agent communicates to. sort (tuple, optional) – A tuple of tuples identifying the the field and sort order of the field. wildcard (str, optional) – A string to pattern match against all available fields returned. wildcard_fields (list, optional) – A list of fields to optionally restrict the wild-card matching to.
Returns:	An iterator that handles the page management of the requested records.
Return type:	`AgentsIterator`

Examples

Getting the listing of all agents:

>>> for agent in tio.agents.list():
...     pprint(agent)

Retrieving all of the windows agents:

>>> for agent in tio.agents.list(('distro', 'match', 'win')):
...     pprint(agent)

unlink(*agent_ids, **kw)[source]¶

Unlink one or multiple agents from the Tenable.io instance.

agents: delete

Parameters:	agent_ids (int) – The ID of the agent to delete scanner_id* (int, optional) – The identifier the scanner that the agent communicates to.
Returns:	If unlinking a singular agent, a `None` response will be returned. If unlinking multiple agents, a `dict` response will be returned with a task record.
Return type:	`dict` or `None`

Examples

Unlink a singular agent:

>>> tio.agents.unlink(1)

Unlink many agents:

>>> tio.agents.unlink(1, 2, 3)

task_status(task_uuid, scanner_id=1)[source]¶

Retrieves the current status of the task requested.

bulk-operations: bulk-agent-status

Parameters:	task_uuid (str) – The id of the agent scanner_id (int, optional) – The id of the scanner
Returns:	Task resource
Return type:	`dict`

Examples

>>> item = tio.agents.unlink(21, 22, 23)
>>> task = tio.agent.task_status(item['task_uuid'])
>>> pprint(task)

assets¶

The following methods allow for interaction into the Tenable.io assets API endpoints.

Methods available on tio.assets:

class AssetsAPI(api)[source]¶

asset_import(source, *assets)[source]¶

Imports asset information into Tenable.io from an external source.

assets: import

Imports a list of asset definition dictionaries. Each asset record must contain at least one of the following attributes: fqdn, ipv4, netbios_name, mac_address. Each record may also contain additional properties.

Parameters:	assets (list) – The list of asset dictionaries source* (str) – An identifier to be used to upload the assets.
Returns:	The job UUID.
Return type:	`str`

Examples

>>> tio.assets.asset_import('example_source', {
...     'fqdn': ['example.py.test'],
...     'ipv4': ['192.168.254.1'],
...     'netbios_name': 'example',
...     'mac_address': ['00:00:00:00:00:00']
... })

delete(uuid)[source]¶

Deletes the asset.

workbenches: asset-delete

Parameters:	asset_uuid (str) – The unique identifier for the asset.
Returns:
Return type:	`None`

Examples

>>> asset_id = '00000000-0000-0000-0000-000000000000'
>>> tio.asset.delete(asset_id)

details(uuid)[source]¶

Retrieves the details about a specific asset.

assets: asset-info

Parameters:	uuid (str) – The UUID (unique identifier) for the asset.
Returns:	Asset resource definition.
Return type:	`dict`

Examples

>>> asset = tio.assets.details(
...     '00000000-0000-0000-0000-000000000000')

import_job_details(uuid)[source]¶

Returns the details about a specific asset import job.

assets: import-job-info

uuid (str):: The UUID (unique identifier) for the job.

Returns:	The job Resource record.
Return type:	`dict`

Examples

>>> job = tio.assets.import_job_details(
...     '00000000-0000-0000-0000-000000000000')
>>> pprint(job)

list()[source]¶

Returns a list of assets.

assets: list-assets

Returns:	List of asset records.
Return type:	`list`

Examples

>>> for asset in tio.assets.list():
...     pprint(asset)

list_import_jobs()[source]¶

Returns a list of asset import jobs.

assets: list-import-jobs

Returns:	List of job records.
Return type:	`list`

Examples

>>> for job in tio.assets.list_import_jobs():
...     pprint(job)

tags(uuid)[source]¶

Retrieves the details about a specific asset.

tags: asset-tags

Parameters:	uuid (str) – The UUID (unique identifier) for the asset.
Returns:	Asset resource definition.
Return type:	`dict`

Examples

>>> asset = tio.assets.tags(
...     '00000000-0000-0000-0000-000000000000')

audit_log¶

The following methods allow for interaction into the Tenable.io audit log API endpoints.

Methods available on io.audit_log:

class AuditLogAPI(api)[source]¶

events(*filters, **kw)[source]¶

Retrieve audit logs from Tenable.io.

audit-log: events

Parameters:	filters (tuple, optional) – Filters to allow the user to get to a specific subset of data within the audit log. For a more detailed listing of what filters are available, please refer to the API documentation linked above, however some examples are as such: `('date', 'gt', '2017-07-05')` `('date', 'lt', '2017-07-07')` `('actor_id', 'match', '6000a811-8422-4096-83d3-e4d44f44b97d')` `('target_id', 'match', '6000a811-8422-4096-83d3-e4d44f44b97d')` limit* (int, optional) – The limit of how many events to return. The API will default to 50 unless otherwise specified.
Returns:	List of event records
Return type:	`list`

Examples

>>> events = tio.audit_log.events(
...     ('date', 'gt', '2018-01-01'), limit=100)
>>> for e in events:
...     pprint(e)

credentials¶

The following methods allow for interaction into the Tenable.io credentials API endpoints.

Methods available on tio.credentials:

class CredentialsAPI(api)[source]¶

create(cred_name, cred_type, description=None, permissions=None, **settings)[source]¶

Creates a new managed credential.

credentials: create

Parameters:	cred_name (str) – The name of the credential. cred_type (str) – The type of credential to create. For a list of values refer to the output of the `types()` method. description (str, optional) – A description for the credential. permissions (list, optional) – A list of permissions (in either tuple or native dict format) detailing whom is allowed to use or edit this credential set. For the dictionary format, refer to the API docs. The tuple format uses the customary `(type, perm, uuid)` format. Examples `('user', 32, user_uuid)` `('group', 32, group_uuid)` `('user', 'use', user_uuid)` *settings (dict, optional*) – Additional keywords passed will be added to the settings dict within the API call. As this dataset can be highly variable, it will not be validated and simply passed as-is.
Returns:	The UUID of the newly created credential.
Return type:	`str`

Examples

>>> group_id = '00000000-0000-0000-0000-000000000000'
>>> tio.credentials.create('SSH Account', 'SSH',
...     permissions=[('group', 'use', group_id)],
...     username='user1',
...     password='sekretsquirrel',
...     escalation_account='root',
...     escalation_password='sudopassword',
...     elevate_privileges_with='sudo',
...     bin_directory='/usr/bin',
...     custom_password_prompt='')

delete(id)[source]¶

Deletes the specified credential.

credentials: delete

Parameters:	id (str) – The UUID of the credential to retreive.
Returns:	The status of the action.
Return type:	`bool`

Examples

>>> cred_uuid = '00000000-0000-0000-0000-000000000000'
>>> cred = tio.credentials.delete(cred_uuid)

details(id)[source]¶

Retrives the details of the specified credential.

credentials: details

Parameters:	id (str) – The UUID of the credential to retreive.
Returns:	The resource record for the credential.
Return type:	`dict`

Examples

>>> cred_uuid = '00000000-0000-0000-0000-000000000000'
>>> cred = tio.credentials.details(cred_uuid)

edit(cred_uuid, cred_name=None, description=None, permissions=None, ad_hoc=None, **settings)[source]¶

Creates a new managed credential.

credentials: create

Parameters:	ad_hoc (bool, optional) – Determins whether the credential is managed (`False`) or an embedded credential in a scan or policy (`True`). cred_name (str, optional) – The name of the credential. description (str, optional) – A description for the credential. permissions (list, optional) – A list of permissions (in either tuple or native dict format) detailing whom is allowed to use or edit this credential set. For the dictionary format, refer to the API docs. The tuple format uses the customary `(type, perm, uuid)` format. Examples `('user', 32, user_uuid)` `('group', 32, group_uuid)` `('user', 'use', user_uuid)` *settings (dict, optional*) – Additional keywords passed will be added to the settings dict within the API call. As this dataset can be highly variable, it will not be validated and simply passed as-is.
Returns:	The status of the update process.
Return type:	`bool`

Examples

>>> cred_uuid = '00000000-0000-0000-0000-000000000000'
>>> tio.credentials.edit(cred_uuid,
...     password='sekretsquirrel',
...     escalation_password='sudopassword')

list(*filters, **kw)[source]¶

Get the listing of configured credentials from Tenable.io.

credentials: list

Parameters:	filters (tuple, optional) – Filters are tuples in the form of (‘NAME’, ‘OPERATOR’, ‘VALUE’). Multiple filters can be used and will filter down the data being returned from the API. Examples `('name', 'eq', 'example')` As the filters may change and sortable fields may change over time, it’s highly recommended that you look at the output of the `tio.filters.networks_filters()` endpoint to get more details. filter_type* (str, optional) – The filter_type operator determines how the filters are combined together. `and` will inform the API that all of the filter conditions must be met for an access group to be returned, whereas `or` would mean that if any of the conditions are met, the access group record will be returned. limit (int, optional) – The number of records to retrieve. Default is 50 offset (int, optional) – The starting record to retrieve. Default is 0. owner_uuid (str, optional) – The UUID of the scan owner. If specified it will limit the responses to credentials assigned to scans owned by the specified user UUID. sort (tuple, optional) – A tuple of tuples identifying the the field and sort order of the field. wildcard (str, optional) – A string to pattern match against all available fields returned. wildcard_fields (list, optional) – A list of fields to optionally restrict the wild-card matching to.
Returns:	An iterator that handles the page management of the requested records.
Return type:	`CredentialsIterator`

Examples

>>> for cred in tio.credentials.list():
...     pprint(cred)

types()[source]¶

Lists all of the available credential types.

credentials: list-types

Returns:	A list of the available credential types and definitions.
Return type:	`list`

Examples

>>> cred_types = tio.credentials.types()

editor¶

The following methods allow for interaction into the Tenable.io editor API endpoints. While these endpoints are pythonized for completeness within pyTenable, the Editor API endpoints should generally be avoided unless absolutely necessary. These endpoints are used to drive the Tenable.io UI, and not designed to be used programmatically.

Methods available on io.editor:

class EditorAPI(api)[source]¶

audits(etype, object_id, file_id, fobj=None)[source]¶

Retrieves an audit file from Tenable.io

editor: audits

Parameters:	etype (str) – The type of template to retrieve. Must be either `scan` or `policy`. object_od (int) – The unique identifier of the object. file_id (int) – The unique identifier of the file to export. fobj (FileObject) – An optional File-like object to write the file to. If none is provided a BytesIO object will be returned.
Returns:	A File-like object of of the audit file.
Return type:	`file`

details(etype, id)[source]¶

Constructs a valid scan document from the specified item.

Important

Please note that the details method is reverse-engineered from the responses from the editor API, and while we are reasonably sure that the response should align almost exactly to what the API expects to be pushed to it, this method by very nature of what it’s doing isn’t guaranteed to always work.

Parameters:	etype (str) – The type of object to request. scan_id (int) – The unique identifier for the scan.
Returns:	The constructed scan configuration resource.
Return type:	`dict`

Examples

>>> policy = tio.editor.details('scan', 1)
>>> pprint(scan)

obj_details(etype, id)[source]¶

Retrieves details about a specific object.

editor: template-details

Parameters:	etype (str) – The type of object to retrieve. Must be either `scan` or `policy`. id (int) – The unique identifier of the object.
Returns:	Details of the requested object
Return type:	`dict`

plugin_description(policy_id, family_id, plugin_id)[source]¶

Retrieves the plugin description for the specified plugin.

editor: plugin-description

Parameters:	policy_id (int) – The identifier of the policy. family_id (int) – The identifier of the plugin family. plugin_id (int) – The identifier of the plugin within the family.
Returns:	Details of the plugin requested.
Return type:	`dict`

template_details(etype, uuid)[source]¶

Retrieves details about a specific template.

editor: template-details

Parameters:	etype (str) – The type of template to retrieve. Must be either `scan` or `policy`. uuid (str) – The UUID (unique identifier) for the template.
Returns:	Details on the requested template
Return type:	`dict`

template_list(etype)[source]¶

List template objects.

editor: list

Parameters:	etype (str) – The type of object to retrieve. Must be either `scan` or `policy`.
Returns:	Listing of template records.
Return type:	`list`

exclusions¶

The following methods allow for interaction into the Tenable.io exclusions API endpoints.

Methods available on tio.exclusions:

class ExclusionsAPI(api)[source]¶

create(name, members, start_time=None, end_time=None, timezone=None, description=None, frequency=None, interval=None, weekdays=None, day_of_month=None, enabled=True)[source]¶

Create a scan target exclusion.

exclusions: create

Parameters:	name (str) – The name of the exclusion to create. members (list) – The exclusions members. Each member should be a string with either a FQDN, IP Address, IP Range, or CIDR. description (str, optional) – Some further detail about the exclusion. start_time (datetime) – When the exclusion should start. end_time (datetime) – When the exclusion should end. timezone (str, optional) – The timezone to use for the exclusion. The default if none is specified is to use UTC. For the list of usable timezones, please refer to devportalscans-timezones frequency (str, optional) – The frequency of the rule. The string inputted will be up-cased. Valid values are: `ONETIME`, `DAILY`, `WEEKLY`, `MONTHLY`, `YEARLY`. Default value is `ONETIME`. interval (int, optional) – The interval of the rule. The default interval is 1 weekdays (list, optional) – List of 2-character representations of the days of the week to repeat the frequency rule on. Valid values are: SU, MO, TU, WE, TH, FR, SA Default values: `['SU', 'MO', 'TU', 'WE', 'TH', 'FR', 'SA']` day_of_month (int, optional) – The day of the month to repeat a MONTHLY frequency rule on. The default is today. enabled (bool, optional) – Is the exclusion enabled? The default is `True`
Returns:	Dictionary of the newly minted exclusion.
Return type:	`dict`

Examples

Creating a one-time exclusion:

>>> from datetime import datetime, timedelta
>>> exclusion = tio.exclusions.create(
...     'Example One-Time Exclusion',
...     ['127.0.0.1'],
...     start_time=datetime.utcnow(),
...     end_time=datetime.utcnow() + timedelta(hours=1))

Creating a daily exclusion:

>>> exclusion = tio.exclusions.create(
...     'Example Daily Exclusion',
...     ['127.0.0.1'],
...     frequency='daily',
...     start_time=datetime.utcnow(),
...     end_time=datetime.utcnow() + timedelta(hours=1))

Creating a weekly exclusion:

>>> exclusion = tio.exclusions.create(
...     'Example Weekly Exclusion',
...     ['127.0.0.1'],
...     frequency='weekly',
...     weekdays=['mo', 'we', 'fr'],
...     start_time=datetime.utcnow(),
...     end_time=datetime.utcnow() + timedelta(hours=1))

Creating a monthly esxclusion:

>>> exclusion = tio.exclusions.create(
...     'Example Monthly Exclusion',
...     ['127.0.0.1'],
...     frequency='monthly',
...     day_of_month=1,
...     start_time=datetime.utcnow(),
...     end_time=datetime.utcnow() + timedelta(hours=1))

Creating a yearly exclusion:

>>> exclusion = tio.exclusions.create(
...     'Example Yearly Exclusion',
...     ['127.0.0.1'],
...     frequency='yearly',
...     start_time=datetime.utcnow(),
...     end_time=datetime.utcnow() + timedelta(hours=1))

delete(id)[source]¶

Delete a scan target exclusion.

exclusions: delete

Parameters:	id (int) – The exclusion identifier to delete
Returns:	The exclusion was successfully deleted.
Return type:	`None`

Examples

>>> tio.exclusions.delete(1)

details(id)[source]¶

Retrieve the details for a specific scan target exclusion.

exclusions: details

Parameters:	id (int) – The exclusion identifier.
Returns:	The exclusion record requested.
Return type:	`dict`

Examples

>>> exclusion = tio.exclusions.details(1)
>>> pprint(exclusion)

edit(id, name=None, members=None, start_time=None, end_time=None, timezone=None, description=None, frequency=None, interval=None, weekdays=None, day_of_month=None, enabled=None)[source]¶

Edit an existing scan target exclusion.

exclusions: edit

The edit function will first gather the details of the exclusion that will be edited and will overlay the changes on top. The result will then be pushed back to the API to modify the exclusion.

Parameters:	id (int) – The id of the exclusion object in Tenable.io scanner_id (int, optional) – The scanner id. name (str, optional) – The name of the exclusion to create. description (str, optional) – Some further detail about the exclusion. start_time (datetime, optional) – When the exclusion should start. end_time (datetime, optional) – When the exclusion should end. timezone (str, optional) – The timezone to use for the exclusion. The default if none is specified is to use UTC. frequency (str, optional) – The frequency of the rule. The string inputted will be upcased. Valid values are: ONETIME, DAILY, WEEKLY, MONTHLY, YEARLY. interval (int, optional) – The interval of the rule. weekdays (list, optional) – List of 2-character representations of the days of the week to repeat the frequency rule on. Valid values are: SU, MO, TU, WE, TH, FR, SA Default values: `['SU', 'MO', 'TU', 'WE', 'TH', 'FR', 'SA']` day_of_month (int, optional) – The day of the month to repeat a MONTHLY frequency rule on.
Returns:	Dictionary of the newly minted exclusion.
Return type:	`dict`

Examples

Modifying the name of an exclusion:

>>> exclusion = tio.exclusions.edit(1, name='New Name')

list()[source]¶

List the currently configured scan target exclusions.

exclusions: list

Returns:	List of exclusion resource records.
Return type:	`list`

Examples

>>> for exclusion in tio.exclusions.list():
...     pprint(exclusion)

exports¶

The following methods allow for interaction into the Tenable.io exports API endpoints.

Methods available on tio.exports:

class ExportsAPI(api)[source]¶

assets(**kw)[source]¶

Export asset data from Tenable.io.

exports: assets-request-export

Parameters:	chunk_size (int, optional) – Specifies the number of objects returned per-chunk. If nothing is specified, it will default to 1000 objects. created_at (int, optional) – Returns all assets created after the specified unix timestamp. updated_at (int, optional) – Returns all assets updated after the specified unix timestamp. terminated_at (int, optional) – Returns all assets terminated after the specified unix timestamp. deleted_at (int, optional) – Returns all assets deleted after the specified unix timestamp. first_scan_time (int, optional) – Returns all assets first scanned after the specified unix timestamp. last_authenticated_scan_time (int, optional) – Returns all assets that have completed an authenticated scan after the specified unix timestamp. last_assessed (int, optional) – Returns all assets that have been assessed after the specified unix timestamp. servicenow_sysid (bool, optional) – If set to True, will return only assets that have a ServiceNow Sys ID. If set to False, then returns only assets that do not have a ServiceNow Sys ID. sources (list, optional) – Returns assets that have the specified source. If multiple sources are listed, then the results will be assets that have been observed by any of the sources listed. has_plugin_results (bool, optional) – If True, returns only assets that have plugin results. If False, returns only assets that do not have any plugin results. Assets thats would not have plugin results would be assets created from a connector, or a discovery scan. tags (list, optional) – List of tag key-value pairs that must be associated to the asset data to be returned. Key-value pairs are tuples `('key', 'value')` and are case-sensitive. uuid (str, optional) – To re-request an iterator based off of an existing export, pass the UUID of the export to bypass the initial request and instead use the UUID passed to build the export iterator.
Returns:	An iterator to walk through the results.
Return type:	`ExportIterator`

Examples

Export all of the asset data within Tenable.io:

>>> assets = tio.exports.assets()
>>> for asset in assets:
...     pprint(asset)

Export only the assets updated in the last week:

>>> import time
>>> last_week = int(time.time()) - 604800
>>> for asset in tio.exports.assets(updated_at=last_week):
...     pprint(asset)

vulns(**kw)[source]¶

Initiate an vulnerability export.

exports: vulns-request-export

Parameters:	cidr_range (str, optional) – Restrict the export to only vulns assigned to assets within the CIDR range specified. first_found (int, optional) – Specifies the earliest time for a vulnerability to have been discovered. Format is a unix timestamp integer. last_fixed (int, optional) – Specifies the earliest time that vulnerabilities may have been fixed. Format is a unix timestamp integer. last_found (int, optional) – Specifies the earliest time that a vulnerability may have been last seen. Format is a unix timestamp integer. num_assets (int, optional) – Specifies the number of assets returned per-chunk. If nothing is specified, it will default to 500 assets. plugin_family (list, optional) – list of plugin families to restrict the export to. values are interpreted with an insensitivity to case. severity (list, optional) – list of severities to include as part of the export. Supported values are info, low, medium, high, and critical. since (int, optional) – Returned results will be bounded based on the state of the vulnerability instance detailed below. This parameter expects a unix timestamp. Vulns in the open state are bounded by `first_found`. Vulns in the reopened state are bounded by `last_found`. Vulns in the fixed state are bounded by `last_fixed`. In short it’ll return active vulnerabilities based on when they were first discovered, and fixed and resurfaced vulnerabilities based on when they were last observed. The idea is to relay state changes of a vulnerability and use a singular export to track all of these state changes. state (list, optional) – list of object states to be returned. Supported values are open, reopened, and fixed. tags (list, optional) – List of tag key-value pairs that must be associated to the vulnerability data to be returned. Key-value pairs are tuples `('key', 'value')` and are case-sensitive. uuid (str, optional) – To re-request an iterator based off of an existing export, pass the UUID of the export to bypass the initial request and instead use the UUID passed to build the export iterator. vpr (dict, optional) – Restricts the results to the
Returns:	An iterator to walk through the results.
Return type:	`ExportIterator`

Examples

Export all of the vulnerability data:

>>> vulns = tio.exports.vulns()
>>> for vuln in vulns:
...     pprint(vuln)

Export only the critical vulnerabilities:

>>> for vuln in tio.exports.vulns(severity=['critical']):
...     pprint(vuln)

files¶

The following methods allow for interaction into the Tenable.io file API endpoints.

Methods available on tio.files:

class FileAPI(api)[source]¶

upload(fobj, encrypted=False)[source]¶

Uploads a file into Tenable.io.

file: upload

Parameters:	fobj (FileObject) – The file object intended to be uploaded into Tenable.io. encrypted (bool, optional) – If the file is encrypted, set the flag to True.
Returns:	The fileuploaded attribute
Return type:	`str`

Examples

>>> with open('file.txt') as fobj:
...     file_id = tio.files.upload(fobj)

filters¶

The following methods allow for interaction into the Tenable.io filters API endpoints.

Methods available on tio.filters:

class FiltersAPI(api)[source]¶

agents_filters(normalize=True)[source]¶

Returns agent filters.

filters: agents-filters

Returns:	Filter resource dictionary
Return type:	`dict`

Examples

>>> filters = tio.filters.agents_filters()

scan_filters(normalize=True)[source]¶

Returns the individual scan filters.

Returns:	Filter resource dictionary
Return type:	`dict`

Examples

>>> filters = tio.filters.scan_filters()

networks_filters()[source]¶

Returns the networks filters.

Returns:	Filter resource dictionary
Return type:	`dict`

Examples

>>> filters = tio.filters.network_filters()

workbench_asset_filters(normalize=True)[source]¶

Returns the asset workbench filters.

workbenches: assets-filters

Returns:	Filter resource dictionary
Return type:	`dict`

Examples

>>> filters = tio.filters.workbench_asset_filters()

workbench_vuln_filters(normalize=True)[source]¶

Returns the vulnerability workbench filters

workbenches: vulnerabilities-filters

Returns:	Filter resource dictionary
Return type:	`dict`

Examples

>>> filters = tio.filters.workbench_vuln_filters()

folders¶

The following methods allow for interaction into the Tenable.io folders API endpoints.

Methods available on tio.folders:

class FoldersAPI(api)[source]¶

create(name)[source]¶

Create a folder.

folders: create

Parameters:	name (str) – The name of the new folder.
Returns:	The new folder id.
Return type:	`int`

Examples

>>> folder = tio.folders.create('New Folder Name')

delete(id)[source]¶

Delete a folder.

folders: delete

Parameters:	id (int) – The unique identifier for the folder.
Returns:	`None`

Examples

>>> tio.folders.delete(1)

edit(id, name)[source]¶

Edit a folder.

folders: edit

Parameters:	id (int) – The unique identifier for the folder. name (str) – The new name for the folder.
Returns:	The folder was successfully renamed.
Return type:	`None`

Examples

>>> tio.folders.edit(1, 'Updated Folder Name')

list()[source]¶

Lists the available folders.

folders: list

Returns:	List of folder resource records.
Return type:	`list`

Examples

>>> for folder in tio.folders.list():
...     pprint(folder)

groups¶

The following methods allow for interaction into the Tenable.io groups API.

Methods available on tio.groups:

class GroupsAPI(api)[source]¶

add_user(group_id, user_id)[source]¶

Add a user to a user group.

groups: add-user

Parameters:	group_id (int) – The unique identifier of the group to add the user to. user_id (int) – The unique identifier of the user to add.
Returns:	The user was successfully added to the group.
Return type:	`None`

Examples

>>> tio.groups.add_user(1, 1)

create(name)[source]¶

Create a new user group.

groups: create

Parameters:	name (str) – The name of the group that will be created.
Returns:	The group resource record of the newly minted group.
Return type:	`dict`

Examples

>>> group = tio.groups.create('Group Name')

delete(id)[source]¶

Delete a user group.

groups: delete

Parameters:	id (int) – The unique identifier for the group to be deleted.
Returns:	The group was successfully deleted.
Return type:	`None`

Examples

>>> tio.groups.delete(1)

delete_user(group_id, user_id)[source]¶

Delete a user from a user group.

groups: delete-user

Parameters:	group_id (int) – The unique identifier for the group to be modified. user_id (int) – The unique identifier for the user to be removed from the group.
Returns:	The user was successfully removed from the group.
Return type:	`None`

Examples

>>> tio.groups.delete_user(1, 1)

edit(id, name)[source]¶

Edit a user group.

groups: edit

Parameters:	id (int) – The unique identifier for the group to be modified. name (str) – The new name for the group.
Returns:	The group resource record.
Return type:	`dict`

Examples

>>> tio.groups.edit(1, 'Updated name')

list()[source]¶

Lists all of the available user groups.

groups: list

Returns:	List of the group resource records
Return type:	`list`

Examples

>>> for group in tio.groups.list():
...     pprint(group)

list_users(id)[source]¶

List the user memberships within a specific user group.

groups: list-users

Parameters:	id (int) – The unique identifier of the group requested.
Returns:	List of user resource records based on membership to the specified group.
Return type:	`list`

Example

>>> for user in tio.groups.list_users(1):
...     pprint(user)

networks¶

The following methods allow for interaction into the Tenable.io networks API endpoints.

Methods available on tio.networks:

class NetworksAPI(api)[source]¶

assign_scanners(id, *scanner_uuids)[source]¶

Assigns one or many scanners to a network.

networks: assign-scanner networks: bulk-assign-scanner

Parameters:	id (str) – The UUID of the network. scanner_uuids (str*) – Scanner UUID(s) to assign to the network.

Examples

Assign a single scanner:

>>> tio.networks,assign_scanners(
...     '00000000-0000-0000-0000-000000000000', # Network UUID
...     '00000000-0000-0000-0000-000000000000') # Scanner UUID

Assign multiple scanners:

>>> tio.networks,assign_scanners(
...     '00000000-0000-0000-0000-000000000000', # Network UUID
...     '00000000-0000-0000-0000-000000000000', # Scanner1 UUID
...     '00000000-0000-0000-0000-000000000000') # Scanner2 UUID

create(name, description=None)[source]¶

Creates a new network within Tenable.io

networks: create

Parameters:	name (str) – The name of the new network. description (str, optional) – Description of the network.
Returns:	The resource record of the newly created network.
Return type:	`dict`

Examples

>>> nw = tio.networks.create('Example')

delete(id)[source]¶

Deletes the specified network.

networks: delete

Parameters:	id (str) – The UUID of the network to remove.

Examples

>>> tio.networks.delete('00000000-0000-0000-0000-000000000000')

details(id)[source]¶

Retreives the details of the specified network.

networks: details

Parameters:	id (str) – The UUID of the network.

Examples

>>> nw = tio.networks.details('00000000-0000-0000-0000-000000000000')

edit(id, name, description=None)[source]¶

Updates the specified network resource.

networks: update

Parameters:	id (str) – The UUID of the network resource to update. name (str) – The new name of the network resource. description (str, optional) – The new description of the network resource.
Returns:	The updates network resource.
Return type:	`dict`

Examples

>>> nw = tio.networks.edit('00000000-0000-0000-0000-000000000000',
...     'Updated Network', 'Updated Description')

list(*filters, **kw)[source]¶

Get the listing of configured networks from Tenable.io.

networks: list

Parameters:	filters (tuple, optional) – Filters are tuples in the form of (‘NAME’, ‘OPERATOR’, ‘VALUE’). Multiple filters can be used and will filter down the data being returned from the API. Examples `('name', 'eq', 'example')` As the filters may change and sortable fields may change over time, it’s highly recommended that you look at the output of the `tio.networks.network_filters()` endpoint to get more details. filter_type* (str, optional) – The filter_type operator determines how the filters are combined together. `and` will inform the API that all of the filter conditions must be met for an access group to be returned, whereas `or` would mean that if any of the conditions are met, the access group record will be returned. include_deleted (bool, optional) – Indicates whether deleted network objects should be included in the response. If left unspecified, the default is `False`. limit (int, optional) – The number of records to retrieve. Default is 50 offset (int, optional) – The starting record to retrieve. Default is 0. sort (tuple, optional) – A tuple of tuples identifying the the field and sort order of the field. wildcard (str, optional) – A string to pattern match against all available fields returned. wildcard_fields (list, optional) – A list of fields to optionally restrict the wild-card matching to.
Returns:	An iterator that handles the page management of the requested records.
Return type:	`NetworksIterator`

Examples

Getting the listing of all agents:

>>> for nw in tio.networks.list():
...     pprint(nw)

Retrieving all of the windows agents:

>>> for nw in tio.access_groups.list(('name', 'match', 'win')):
...     pprint(nw)

list_scanners(id)[source]¶

Retreives the list of scanners associated to a given network.

networks: list-scanners

Parameters:	id (str) – The UUID of the network.
Returns:	List of scanner resources associated to this network.
Return type:	`list`

Examples

>>> network = '00000000-0000-0000-0000-000000000000'
>>> for scanner in tio.networks.list_scanners(network):
...     pprint(scanner)

unassigned_scanners(id)[source]¶

Retrives the list of scanners that are currently unassigned to the given network. This will include scanners and scanner groups that are currently assigned to the default network.

networks: list-assignable-scanners

Parameters:	id (str) – The UUID of the network.
Returns:	The list of unassigned scanner resources
Return type:	`list`

Examples

>>> network = '00000000-0000-0000-0000-000000000000'
>>> for scanner in tio.networks.unassigned_scanners(network):
...     pprint(scanner)

permissions¶

The following methods allow for interaction into the Tenable.io :devportal`permissions <permissions-1>` API endpoints.

Methods available on tio.permissions:

class PermissionsAPI(api)[source]¶

change(otype, id, *acls)[source]¶

Modify the permission of a specific object.

permissions: change

Parameters:	otype (str) – The type of object to change. id (int) – The unique identifier fo the object. acls (dict*) – ACL dictionaries inform Tenable.io how to handle permissions of the various objects within Tenable.io. Please refer to the permissions documentation for more details.
Returns:	The object permissions were successfully changed.
Return type:	`None`

list(otype, id)[source]¶

List the permissions of a specific object.

permissions: list

Parameters:	otype (str) – The type of object being queried. id (int) – The unique identifier of the object.
Returns:	The permission recourse record listings for the specified object.
Return type:	`list`

plugins¶

The following methods allow for interaction into the Tenable.io plugins API endpoints.

Methods available on tio.plugins:

class PluginsAPI(api)[source]¶

families()[source]¶

List the available plugin families.

plugins: families

Returns:	List of plugin family resource records.
Return type:	`list`

Examples

>>> for family in tio.plugins.families():
...     pprint(family)

family_details(id)[source]¶

Retrieve the details for a specific plugin family.

devportalplugins: family-details plugins-family-details>

Parameters:	id (int) – The plugin family unique identifier.
Returns:	Returns a dictionary stating the id, name, and plugins that are housed within the plugin family.
Return type:	`dict`

Examples

>>> family = tio.plugins.family_details(1)

list(page=None, size=None, last_updated=None, num_pages=None)[source]¶

Get the listing of plugin details from Tenable.io.

:devportal:`plugins: list <>`_

Parameters:	size (int, optional) – The number of records to retrieve. Default is 1000 page (int, optional) – The starting page to retrieve. Default is 0. last_updated (date, optional) – A datetime.date object stating when the threshold for the last updated field can be for a plugin. num_pages (int, optional) – The total number of pages to request before stopping the iterator.
Returns:	An iterator that handles the page management of the requested records.
Return type:	`PluginsIterator`

Examples

Getting the listing of all plugins:

>>> for plugin in tio.plugins.list():
...     pprint(plugin)

Retrieving all of the plugins updated since 2019-01-01:

>>> for plugin in tio.plugins.list(last_updated=date(2019, 1, 1)):
...     pprint(plugin)

Informing the iterator to cache the plugin family data for injection into each item:

>>> plugins = tio.plugins.list(last_updated=date(2019, 1, 1))
>>> plugins.populate_maptable = True
>>> for plugin in plugins:
...     pprint(plugin)

plugin_details(id)[source]¶

Retrieve the details for a specific plugin.

plugins: plugin-details

Parameters:	id (int) – The plugin id for the requested plugin.
Returns:	A dictionary stating the id, name, family, and any other relevant attributes associated to the plugin.
Return type:	`dict`

Examples

>>> plugin = tio.plugins.plugin_details(19506)
>>> pprint(plugin)

policies¶

The following methods allow for interaction into the Tenable.io policies API.

Methods available on tio.policies:

class PoliciesAPI(api)[source]¶

configure(id, policy)[source]¶

Configures an existing policy.

policies: configure

Parameters:	id (int) – The policy unique identifier. policy (dict) – The updated policy definition to push into Tenable.io. As these policies can be quite complex, please refer to the documentation in the policies: configure page (linked above).
Returns:	Policy successfully modified.
Return type:	`None`

Examples

>>> policy = tio.policies.details(1)
>>> policy['settings']['name'] = 'Updated Policy Name'
>>> tio.policies.configure(policy)

copy(id)[source]¶

Duplicates a scan policy and returns the copy.

policies: copy

Parameters:	id (int) – The unique identifier of the policy you wish to copy.
Returns:	A dictionary containing the name and id of the policy copy.
Return type:	`dict`

Example

>>> policy = tio.policies.copy(1)

create(policy)[source]¶

Creates a new scan policy based on the policy dictionary passed.

policies: configure

Parameters:	policy (dict) – The policy definition to push into Tenable.io. As these policies can be quite complex, please refer to the documentation in the policies: configure page (linked above).
Returns:	A dictionary containing the name and id of the new policy.
Return type:	`dict`

Examples

>>> policy = tio.policies.template_details('basic')
>>> policy['settings']['name'] = 'New Scan Policy'
>>> info = tio.policies.create(policy)

delete(id)[source]¶

Delete a custom policy.

policies: delete

Parameters:	id (int) – The unique identifier of the policy to delete.
Returns:	The policy was successfully deleted.
Return type:	`None`

Examples

>>> tio.policies.delete(1)

details(id)[source]¶

Retrieve the details for a specific policy.

policies: details

Parameters:	id (int) – The unique identifier of the policy.
Returns:	The dictionary definition of the policy.
Return type:	`dict`

Examples

>>> policy = tio.policies.details(1)

policy_import(fobj)[source]¶

Imports a policy into Tenable.io.

policies: import

Parameters:	fobj (FileObject) – The file object of the scan policy you wish to import.
Returns:	The dictionary of the imported policy.
Return type:	`dict`

Examples

>>> with open('example.nessus') as policy:
...     tio.policies.import(policy)

policy_export(id, fobj=None)[source]¶

Exports a specified policy from Tenable.io.

policies: export

Parameters:	id (int) – The unique identifier of the policy to export. fobj (FileObject, optional) – A file-like object to write the contents of the policy to. If none is provided a BytesIO object will be returned with the policy.
Returns:	A file-like object containing the contents of the policy in XML format.
Return type:	`FileObject`

Examples

>>> with open('example.nessus', 'wb') as policy:
...     tio.policies.export(1, policy)

list()[source]¶

List the available custom policies.

policies: list

Returns:	List of policy resource documents.
Return type:	`list`

Examples

>>> for policy in tio.policies.list():
...     pprint(policy)

scanner_groups¶

The following methods allow for interaction into the Tenable.io scanner-groups API endpoints.

Methods available on tio.scanner_groups:

class ScannerGroupsAPI(api)[source]¶

add_scanner(group_id, scanner_id)[source]¶

Add a scanner to a scanner group.

scanner-groups: add-scanner

Parameters:	group_id (int) – The unique identifier of the scanner group. scanner_id (int) – The unique identifier of the scanner.
Returns:	Scanner successfully added to the scanner group.
Return type:	`None`

Examples

>>> tio.scanner_groups.add_scanner(1, 1)

create(name, group_type=None)[source]¶

Create a scanner group.

scanner-groups: create

Parameters:	name (str) – The name of the scanner group to create group_type (str, optional) – The type of scanner group to create. Currently the only supported type is “load_balancing”
Returns:	The scanner group resource record for the created group.
Return type:	`dict`

Example

>>> group = tio.scanner_groups.create('Scanner Group')

delete(id)[source]¶

Deletes a scanner group.

scanner-groups: delete

Parameters:	id (int) – The unique identifier for the scanner group to delete.
Returns:	The scanner group has been successfully deleted.
Return type:	`None`

Examples

>>> tio.scanner_groups.delete(1)

delete_scanner(group_id, scanner_id)[source]¶

Removes a scanner from a scanner group.

scanner-groups: delete-scanner

Parameters:	group_id (int) – The unique identifier of the scanner group. scanner_id (int) – The unique identifier of the scanner to remove from the requested scanner group.
Returns:	The scanner was successfully removed from the scanner group.
Return type:	`None`

Examples

>>> tio.scanner_groups.delete_scanner(1, 1)

details(id)[source]¶

Retrieves the details about a scanner group.

scanner-groups: details

Parameters:	id (int) – The unique identifier for the scanner group.
Returns:	The scanner group resource record.
Return type:	`dict`

Examples

>>> group = tio.scanner_groups.details(1)
>>> pprint(group)

edit(id, name)[source]¶

Modifies a scanner group.

scanner-groups: edit

Parameters:	id (int) – The unique identifier for the scanner group. name (str) – The new name for the scanner group.
Returns:	The scanner group has been successfully updated.
Return type:	`None`

Examples

>>> tio.scanner_groups.edit(1, 'New Group Name')

list()[source]¶

Lists the configured scanner groups.

scanner-groups: list

Returns:	List of scanner group resource records.
Return type:	`list`

Examples

>>> for group in tio.scanner_groups.list():
...     pprint(group)

list_scanners(id)[source]¶

List the scanners within a specific scanner group.

devportalscanner-groups: list-scanners scanner-groups-list-scanners>

Parameters:	id (int) – The unique identifier of the scanner group.
Returns:	List of scanner resource records associated to the scanner group.
Return type:	`list`

Examples

>>> for scanner in tio.scanner_groups.list_scanners(1):
...     pprint(scanner)

scanners¶

The following methods allow for interaction into the Tenable.io scanners API.

Methods available on tio.scanners:

class ScannersAPI(api)[source]¶

control_scan(scanner_id, scan_uuid, action)[source]¶

Perform actions against scans on a given scanner.

scanners: control-scans

Parameters:	scanner_id (int) – The unique identifier for the scanner. scan_uuid (uuid) – The unique identifier for the scan. action (str) – The action to take upon the scan. Valid actions are stop, pause, and resume.
Returns:	The action was sent to the scan successfully.
Return type:	`None`

Examples

Stop a scan running on the scanner:

>>> tio.scanners.control_scan(1, '00000000-0000-0000-0000-000000000000', 'stop')

delete(id)[source]¶

Delete a scanner from Tenable.io.

scanners: delete

Parameters:	id (int) – The unique identifier for the scanner to delete.
Returns:	The scanner was successfully deleted.
Return type:	`None`

Examples

>>> tio.scanners.delete(1)

details(id)[source]¶

Retrieve the details for a specified scanner.

scanners: details

Parameters:	id (int) – The unique identifier for the scanner
Returns:	The scanner resource record.
Return type:	`dict`

Examples

>>> scanner = tio.scanners.details(1)
>>> pprint(scanner)

edit(id, **kwargs)[source]¶

Modify the scanner.

scanners: edit

Parameters:	id (int) – The unique identifier for the scanner. force_plugin_update (bool, optional) – Force the scanner to perform a plugin update . force_ui_update (bool, optional) – Force the scanner to perform a UI update. finish_update (bool, optional) – Force the scanner to reboot to complete the update process. This action is only valid when automatic updates are disabled. registration_code (str, optional) – Sets the registration code for the scanner. aws_update_interval (int, optional) – For AWS scanners this will inform the scanner how often to check into Tenable.io.
Returns:	The operation was requested successfully.
Return type:	`None`

Examples

Force a plugin update on a scanner:

>>> tio.scanners.edit(1, force_plugin_update=True)

get_aws_targets(id)[source]¶

Returns the list of AWS targets the scanner can reach.

scanners: get-aws-targets

Parameters:	id (int) – The unique identifier for the scanner.
Returns:	List of aws target resource records.
Return type:	`list`

Examples

>>> for target in tio.scanners.get_aws_targets(1):
...      pprint(target)

get_scanner_key(id)[source]¶

Return the key associated with the scanner.

scanners: get-scanner-key

Parameters:	id (int) – The unique identifier for the scanner.
Returns:	The scanner key
Return type:	`str`

Examples

>>> print(tio.scanners.get_scanner_key(1))

get_scans(id)[source]¶

Retrieves the scans associated to the scanner.

scanners: get-scans

Parameters:	id (int) – The unique identifier for the scanner.
Returns:	List of scan resource records associated to the scanner.
Return type:	`list`

Examples

>>> for scan in tio.scanners.get_scans(1):
...     pprint(scan)

linking_key()[source]¶

The linking key for the Tenable.io instance.

Returns:	The linking key
Return type:	`str`

Examples

>>> print(tio.scanners.linking_key())

list()[source]¶

Retrieves the list of scanners.

scanners: list

Returns:	List of scanner resource records.
Return type:	`list`

Examples

>>> for scanner in tio.scanners.list():
...     pprint(scanner)

toggle_link_state(id, linked)[source]¶

Toggles the scanner’s activated state.

scanners: toggle-link-state

Parameters:	id (int) – The unique identifier for the scanner linked (bool) – The link status of the scanner. Setting to False will disable the link, whereas setting to True will enable the link.
Returns:	The status change was successful.
Return type:	`None`

Examples

to deactivate a linked scanner:

>>> tio.scanners.toggle_link_state(1, False)

scans¶

The following methods allow for interaction into the Tenable.io scans API endpoints.

Methods available on tio.scans:

class ScansAPI(api)[source]¶

attachment(scan_id, attachment_id, key, fobj=None)[source]¶

Retrieve an attachment associated to a scan.

scans: attachments

Parameters:	scan_id (int) – The unique identifier for the scan. attachment_id (int) – The unique identifier for the attachement key (str) – The attachement access token. fobj (FileObject, optional) – a file-like object you wish for the attachement to be written to. If none is specified, a BytesIO object will be returned with the contents of the attachment.
Returns:	A file-like object with the attachement written into it.
Return type:	`FileObject`

Examples

>>> with open('example.file', 'wb') as fobj:
...     tio.scans.attachement(1, 1, 'abc', fobj)

configure(id, **kw)[source]¶

Overwrite the parameters specified on top of the existing scan record.

scans: configure

Parameters:	id (int) – The unique identifier for the scan. template (str, optional) – The scan policy template to use. If no template is specified then the default of basic will be used. policy (int, optional) – The id or title of the scan policy to use (if not using one of the pre-defined templates). Specifying a a policy id will override the the template parameter. targets (list, optional) – If defined, then a list of targets can be specified and will be formatted to an appropriate text_target attribute. credentials (dict, optional) – A list of credentials to use. compliance (dict, optional) – A list of compliance audiots to use. scanner (str, optional) – Define the scanner or scanner group uuid or name. *kw (dict, optional*) – The various parameters that can be passed to the scan creation API. Examples would be name, email, scanner_id, etc. For more detailed information, please refer to the API documentation linked above.
Returns:	The scan resource record.
Return type:	`dict`

Examples

>>> tio.scans.configure(1, name='New Scan Name')

copy(scan_id, folder_id=None, name=None)[source]¶

Duplicates a scan and returns the details of the copy.

scans: copy

Parameters:	scan_id (int) – The unique identifier for the scan. folder_id (int, optional) – The unique identifier for the folder. name (str, optional) – The name for the copied scan.
Returns:	The scan resource record for the copied scan.
Return type:	`dict`

Examples

>>> new_scan = tio.scans.copy(1, 'New Scan Name')

create(**kw)[source]¶

Create a new scan.

scans: create

Parameters:	name (str) – The name of the scan to create. template (str, optional) – The scan policy template to use. If no template is specified then the default of basic will be used. policy (int, optional) – The id or title of the scan policy to use (if not using one of the pre-defined templates). Specifying a a policy id will override the the template parameter. targets (list, optional) – If defined, then a list of targets can be specified and will be formatted to an appropriate text_target attribute. credentials (dict, optional) – A list of credentials to use. compliance (dict, optional) – A list of compliance audits to use. scanner (str, optional) – Define the scanner or scanner group uuid or name. *kw (dict, optional*) – The various parameters that can be passed to the scan creation API. Examples would be name, email, scanner_id, etc. For more detailed information, please refer to the API documentation linked above.
Returns:	The scan resource record of the newly created scan.
Return type:	`dict`

Examples

Create an un-credentialed basic scan:

>>> scan = tio.scans.create(
...     name='Example Scan',
...     targets=['127.0.0.1'])

Creating a scan with a set of managed credentials:

>>> scan = tio.scans.create(
...     name='Example Managed Cred Scan',
...     targets=['127.0.0.1'],
...     credentials={'Host': {'SSH': [{'id': 'CREDENTIAL-UUID'}]}}

Creating a scan with a set of embedded credentials:

>>> scan = tio.scans.create(
...     name='Example Embedded Cred Scan',
...     targets=['127.0.0.1'],
...     credentials={'Host': {'Windows': [{
...         'domain': '',
...         'username': 'Administrator',
...         'password': 'sekretsquirrel',
...         'auth_method': 'Password'
...     }]}}
... )

For further information on credentials, what settings to use, etc, refer to this doc on the developer portal.

delete(scan_id)[source]¶

Remove a scan.

scans: delete

Parameters:	scan_id (int) – The unique identifier for the scan.
Returns:	The scan was successfully deleted.
Return type:	`None`

Examples

>>> tio.scans.delete(1)

delete_history(scan_id, history_id)[source]¶

Remove an instance of a scan from a scan history.

scans: delete-history

Parameters:	scan_id (int) – The unique identifier for the scan. history_id (int) – The unique identifier for the instance of the scan.
Returns:	Scan history successfully deleted.
Return type:	`None`

Examples

>>> tio.scans.delete_history(1, 1)

details(scan_id)[source]¶

Calls the editor API and parses the scan config details to return a document that closely matches what the API expects to be POSTed or PUTed via the create and configure methods. The compliance audits and credentials are populated into the ‘current’ sub-document for the relevant resources.

Important

Please note that the details method is reverse-engineered from the responses from the editor API, and while we are reasonably sure that the response should align almost exactly to what the API expects to be pushed to it, this method by very nature of what it’s doing isn’t guaranteed to always work.

Parameters:	scan_id (int) – The unique identifier for the scan.
Returns:	The scan configuration resource.
Return type:	`dict`

Examples

>>> scan = tio.scans.details(1)
>>> pprint(scan)

export(scan_id, *filters, **kw)[source]¶

Export the scan report.

scans: export

Parameters:	scan_id (int) – The unique identifier of the scan. filters (tuple, optional) – A list of tuples detailing the filters that wish to be applied the response data. Each tuple is constructed as (‘filter’, ‘operator’, ‘value’) and would look like the following example: (‘plugin.id’, ‘eq’, ‘19506’). For a complete list of the available filters and options, please refer to the API documentation linked above. history_id* (int, optional) – The unique identifier for the instance of the scan. format (str, optional) – What format would you like the resulting data to be in. The default would be nessus output. Available options are nessus, csv, html, pdf, db. Default is nessus. password (str, optional) – If the export format is db, then what is the password used to encrypt the NessusDB file. This is a require parameter for NessusDB exports. chapters (list, optional) – A list of the chapters to write for the report. The chapters list is only required for PDF and HTML exports. Available chapters are vuln_hosts_summary, vuln_by_host, compliance_exec, remediations, vuln_by_plugin, and compliance. List order will denote output order. Default is vuln_by_host. filter_type (str, optional) – Are the filters exclusive (this AND this AND this) or inclusive (this OR this OR this). Valid values are and and or. The default setting is and. scan_type (str, optional) – This parameter is required only when using the API with Web Application Scanning. Available option is ‘web-app’. fobj (FileObject, optional) – The file-like object to be returned with the exported data. If no object is specified, a BytesIO object is returned with the data. While this is an optional parameter, it is highly recommended to use this parameter as exported files can be quite large, and BytesIO objects are stored in memory, not on disk.
Returns:	The file-like object of the requested export.
Return type:	`FileObject`

Examples

Export the full report of the latest instance of the scan:

>>> with open('example.nessus', 'wb') as reportobj:
...     tio.scans.export(1, fobj=reportobj)

Export a specific instance of the scan:

>>> with open('example.nessus', 'wb') as reportobj:
...     tio.scans.export(1, history_id=1, fobj=reportobj)

history(id, limit=None, offset=None, pages=None)[source]¶

Get the scan history of a given scan from Tenable.io.

scans: history

Parameters:	id (int) – The unique identifier for the scan. limit (int, optional) – The number of records to retrieve. Default is 50 offset (int, optional) – The starting record to retrieve. Default is 0.
Returns:	An iterator that handles the page management of the requested records.
Return type:	`ScanHistoryIterator`

Examples

>>> for history in tio.scans.history(1):
...     pprint(history)

host_details(scan_id, host_id, history_id=None)[source]¶

Retrieve the host details from a specific scan.

scans: host-details

Parameters:	scan_id (int) – The unique identifier for the scan. host_id (int) – The unique identifier for the host within the scan. histort_id (int, optional) – The unique identifier for the instance of the scan.
Returns:	The information related to the host requested.
Return type:	`dict`

Examples

>>> host = tio.scans.host_details(1, 1)

import_scan(fobj, folder_id=None, password=None, aggregate=None)[source]¶

Import a scan report into Tenable.io.

scans: import

Parameters:	fobj (FileObject) – The File-like object of the scan to import. folder_id (int, optional) – The unique identifier for the folder to place the scan into. password (str, optional) – The password needed to decrypt the file. This is only necessary for NessusDB files uploaded. aggregate (bool, optional) – should the Nessus report be aggregated into the aggregate results? The default is True.
Returns:	The scan resource record for the imported scan.
Return type:	`dict`

Examples

Import a .nessusv2 report:

>>> with open('example.nessus') as reportobj:
...     tio.scans.import(reportobj)

Import a NessusDB report.

>>> with open('example.db') as reportobj:
...     tio.scans.import(reportobj, password='sekret')

info(scan_id, history_uuid)[source]¶

Retrieves information about the status of the specified instance of the scan.

scan: get-scan-history

Parameters:	scan_id (int) – The unique identifier for the scan. history_uuid (str) – The unique identifier for the scan instance.
Returns:	The metadata about the scan instance specified.
Return type:	`dict`

Examples

>>> info = tio.scans.info(1, 'BA0ED610-C27B-4096-A8F4-3189279AFFE7')

launch(scan_id, targets=None)[source]¶

Launches a scan.

scans: launch

Parameters:	scan_id (int) – The unique identifier for the scan. targets (list, optional) – A list of targets to be scanned instead of the default targets in the scan.

Response:

str:: The uuid of the scan instance (history).

Examples

Launch the scan with the configured targets:

>>> tio.scans.launch(1)

Launch the scan with some custom targets:

>>> tio.scans.launch(1, targets=['127.0.0.1'])

list(folder_id=None, last_modified=None)[source]¶

Retrieve the list of configured scans.

scans: list

Parameters:	folder_id (int, optional) – Only return scans within this folder. last_modified (datetime, optional) – Only return scans that have been modified since the time specified.
Returns:	A list containing the list of scan resource records.
Return type:	`list`

Examples

>>> for scan in tio.scans.list():
...     pprint(scan)

pause(scan_id, block=False)[source]¶

Pauses a running scan.

scans: pause

Parameters:	scan_id (int) – The unique identifier fo the scan to pause. block (bool, optional) – Block until the scan is actually paused. Default is False.
Returns:	The scan was successfully requested to be paused.
Return type:	`None`

Examples

>>> tio.scans.pause(1)

plugin_output(scan_id, host_id, plugin_id, history_id=None)[source]¶

Retrieve the plugin output for a specific instance of a vulnerability on a host.

scans: plugin-output

Parameters:	scan_id (int) – The unique identifier of the scan. host_id (int) – The unique identifier of the scanned host. plugin_id (int) – The plugin id. history_id (int, optional) – The unique identifier of the scan instance.
Returns:	The plugin resource record for that plugin on that host.
Return type:	`dict`

Examples

>>> output = tio.scans.plugin_output(1, 1, 1)
>>> pprint(output)

results(scan_id, history_id=None)[source]¶

Return the scan results from either the latest scan or a specific scan instance in the history.

scans: details

Parameters:	scan_id (int) – The unique identifier for the scan. history_id (int, optional) – The unique identifier for the instance of the scan.
Returns:	The scan result dictionary.
Return type:	`dict`

Examples

Retrieve the latest results:

>>> results = tio.scans.results(1)

Retrieve a specific instance of the result set:

>>> results = tio.scans.results(1, 1)

resume(scan_id)[source]¶

Resume a paused scan.

scans: resume

Parameters:	scan_id (int) – The unique identifier for the scan.
Returns:	The scan was successfully requested to resume.
Return type:	`None`

Examples

>>> tio.scans.resume(1)

schedule(scan_id, enabled)[source]¶

Enables or disables the scan schedule.

scans: schedule

Parameters:	scan_id (int) – The unique identifier for the scan. enabled (bool) – Enables or Disables the scan scheduling.
Returns:	The schedule resource record for the scan.
Return type:	`dict`

Examples

Enable a scan schedule:

>>> tio.scans.schedule(1, True)

set_read_status(scan_id, read_status)[source]¶

Sets the read status of the scan. This is generally used to toggle the unread status of the scan within the UI.

scans: read-status

Parameters:	scan_id (int) – The unique identifier for the scan. read_status (bool) – Is the scan in a read or unread state? True would denote read, whereas False is unread.
Returns:	The status of the scan was updated.
Return type:	`None`

Examples

Set a scan to unread:

>>> tio.scans.set_read_status(1, False)

status(scan_id)[source]¶

Get the status of the latest instance of the scan.

scans: get-latest-status

Parameters:	scan_id (int) – The unique identifier for the scan.
Returns:	The current status of the last instance.
Return type:	`str`

Examples

>>> tio.scans.status(1)
u'completed'

stop(scan_id, block=False)[source]¶

Stop a running scan.

scans: stop

Parameters:	scan_id (int) – The unique identifier for the scan. block (bool, optional) – Block until the scan is actually stopped. Default is False.
Returns:	The scan was successfully requested to stop.
Return type:	`None`

Examples

Stop the scan asynchronously:

>>> tio.scans.stop(1)

Stop the scan and wait for the scan to stop:

>>> tio.scans.stop(1, True)

timezones()[source]¶

Retrieves the list of timezones.

scans: timezones

Returns:	List of allowed timezone strings accepted by Tenable.IO
Return type:	`list`

Examples

>>> for item in tio.scans.timezones():
...     pprint(item)

server¶

The following methods allow for interaction into the Tenable.io server API endpoints.

Methods available on tio.server:

class ServerAPI(api)[source]¶

properties()[source]¶

Retrieves the various properties used within the Tenable.io instance.

server: properties

Returns:	The server properties.
Return type:	`dict`

Examples

>>> props = tio.server.properties()
>>> pprint(props)

status()[source]¶

Retrieves the server status of the Tenable.io instance.

server: status

Returns:	The server status.
Return type:	`dict`

Examples

>>> status = tio.server.status()
>>> pprint(status)

session¶

The following methods allow for interaction into the Tenable.io session API endpoints.

Methods available on tio.session:

class SessionAPI(api)[source]¶

change_password(old_password, new_password)[source]¶

Change the password of the current user.

session: password

Parameters:	old_password (str) – The current password. new_password (str) – The new password.
Returns:	The password has been successfully changed.
Return type:	`None`

Examples

>>> tio.session.change_password('old_pass', 'new_pass')

details()[source]¶

Retrieve the current users resource record.

session: get

Returns:	The user’s session resource record.
Return type:	`dict`

Examples

>>> user = tio.session.details()
>>> pprint(user)

edit(name, email)[source]¶

Modify the currently logged-in user.

session: edit

Parameters:	name (str) – The full name of the user. email (str) – The email address of the user.
Returns:	The session data for the current user.
Return type:	`dict`

Examples

>>> tio.session.edit('John Doe', 'joe@company.com')

gen_api_keys()[source]¶

Generate new API keys for the current user.

session: keys

Returns:	A dictionary containing the new API Keypair.
Return type:	`dict`

Examples

>>> keys = tio.session.gen_api_keys()

two_factor(email, sms, phone=None)[source]¶

Configure two-factor authorization.

session: two-factor

Parameters:	email (bool) – Whether two-factor should be additionally sent as an email. sms (bool) – Whether two-factor should be enabled. This will send SMS codes. phone (str, optional) – The phone number to use for two-factor authentication. Required when sms is set to True.
Returns:	Setting changes were successfully updated.
Return type:	`None`

Example

Configure email multi-factor auth:

>>> tio.session.two_factor(True, False)

Configure SMS multi-factor auth:

>>> tio.session.two_factor(False, True, '9998887766')

enable_two_factor(phone)[source]¶

Initiate the phone-based two-factor authorization verification process.

session: two-factor-enable

Parameters:	phone (str) – The phone number to use for two-factor auth.
Returns:	One-time activation code sent to the provided phone number.
Return type:	`None`

Examples

>>> tio.session.enable_two_factor('9998887766')

verify_two_factor(code)[source]¶

Send the verification code for two-factor authorization.

session: verify-code

Parameters:	code (str) – The verification code that was sent to the device.
Returns:	The verification code was valid and two-factor is enabled.
Return type:	`None`

Examples

>>> tio.session.verify_two_factor('abc123')

restore()[source]¶

Restore the session to the logged-in user. This will remove any user impersonation setting that have been set.

session: restore

Returns:	The session has properly been restored to the original user.
Return type:	`None`

Example

>>> tio.session.restore()

tags¶

The following methods allow for interaction into the Tenable.io tagging API endpoints.

Methods available on tio.tags:

class TagsAPI(api)[source]¶

create(category, value, description=None, filters=None, category_description=None)[source]¶

Create a tag category/value pair

tags: create-tag-value

Parameters:	category (str) – The category name, or the category UUID. If the category does not exist, then it will be created along with the new value. value (str) – The value for the tag. category_description (str, optional) – If the category is to be created, a description can be optionally provided. description (str, optional) – A description for the Category/Value pair. filters (dict, optional) – The filter dictionary as specified within the API documents.
Returns:	Tag value resource record
Return type:	`dict`

Examples

Creating a new tag & Category:

>>> tio.tags.create('Location', 'Chicago')

Creating a new Tag value in the existing Location Category:

>>> tio.tags.create('Location', 'New York')

Creating a new Tag Value within a Category by UUID:

>>> tio.tags.create('00000000-0000-0000-0000-000000000000', 'Madison')

create_category(name, description=None)[source]¶

Creates a new category

tags: create-category

Parameters:	name (str) – The name of the category to create description (str, optional) – Description for the category to create.
Returns:	Tag category resource record
Return type:	`dict`

Examples

>>> tio.tags.create_category('Location')

delete(tag_value_uuid)[source]¶

Deletes a tag category/value pair.

tag: delete tag value

Parameters:	tag_value_uuid (str) – The unique identifier for the c/v pair to be deleted.
Returns:	`None`

Examples

>>> tio.tags.delete('00000000-0000-0000-0000-000000000000')

delete_category(tag_category_uuid)[source]¶

Deletes a tag category.

tag: delete tag category

Parameters:	tag_category_uuid (str) – The unique identifier for the tag category to be deleted.
Returns:	`None`

Examples

>>> tio.tags.delete('00000000-0000-0000-0000-000000000000')

details(tag_value_uuid)[source]¶

Retrieves the details for a specific tag category/value pair.

tag: tag details

Parameters:	tag_value_uuid (str) – The unique identifier for the c/v pair
Returns:	Tag value resource record
Return type:	`dict`

Examples

>>> tio.tags.details('00000000-0000-0000-0000-000000000000')

details_category(tag_category_uuid)[source]¶

Retrieves the details for a specific tag category.

tag: tag category details

Parameters:	tag_category_uuid (str) – The unique identifier for the category
Returns:	Tag category resource record
Return type:	`dict`

Examples

>>> tio.tags.details_category('00000000-0000-0000-0000-000000000000')

edit(tag_value_uuid, value=None, description=None, filters=None)[source]¶

Updates Tag category/value pair information.

tag: edit tag value

Parameters:	tag_value_uuid (str) – The unique identifier for the c/v pair to be edited. value (str, optional) – The new name for the category value. description (str, optional) – New description for the category value. filters (dict, optional) – The filter dictionary as specified within the API documents.
Returns:	Tag value resource record.
Return type:	`dict`

Examples

>>> tio.tags.edit('00000000-0000-0000-0000-000000000000',
...     name='NewValueName')

edit_category(tag_category_uuid, name=None, description=None)[source]¶

Updates Tag category information.

tag: edit tag category

Parameters:	tag_category_uuid (str) – The unique identifier for the category to be edited. name (str, optional) – The new name for the category. description (str, optional) – New description for the category.
Returns:	Tag category resource record.
Return type:	`dict`

Examples

>>> tio.tags.edit_category('00000000-0000-0000-0000-000000000000',
...     name='NewValueName')

list(*filters, **kw)[source]¶

Retrieves a list of tag category/value pairs based off of the filters defined within the query.

tags: list tags

Parameters:	filters (tuple, optional) – A defined filter tuple consisting of the name, operator, and value. Example: `('category_name', 'eq', 'Location')`. filter_type* (str, optional) – If multiple filters are defined, the filter_type toggles the behavior as to how these filters are used. Either all of the filters have to match (`AND`) or any of the filters have to match (`OR`). If not specified, the default behavior is to assume filter_type is `AND`. limit (int, optional) – How many records should be returned in a given page. If nothing is set, it will default to 1000 records. pages (int, optional) – How many pages of data would you like to request? offset (int, optional) – How many records to skip before returning results. If nothing is set, it will default to 0. sort (str, optional) – What field to sort the results on.
Returns:	An iterator that handles the pagination of the results
Return type:	`TagIterator`

Examples

Return all of the Tag Values:

>>> for tag in tio.tags.list():
...     pprint(tag)

Return all of the Tags of the Location category:

>>> for tag in tio.tags.list(('category_name', 'eq', 'Location')):
...     pprint(tag)

list_categories(*filters, **kw)[source]¶

Retrieves a list of tag categories based off of the filters defined within the query.

tags: list categories

Parameters:	filters (tuple, optional) – A defined filter tuple consisting of the name, operator, and value. Example: `('category_name', 'eq', 'Location')`. filter_type* (str, optional) – If multiple filters are defined, the filter_type toggles the behavior as to how these filters are used. Either all of the filters have to match (`AND`) or any of the filters have to match (`OR`). If not specified, the default behavior is to assume filter_type is `AND`. limit (int, optional) – How many records should be returned in a given page. If nothing is set, it will default to 1000 records. pages (int, optional) – How many pages of data would you like to request? offset (int, optional) – How many records to skip before returning results. If nothing is set, it will default to 0. sort (str, optional) – What field to sort the results on.
Returns:	An iterator that handles the pagination of the results
Return type:	`TagIterator`

Examples

Return all of the Tag Categories:

>>> for tag in tio.tags.list_categories():
...     pprint(tag)

Return all of the Tags of the Location category:

>>> for tag in tio.tags.list_categories(
...   ('category_name', 'eq', 'Location')):
...     pprint(tag)

target_groups¶

The following methods allow for interaction into the Tenable.io target_groups API endpoints.

Methods available on tio.target_groups:

class TargetGroupsAPI(api)[source]¶

create(name, members, **kw)[source]¶

Create a target-group.

target-groups: create

Parameters:	name (str) – The name of the target group members (list) – The members of the target group. FQDNs, CIDRs, IPRanges, and individual IPs are supported. type (str, optional) – The type of target group to create. Valid types are user and system. The default if not specified is user. acls (list, optional) – A list of ACLs defining how the asset list can be used. For further information on how the ACL dictionaries should be written, please refer to the API documentation.
Returns:	The resource record of the newly created target group.
Return type:	`dict`

Examples

>>> tg = tio.target_groups.create('Example', ['192.168.0.0/24'])

delete(id)[source]¶

Delete a target group.

target-groups: delete

Parameters:	id (int) – The unique identifier for the target group.
Returns:	The target group was successfully deleted.
Return type:	`None`

Examples

>>> tio.target_groups.delete(1)

details(id)[source]¶

Retrieve the details of a target group.

target-groups: details

Parameters:	id (int) – The unique identifier for the target group.
Returns:	The resource record for the target group.
Return type:	`dict`

Examples

>>> tg = tio.target_groups.details(1)

edit(id, **kw)[source]¶

Edit an existing target group.

target-groups: edit

Parameters:	id (int) – The unique identifier for the target group. name (str, optional) – The name of the target group. members (list, optional) – The members of the target group. FQDNs, CIDRs, IPRanges, and individual IPs are supported. NOTE: modifying the member list is atomic and not additive. All previous members that are desired to be kept within the member list much also be included. acls (list, optional) – A list of ACLs defining how the asset list can be used. For further information on how the ACL dictionaries should be written, please refer to the API documentation. NOTE: modifying ACLs is atomic and not additive. Please provide the complete list of ACLs that this asset group will need. type (str, optional) – The type of target group to create. Valid types are user and system.
Returns:	The modified target group resource record.
Return type:	`dict`

Examples

>>> tio.target_groups.edit(1, name='Updated TG Name')

list()[source]¶

Retrieve the list of target groups configured.

target-groups: list

Returns:	Listing of target group resource records.
Return type:	list

Examples

>>> for tg in tio.target_groups.list():
...     pprint(tg)

users¶

The following methods allow for interaction into the Tenable.io users API endpoints.

Methods available on tio.users:

class UsersAPI(api)[source]¶

create(username, password, permissions, name=None, email=None, account_type=None)[source]¶

Create a new user.

users: create

Parameters:	username (str) – The username for the new user. password (str) – The password for the new user. permissions (int) – The permissions role for the user. The permissions integer is derived based on the desired role of the user. For details describing what permissions values mean what roles, please refer to the User Roles table to see what permissions are accepted. name (str, optional) – The human-readable name of the user. email (str, optional) – The email address of the user. account_type (str, optional) – The account type for the user. The default is local.
Returns:	The resorce record fo the new user.
Return type:	`dict`

Examples

Create a standard user:

>>> user = tio.users.create('jsmith@company.com', 'password1', 32)

Create an admin user and add the email and name:

>>> user = tio.create.users('jdoe@company.com', 'password', 64,
...     name='Jane Doe', email='jdoe@company.com')

change_password(id, old_password, new_password)[source]¶

Change the password for a specific user.

users: password

Parameters:	id (int) – The unique identifier for the user. old_password (str) – The current password. new_password (str) – The new password.
Returns:	The password has been successfully changed.
Return type:	`None`

Examples

>>> tio.users.change_password(1, 'old_pass', 'new_pass')

delete(id)[source]¶

Removes a user from Tenable.io.

users: delete

Parameters:	id (int) – The unique identifier of the user.
Returns:	The user was successfully deleted.
Return type:	`None`

Examples

>>> tio.users.delete(1)

details(id)[source]¶

Retrieve the details of a user.

users: details

Parameters:	id (int) – THe unique identifier for the user.
Returns:	The resource record for the user.
Return type:	`dict`

Examples

>>> user = tio.users.details(1)

edit(id, permissions=None, name=None, email=None, enabled=None)[source]¶

Modify an existing user.

users: edit

Parameters:	id (int) – The unique identifier for the user. permissions (int, optional) – The permissions role for the user. The permissions integer is derived based on the desired role of the user. For details describing what permissions values mean what roles, please refer to the User Roles table to see what permissions are accepted. name (str, optional) – The human-readable name of the user. email (str, optional) – The email address of the user. enabled (bool, optional) – Is the user account enabled?
Returns:	The modified user resource record.
Return type:	`dict`

Examples

>>> user = tio.users.edit(1, name='New Full Name')

enabled(id, enabled)[source]¶

Enable the user account.

users: enabled

Parameters:	id (int) – The unique identifier for the user. enabled (bool) – Is the user enabled?
Returns:	The modified user resource record.
Return type:	`dict`

Examples

Enable a user:

>>> tio.users.enabled(1, True)

Disable a user:

>>> tio.users.enabled(1, False)

gen_api_keys(id)[source]¶

Generate the API keys for a specific user.

users: keys

Parameters:	id (int) – The unique identifier for the user.
Returns:	A dictionary containing the new API Key-pair.
Return type:	`dict`

Examples

>>> keys = tio.users.gen_api_keys(1)

two_factor(id, email, sms, phone=None)[source]¶

Configure two-factor authorization for a specific user.

users: two-factor

Parameters:	id (int) – The unique identifier for the user. email (bool) – Whether two-factor should be additionally sent as an email. sms (bool) – Whether two-factor should be enabled. This will send SMS codes. phone (str, optional) – The phone number to use for two-factor authentication. Required when sms is set to True.
Returns:	Setting changes were successfully updated.
Return type:	`None`

Examples

Enable email authorization for a user:

>>> tio.users.two_factor(1, True, False)

Enable SMS authorization for a user:

>>> tio.users.two_factor(1, False, True, '9998887766')

enable_two_factor(id, phone)[source]¶

Enable phone-based two-factor authorization for a specific user.

users: two-factor-enable

Parameters:	phone (str) – The phone number to use for two-factor auth.
Returns:	One-time activation code sent to the provided phone number.
Return type:	`None`

Examples

>>> tio.users.enable_two_factor(1, '9998887766')

verify_two_factor(id, code)[source]¶

Send the verification code for two-factor authorization.

users: two-factor-enable-verify

Parameters:	code (str) – The verification code that was sent to the device.
Returns:	The verification code was valid and two-factor is enabled.
Return type:	`None`

Examples

>>> tio.users.verify_two_factor(1, 'abc123')

impersonate(name)[source]¶

Impersonate as a specific user.

users: impersonate

Parameters:	name (str) – The user-name of the user to impersonate.
Returns:	Impersonation successful.
Return type:	`None`

Examples

>>> tio.users.impersonate('jdoe@company.com')

list()[source]¶

Retrieves a list of users.

users: list

Returns:	List of user resource records.
Return type:	`list`

Examples

>>> for user in tio.users.list():
...     pprint(user)

workbenches¶

The following methods allow for interaction into the Tenable.io workbenches API endpoints.

Note

Workbenches API endpoints have an upper bound on the amount of data that they will return, so for larger result sets, it may make more sense to use the exports API.

Methods available on tio.workbenches:

class WorkbenchesAPI(api)[source]¶

assets(*filters, **kw)[source]¶

The assets workbench allows for filtering and interactively querying the asset data stored within Tenable.io. There are a wide variety of filtering options available to find specific pieces of data.

workbenches: assets

Parameters:	age (int, optional) – The maximum age of the data to be returned. filters (list, optional) – A list of tuples detailing the filters that wish to be applied the response data. Each tuple is constructed as (‘filter’, ‘operator’, ‘value’) and would look like the following example: (‘host.hostname’, ‘match’, ‘asset.com’). For a complete list of the available filters and options, please refer to the API documentation linked above. filter_type* (str, optional) – Are the filters exclusive (this AND this AND this) or inclusive (this OR this OR this). Valid values are and and or. The default setting is and. all_fields (bool, optional) – Should all of the available fields be returned for each returned asset, or just the default fields represented in the UI. The default is set to True which will return the same level of detail as the workbenches: asset-info endpoint.
Returns:	List of asset resource records.
Return type:	`list`

Examples

Query for all of the asset information:

>>> for asset in tio.workbenches.assets():
...     pprint(asset)

Query for just the windows assets:

>>> for asset in tio.workbenches.assets(
...     ('operating_system', 'match', 'Windows')):
...     pprint(asset)

asset_activity(uuid)[source]¶

Query for the asset activity (when was the asset was seen, were there changes, etc.).

workbenches: asset-activity

Parameters:	uuid (str) – The asset unique identifier.
Returns:	The activity list of the asset specified.
Return type:	`list`

Examples

>>> asset_id = '00000000-0000-0000-0000-000000000000'
>>> for entry in tio.workbenches.asset_activity(asset_id):
...     pprint(entry)

asset_delete(asset_uuid)[source]¶

Deletes the asset.

workbenches: asset-delete

Parameters:	asset_uuid (str) – The unique identifier for the asset.
Returns:
Return type:	`None`

Examples

>>> asset_id = '00000000-0000-0000-0000-000000000000'
>>> tio.workbenches.asset_delete(asset_id)

asset_info(uuid, all_fields=True)[source]¶

Query for the information for a specific asset within the asset workbench.

workbenches: asset-info

Parameters:	id (str) – The unique identifier (UUID) of the asset. all_fields (bool, optional) – If all_fields is set to true (the default state), then an expanded dataset is returned as defined by the API documentation (linked above).
Returns:	The resource record for the asset.
Return type:	`dict`

Examples

>>> asset = tio.workbenches.asset_info('00000000-0000-0000-0000-000000000000')

asset_vulns(uuid, *filters, **kw)[source]¶

Return the vulnerabilities for a specific asset.

devportalworkbenches: asset-vulnerabilities workbenches-asset-vulnerabilities>

Parameters:	uuid (str) – The unique identifier of the asset to query. age (int, optional) – The maximum age of the data to be returned. filters (list, optional) – A list of tuples detailing the filters that wish to be applied the response data. Each tuple is constructed as (‘filter’, ‘operator’, ‘value’) and would look like the following example: (‘host.hostname’, ‘match’, ‘asset.com’). For a complete list of the available filters and options, please refer to the API documentation linked above. filter_type* (str, optional) – Are the filters exclusive (this AND this AND this) or inclusive (this OR this OR this). Valid values are and and or. The default setting is and.
Returns:	List of vulnerability resource records.
Return type:	`list`

Examples

>>> asset_id = '00000000-0000-0000-0000-000000000000'
>>> for vuln in tio.workbenches.asset_vulns(asset_id):
...     pprint(vuln)

asset_vuln_info(uuid, plugin_id, *filters, **kw)[source]¶

Retrieves the vulnerability information for a specific plugin on a specific asset within Tenable.io.

workbenches: asset-vulnerability-info

Parameters:	uuid (str) – The unique identifier of the asset to query. plugin_id (int) – The unique identifier of the plugin. age (int, optional) – The maximum age of the data to be returned. filters (list, optional) – A list of tuples detailing the filters that wish to be applied the response data. Each tuple is constructed as (‘filter’, ‘operator’, ‘value’) and would look like the following example: (‘host.hostname’, ‘match’, ‘asset.com’). For a complete list of the available filters and options, please refer to the API documentation linked above. filter_type* (str, optional) – Are the filters exclusive (this AND this AND this) or inclusive (this OR this OR this). Valid values are and and or. The default setting is and.
Returns:	List of vulnerability resource records.
Return type:	`list`

Examples

>>> asset_id = '00000000-0000-0000-0000-000000000000'
>>> vuln = tio.workbenches.asset_vuln_info(asset_id, 19506)
>>> pprint(vuln)

asset_vuln_output(uuid, plugin_id, *filters, **kw)[source]¶

Retrieves the vulnerability output for a specific vulnerability on a specific asset within Tenable.io.

workbenches: asset-vulnerability-output

Parameters:	uuid (str) – The unique identifier of the asset to query. plugin_id (int) – The unique identifier of the plugin. age (int, optional) – The maximum age of the data to be returned. filters (list, optional) – A list of tuples detailing the filters that wish to be applied the response data. Each tuple is constructed as (‘filter’, ‘operator’, ‘value’) and would look like the following example: (‘host.hostname’, ‘match’, ‘asset.com’). For a complete list of the available filters and options, please refer to the API documentation linked above. filter_type* (str, optional) – Are the filters exclusive (this AND this AND this) or inclusive (this OR this OR this). Valid values are and and or. The default setting is and.
Returns:	List of vulnerability resource records.
Return type:	`list`

Examples

>>> asset_id = '00000000-0000-0000-0000-000000000000'
>>> output = tio.workbenches.asset_vuln_output(asset_id, 19506)
>>> pprint(output)

export(*filters, **kw)[source]¶

Export data from the vulnerability workbench. These exports can be in a number of different formats, however the defaults are set to export a Nessusv2 report.

workbenches: export

Parameters:	filters (tuple, optional) – A list of tuples detailing the filters that wish to be applied the response data. Each tuple is constructed as (‘filter’, ‘operator’, ‘value’) and would look like the following example: (‘plugin.id’, ‘eq’, ‘19506’). For a complete list of the available filters and options, please refer to the API documentation linked above. asset_uuid* (uuid, optional) – Restrict the output to the asset identifier specified. plugin_id (int, optional) – Restrict the output to the plugin identifier specified. format (str, optional) – What format would you like the resulting data to be in. The default would be nessus output. Available options are nessus, csv, html, pdf. Default is ‘nessus’ chapters (list, optional) – A list of the chapters to write for the report. The chapters list is only required for PDF, CSV, and HTML exports. Available chapters are `vuln_hosts_summary`, `vuln_by_host`, `vuln_by_plugin`, and `vuln_by_asset`. List order will denote output order. In the case of CSV reports, only `vuln_by_asset` and `vuln_by_plugin` are available and only a singular chapter can be specified. filter_type (str, optional) – Are the filters exclusive (this AND this AND this) or inclusive (this OR this OR this). Valid values are and and or. The default setting is and. fobj (FileObject, optional) – The file-like object to be returned with the exported data. If no object is specified, a BytesIO object is returned with the data. While this is an optional parameter, it is highly recommended to use this parameter as exported files can be quite large, and BytesIO objects are stored in memory, not on disk.
Returns:	The file-like object of the requested export.
Return type:	`FileObject`

Examples

>>> with open('example.nessus', 'wb') as exportobj:
...     tio.workbenches.export(fobj=exportobj)

vulns(*filters, **kw)[source]¶

The vulnerability workbench allows for filtering and interactively querying the vulnerability data stored within Tenable.io. There are a wide variety of filtering options available to find specific pieces of data.

workbenches: vulnerability-info

Parameters:	age (int, optional) – The maximum age of the data to be returned. authenticated (bool, optional) – If set to true will only return authenticated vulnerabilities. exploitable (bool, optional) – If set to true will only return exploitable vulnerabilities. filters (list, optional) – A list of tuples detailing the filters that wish to be applied the response data. Each tuple is constructed as (‘filter’, ‘operator’, ‘value’) and would look like the following example: (‘host.hostname’, ‘match’, ‘asset.com’). For a complete list of the available filters and options, please refer to the API documentation linked above. filter_type* (str, optional) – Are the filters exclusive (this AND this AND this) or inclusive (this OR this OR this). Valid values are and and or. The default setting is and. resolvable (bool, optional) – If set to true will only return vulnerabilities with a remediation path. severity (str, optional) – Only return results of a specific severity (critical, high, medium, or low).
Returns:	Vulnerability info resource
Return type:	`dict`

vuln_assets(*filters, **kw)[source]¶

Retrieve assets based on the vulnerability data.

workbenches: assets-vulnerabilities

Parameters:	age (int, optional) – The maximum age of the data to be returned. filters (list, optional) – A list of tuples detailing the filters that wish to be applied the response data. Each tuple is constructed as (‘filter’, ‘operator’, ‘value’) and would look like the following example: (‘host.hostname’, ‘match’, ‘asset.com’). For a complete list of the available filters and options, please refer to the API documentation linked above. filter_type* (str, optional) – Are the filters exclusive (this AND this AND this) or inclusive (this OR this OR this). Valid values are and and or. The default setting is and.
Returns:	List of asset resource records.
Return type:	`list`

Examples

>>> for asset in tio.workbenches.vuln_assets():
...     pprint(asset)

vuln_info(plugin_id, *filters, **kw)[source]¶

Retrieve the vulnerability information for a specific vulnerability.

workbenches: vulnerability-info

Parameters:	age (int, optional) – The maximum age of the data to be returned. filters (list, optional) – A list of tuples detailing the filters that wish to be applied the response data. Each tuple is constructed as (‘filter’, ‘operator’, ‘value’) and would look like the following example: (‘host.hostname’, ‘match’, ‘asset.com’). For a complete list of the available filters and options, please refer to the API documentation linked above. filter_type* (str, optional) – Are the filters exclusive (this AND this AND this) or inclusive (this OR this OR this). Valid values are and and or. The default setting is and.
Returns:	Vulnerability info resource
Return type:	`dict`

Examples

>>> info = tio.workbenches.vuln_info(19506)
>>> pprint(info)

vuln_outputs(plugin_id, *filters, **kw)[source]¶

Retrieve the vulnerability output for a given vulnerability.

workbenches: vulnerability-output

Parameters:	age (int, optional) – The maximum age of the data to be returned. filters (list, optional) – A list of tuples detailing the filters that wish to be applied the response data. Each tuple is constructed as (‘filter’, ‘operator’, ‘value’) and would look like the following example: (‘host.hostname’, ‘match’, ‘asset.com’). For a complete list of the available filters and options, please refer to the API documentation linked above. filter_type* (str, optional) – Are the filters exclusive (this AND this AND this) or inclusive (this OR this OR this). Valid values are and and or. The default setting is and.
Returns:	Vulnerability outputs resource
Return type:	`dict`

Examples

>>> outputs = tio.workbenches.vuln_outputs(19506)
>>> pprint(outputs)

Raw HTTP Calls¶

Even though the TenableIO object pythonizes the Tenable.io API for you, there may still bee the occasional need to make raw HTTP calls to the IO API. The methods listed below aren’t run through any naturalization by the library aside from the response code checking. These methods effectively route directly into the requests session. The responses will be Response objects from the requests library. In all cases, the path is appended to the base url paramater that the TenableIO object was instantiated with.

Example:

resp = tio.get('scans')

class TenableIO[source]

get(path, **kwargs)¶

Initiates an HTTP GET request using the specified path. Refer to requests.request for more detailed information on what keyword arguments can be passed:

Parameters:	path (str) – The path to be appended onto the base URL for the request. *kwargs (dict*) – Keyword arguments to be passed to the Requests Sessions request method.
Returns:	`requests.Response`

post(path, **kwargs)¶

Initiates an HTTP POST request using the specified path. Refer to the requests.request for more detailed information on what keyword arguments can be passed:

Parameters:	path (str) – The path to be appented onto the base URL for the request. *kwargs (dict*) – Keyword arguments to be passed to the Requests Sessions request method.
Returns:	`requests.Response`

put(path, **kwargs)¶

Initiates an HTTP PUT request using the specified path. Refer to the requests.request for more detailed information on what keyword arguments can be passed:

Parameters:	path (str) – The path to be appended onto the base URL for the request. *kwargs (dict*) – Keyword arguments to be passed to the Requests Sessions request method.
Returns:	`requests.Response`

delete(path, **kwargs)¶

Initiates an HTTP DELETE request using the specified path. Refer to the requests.request for more detailed information on what keyword arguments can be passed:

Parameters:	path (str) – The path to be appended onto the base URL for the request. *kwargs (dict*) – Keyword arguments to be passed to the Requests Sessions request method.
Returns:	`requests.Response`