Tags¶

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

Methods available on tio.tags:

class TagsAPI(api: APISession)[source]¶

This will contain all methods related to tags

assign(assets, tags)[source]¶

Assigns the tag category/value pairs defined to the assets defined.

tags: assign tags

Parameters:

assets (list) – A list of Asset UUIDs.
tags (list) – A list of tag category/value pair UUIDs.

Returns:

Job UUID of the assignment job.

Return type:

str

Examples

>>> tio.tags.assign(
...     assets=['00000000-0000-0000-0000-000000000000'],
...     tags=['00000000-0000-0000-0000-000000000000'])

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

Create a tag category/value pair

tags: create-tag-value

Parameters:

category (str) – The category name, or the category UUID. If the category does not exist, then it will be created along with the new value.
value (str) – The value for the tag.
category_description (str, optional) – If the category is to be created, a description can be optionally provided.
description (str, optional) – A description for the Category/Value pair.
filters (list, optional) –
Filters are list of tuples in the form of (‘FIELD’, ‘OPERATOR’, ‘VALUE’). Multiple filters can be used and will filter down the data for automatically applying the tag to asset.

Examples
- ('operating_system', 'match', ['Linux'])
- ('name', 'nmatch', 'home')
Note that multiple values can be passed in list of string format
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 whereas or would mean that if any of the conditions are met. Default is and
all_users_permissions (list, optional) – List of the minimum set of permissions all users have on the current tag. Possible values are ALL, CAN_EDIT, and CAN_SET_PERMISSIONS.
current_domain_permissions (list, optional) –
List of user and group-specific permissions for the current tag current_domain_permissions are list of tuples in the form of (‘ID’, ‘NAME’, ‘TYPE’, ‘PERMISSIONS’) the TYPE can be either USER or GROUP and the PERMISSIONS can be ALL, CAN_EDIT or CAN_SET_PERMISSIONS any one or all in list

Examples
- (uuid , 'user@company.com', 'USER', ['CAN_EDIT'])

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 in the existing Location Category and apply to assets dynamically:

>>> tio.tags.create('Location', 'San Francisco',
...     filters=[('operating_system', 'match', ['Linux'])])

Creating a new Tag value in the existing Location Category and set permissions for users:

>>> tio.tags.create('Location', 'Washington',
...     all_users_permissions=['CAN_EDIT'],
...     current_domain_permissions=[('c2f2d080-ac2b-4278-914b-29f148682ee1',
...         'user@company.com', 'USER', ['CAN_EDIT'])
...     ])

Creating a new Tag Value within a Category by UUID:

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

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

Creates a new category

tags: create-category

Parameters:

name (str) – The name of the category to create
description (str, optional) – Description for the category to create.

Returns:

Tag category resource record

Return type:

dict

Examples

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

delete(*tag_value_uuids)[source]¶

Deletes tag value(s).

tag: delete tag value

Parameters:: *tag_value_uuid (str) – The unique identifier for the tag value to be deleted.
Returns:: None

Examples

Deleting a single tag value:

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

Deleting multiple tag values:

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

delete_category(tag_category_uuid)[source]¶

Deletes a tag category.

tag: delete tag category

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

Examples

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

details(tag_value_uuid)[source]¶

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

tag: tag details

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

Examples

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

details_category(tag_category_uuid)[source]¶

Retrieves the details for a specific tag category.

tag: tag category details

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

Examples

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

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

Updates Tag category/value pair information.

tag: edit tag value

Parameters:

tag_value_uuid (str) – The unique identifier for the c/v pair to be edited.
value (str, optional) – The new name for the category value.
description (str, optional) – New description for the category value.
filters (list, optional) –
Filters are list of tuples in the form of (‘FIELD’, ‘OPERATOR’, ‘VALUE’). Multiple filters can be used and will filter down the data for automatically applying the tag to asset.
Examples::
- ('operating_system', 'match', ['Linux'])
- ('name', 'nmatch', 'home')
Note that multiple values can be passed in list of string format
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 whereas or would mean that if any of the conditions are met. Default is and
all_users_permissions (list, optional) – List of the minimum set of permissions all users have on the current tag. Possible values are ALL, CAN_EDIT, and CAN_SET_PERMISSIONS.
current_domain_permissions (list, optional) –
List of user and group-specific permissions for the current tag current_domain_permissions are list of tuples in the form of (‘ID’, ‘NAME’, ‘TYPE’, ‘PERMISSIONS’) the TYPE can be either USER or GROUP and the PERMISSIONS can be ALL, CAN_EDIT or CAN_SET_PERMISSIONS any one or all in list
Examples::
- (uuid, 'user@company.com', 'USER', ['CAN_EDIT'])

Returns:

Tag value resource record.

Return type:

dict

Examples

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

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

Updates Tag category information.

tag: edit tag category

Parameters:

tag_category_uuid (str) – The unique identifier for the category to be edited.
name (str, optional) – The new name for the category.
description (str, optional) – New description for the category.

Returns:

Tag category resource record.

Return type:

dict

Examples

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

get_tag_uuid(category, value)[source]¶

Fetches tag UUID using category/value pairs.

Parameters:

category (str) – The category name for the tag.
value (str) – The value for the tag.

Returns:

Tag UUID.

Return type:

str

Examples

>>> tio.tags.get_tag_uuid('test_category','test_value')

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

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

tags: list tags

Parameters:

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

Returns:

An iterator that handles the pagination of the results

Return type:

TagIterator

Examples

Return all of the Tag Values:

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

Return all of the Tags of the Location category:

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

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

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

tags: list categories

Parameters:

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

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)

unassign(assets, tags)[source]¶

Un-assigns the tag category/value pairs defined to the assets defined.

tags: assign tags

Parameters:

assets (list) – A list of Asset UUIDs.
tags (list) – A list of tag category/value pair UUIDs.

Returns:

Job UUID of the un-assignment job.

Return type:

str

Examples

>>> tio.tags.unassign(
...     assets=['00000000-0000-0000-0000-000000000000'],
...     tags=['00000000-0000-0000-0000-000000000000'])