Tags

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

Methods available on tio.tags:

class TagsAPI(api: restfly.session.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')
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'])