Agents

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

Methods available on tio.agents:

class AgentsAPI(api: APISession)[source]
details(agent_id, scanner_id=1)[source]

Retrieves the details of an agent.

agents: get

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

agents: 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 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:

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)
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)

Unlink one or multiple agents from the Tenable Vulnerability Management instance.

agents: delete

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, a dict response will be returned with a task record.

Return type:

dict or None

Examples

Unlink a singular agent:

>>> tio.agents.unlink(1)

Unlink many agents:

>>> tio.agents.unlink(1, 2, 3)