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, timeout=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
5
.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.
timeout (int, optional) – The connection timeout parameter informing the library how long to wait in seconds for a stalled response before terminating the connection. If unspecified, the default is 120 seconds.
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
- 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.
- Parameters
id (str) – The UUID of the access group to remove.
-
details
(id)[source]¶ Retrieves the details of the specified access group.
- Parameters
id (str) – The UUID of the access group.
-
edit
(id, **kw)[source]¶ Edits an access group
- 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.
- 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, whereasor
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.
- 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)
-
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.
- 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 isONETIME
.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.
- 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.
- 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.
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')
-
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.
- 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, adict
response will be returned with a task record.- Return type
dict
orNone
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.
- 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.
- 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.
- 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.
- 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, adict
response will be returned with a Job resource record.- Return type
dict
orNone
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, *filters, **kw)[source]¶ Retrieve the details about the specified agent group.
- Parameters
group_id (int) – The id of the agent group.
*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, whereasor
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
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
- Parameters
scanner_id (int, optional) – The id of the scanner
- Returns
Listing of agent group resource records
- Return type
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.
- 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.
- 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, whereasor
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.
- 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, adict
response will be returned with a task record.- Return type
dict
orNone
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.
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.
- 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.
- 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.
- 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.
- Returns
List of asset records.
- Return type
Examples
>>> for asset in tio.assets.list(): ... pprint(asset)
-
list_import_jobs
()[source]¶ Returns a list of asset import jobs.
- Returns
List of job records.
- Return type
Examples
>>> for job in tio.assets.list_import_jobs(): ... pprint(job)
-
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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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, whereasor
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.
- Returns
A list of the available credential types and definitions.
- Return type
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
- Parameters
etype (str) – The type of template to retrieve. Must be either
scan
orpolicy
.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.
- Parameters
etype (str) – The type of object to retrieve. Must be either
scan
orpolicy
.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.
- 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.
- Parameters
etype (str) – The type of template to retrieve. Must be either
scan
orpolicy
.uuid (str) – The UUID (unique identifier) for the template.
- Returns
Details on the requested template
- Return type
dict
-
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.
- 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 isONETIME
.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.
- 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.
- 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.
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')
-
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.
is_deleted (bool, optional) – Determines whether or not to return assets which have any value within the
deleted_at
attribute. If left unspecified, the default isFalse
is_licensed (bool, optional) – Determines whether or not to return unlicensed assets as part of the export. If left unspecified, the default is
True
, meaning only licensed assets will be returned.is_terminated (bool, optional) – Determines whether or not to return assets that have any value within the
terminated_at
attribute. If left unspecified, the default isFalse
.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[str], 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[tuple], 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.timeout (int, optional) – Number of seconds to wait before timing out the export. If left unspecified the iterator will wait indefinitely for the export to complete.
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.
when_done (bool, optional) – Wait to start working through the data until the export has finished processing. If left unspecified the default behavior is to download chunks as they are available.
- 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.
- 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.
include_unlicensed (bool, optional) – Informs the vuln export if it should include vulnerability data from assets that are unlicensed. This is generally required when interacting with stale assets (>90 days).
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[str], optional) – list of plugin families to restrict the export to. Please note that this parameter’s values are case sensitive.
plugin_ids (list[int], optional) – A list of plugin id’s to explicitly export.
severity (list[str], optional) – list of severities to include as part of the export. Supported values are info, low, medium, high, and critical.
state (list[str], optional) – list of object states to be returned. Supported values are open, reopened, and fixed.
tags (list[tuple], 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.timeout (int, optional) – Number of seconds to wait before timing out the export. If left unspecified the iterator will wait indefinitely for the export to complete.
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 export to only vulnerabilities that match the VPR criteria specified. As this supports a range of operations, it’s worth detailing a couple of examples:
VPR Scores greater than or equal to 7.0:
VPR Score less than 7, but not 5:
when_done (bool, optional) – Wait to start working through the data until the export has finished processing. If left unspecified the default behavior is to download chunks as they are available.
- 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.
- 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.
- 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.
- 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.
- 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.
- Parameters
id (int) – The unique identifier for the folder.
- Returns
None
Examples
>>> tio.folders.delete(1)
-
edit
(id, name)[source]¶ Edit a folder.
- 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')
-
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.
- 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.
- 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.
- 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.
- 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.
- 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.
- Returns
List of the group resource records
- Return type
Examples
>>> for group in tio.groups.list(): ... pprint(group)
-
list_users
(id)[source]¶ List the user memberships within a specific user group.
- 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
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
- 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.
- 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.
- 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.
- 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.
- 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, whereasor
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.
- Parameters
id (str) – The UUID of the network.
- Returns
List of scanner resources associated to this network.
- Return type
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
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.
- 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
-
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.
- Returns
List of plugin family resource records.
- Return type
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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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)
-
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.
- 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.
- 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.
- 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.
- 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.
- 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.
- Returns
List of scanner group resource records.
- Return type
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
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.
- 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.
- 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.
- 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.
- 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.
- Parameters
id (int) – The unique identifier for the scanner.
- Returns
List of aws target resource records.
- Return type
Examples
>>> for target in tio.scanners.get_aws_targets(1): ... pprint(target)
-
get_scanner_key
(id)[source]¶ Return the key associated with the scanner.
- 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.
- Parameters
id (int) – The unique identifier for the scanner.
- Returns
List of scan resource records associated to the scanner.
- Return type
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.
- Returns
List of scanner resource records.
- Return type
Examples
>>> for scanner in tio.scanners.list(): ... pprint(scanner)
-
toggle_link_state
(id, linked)[source]¶ Toggles the scanner’s activated 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.
- 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.
- 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. Further, any keyword arguments passed that are not explicitly documented will be automatically appended to the settings document. There is no need to pass settings directly.
- 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.
- 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.
- 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. Further, any keyword arguments passed that are not explicitly documented will be automatically appended to the settings document. There is no need to pass settings directly.
- 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.
- Parameters
scan_id (int or uuid) – 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.
- Parameters
scan_id (int or uuid) – The unique identifier for the scan.
history_id (int or uuid) – 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.
Note
If you’re looking for the results of the most recent scan, and what matches to the
GET /scans/{id}
call, then take a look at the results method.- Parameters
scan_id (int or uuid) – 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.
- Parameters
scan_id (int or uuid) – 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.
history_uuid (uuid, optional) – The UUID 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.
- Parameters
id (int or uuid) – 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, history_uuid=None)[source]¶ Retrieve the host details from a specific scan.
- Parameters
scan_id (int) – The unique identifier for the scan.
host_id (int) – The unique identifier for the host within the scan.
history_id (int, optional) – The unique identifier for the instance of the scan.
history_uuid (str, optional) – The unique identifier for the scan instance.
- 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.
- 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', 'rb') as reportobj: ... tio.scans.import(reportobj)
Import a NessusDB report.
>>> with open('example.db', 'rb') 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.
- Parameters
scan_id (int or uuid) – 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.
- Parameters
scan_id (int or uuid) – 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.
- 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
Examples
>>> for scan in tio.scans.list(): ... pprint(scan)
-
pause
(scan_id, block=False)[source]¶ Pauses a running scan.
- Parameters
scan_id (int or uuid) – 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, history_uuid=None)[source]¶ Retrieve the plugin output for a specific instance of a vulnerability on a host.
- Parameters
scan_id (int or uuid) – 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, history_uuid=None)[source]¶ Return the scan results from either the latest scan or a specific scan instance in the history.
- Parameters
scan_id (int or uuid) – The unique identifier for the scan.
history_id (int, optional) – The unique identifier for the instance of the scan.
history_uuid (uuid, optional) – The UUID 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.
- Parameters
scan_id (int or uuid) – 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.
- 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.
- Parameters
scan_id (int or uuid) – 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.
- Parameters
scan_id (int or uuid) – 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.
- 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)
-
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.
- Returns
The server properties.
- Return type
dict
Examples
>>> props = tio.server.properties() >>> pprint(props)
-
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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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')
-
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
- 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
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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 isAND
.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.
- Parameters
*filters (tuple, optional) – A defined filter tuple consisting of the name, operator, and value. Example:
('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 isAND
.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( ... ('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.
- 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.
- 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.
- 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.
- 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')
-
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.
- 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.users.create('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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- Parameters
name (str) – The user-name of the user to impersonate.
- Returns
Impersonation successful.
- Return type
None
Examples
>>> tio.users.impersonate('jdoe@company.com')
-
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.
- 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.).
- 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.
- 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.
- 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.
- 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
, andvuln_by_asset
. List order will denote output order. In the case of CSV reports, onlyvuln_by_asset
andvuln_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
-