Agent Groups

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

Methods available on tio.agent_groups:

class AgentGroupsAPI(api: APISession)[source]
add_agent(group_id, *agent_ids, **kw)[source]

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

agent-groups: add-agent

Parameters:

  • group_id (int) – The id of the group

  • *agent_ids (int) – The id or uuid of the agent. If passing multiple, they must all be either numeric id or uuid.

  • scanner_id (int, optional) – The id of the scanner

Returns:

If adding a singular agent, a None response will be returned. If adding multiple agents, a dict response will be returned with a task record.

Return type:

dict or None

Examples

Adding a singular agent:

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

Adding multiple agents:

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

Adding multiple agents by uuid:

>>> tio.agent_groups.add_agent(1, 'uuid-1', 'uuid-2', 'uuid-3')
configure(group_id, name, scanner_id=1)[source]

Renames an existing agent group.

agent-groups: configure

Parameters:

  • group_id (int) – The id of the group

  • name (str) – The new name for the agent group

  • scanner_id (int, optional) – The id of the scanner

Returns:

None

Examples

>>> tio.agent_groups.configure(1, 'New Name')
create(name, scanner_id=1)[source]

Creates a new agent group.

agent-groups: create

Parameters:

  • name (str) – The name of the agent group

  • scanner_id (int, optional) – The id of the scanner to add the agent group to

Returns:

The dictionary object representing the newly minted agent group

Return type:

dict

Examples

>>> group = tio.agent_groups.create('New Agent Group')
delete(group_id, scanner_id=1)[source]

Delete an agent group.

agent-groups: delete

Parameters:

  • group_id (int) – The id of the agent group to delete

  • scanner_id (int, optional) – The id of the scanner

Returns:

None

Examples

>>> tio.agent_groups.delete(1)
delete_agent(group_id, *agent_ids, **kw)[source]

Delete one or many agents from an agent group.

agent-groups: delete-agent

Parameters:

  • group_id (int) – The id of the agent group to remove the agent from

  • *agent_ids (int) – The id of the agent to be removed

  • scanner_id (int, optional) – The id of the scanner

Returns:

If deleting a singular agent, a None response will be returned. If deleting multiple agents, a dict response will be returned with a Job resource record.

Return type:

dict or None

Examples

Delete a singular agent from an agent group:

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

Delete multiple agents from an agent group:

>>> tio.agent_groups.delete_agent(1, 1, 2, 3)
details(group_id, *filters, **kw)[source]

Retrieve the details about the specified agent group.

agent-groups: details

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 the filter conditions must be met for an agent to be returned, whereas or would mean that if any of the conditions are met, the agent record will be returned.

  • limit (int, optional) – The number of records to retrieve. Default is 50

  • offset (int, optional) – The starting record to retrieve. Default is 0.

  • scanner_id (int, optional) – The identifier the scanner that the agent communicates to.

  • sort (tuple, optional) – A tuple of tuples identifying the 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

agent-groups: list

Parameters:

scanner_id (int, optional) – The id of the scanner

Returns:

Listing of agent group resource records

Return type:

list

Examples

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

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

Retrieves the current status of a bulk task.

bulk-operations: bulk-agent-group-status

Parameters:

  • group_id (int) – The id of the group

  • task_uuid (str) – The id of the task

  • scanner_id (int, optional) – The id of the scanner

Returns:

Task resource

Return type:

dict

Examples

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