Access Groups¶

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

Methods available on tio.access_groups:

class AccessGroupsAPI(api: restfly.session.APISession)[source]¶

This class contains all methods related to access-groups

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

Creates a new access group

access-groups: create

Parameters

name (str) – The name of the access group to create.
rules (list) –
a list of rule tuples. Tuples are defined in the standardized method of name, operator, value. For example:
```
('operating_system', 'eq', ['Windows NT'])
```
Rules will be validated 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(group_id)[source]¶

Deletes the specified access group.

access-groups: delete

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

details(group_id)[source]¶

Retrieves the details of the specified access group.

access-groups: details

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

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

Edits an access group

access-groups: update

Parameters

group_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 validated 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 Vulnerability Management.

access-groups: list

Parameters

*filters (tuple, optional) –
Filters are tuples in the form of (‘NAME’, ‘OPERATOR’, ‘VALUE’). Multiple filters can be used and will filter down the data being returned from the API.

Examples
- ('distro', 'match', 'win')
- ('name', 'nmatch', 'home')
As the filters may change and sortable fields may change over time, it’s highly recommended that you look at the output of the tio.filters.access_groups_filters() endpoint to get more details.
filter_type (str, optional) – The filter_type operator determines how the filters are combined together. and will inform the API that all the filter conditions must be met for an access group to be returned, whereas or would mean that if any of the conditions are met, the access group record will be returned.
limit (int, optional) – The number of records to retrieve. Default is 50
offset (int, optional) – The starting record to retrieve. Default is 0.
sort (tuple, optional) – A tuple of tuples identifying the 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)