Bulk Agent Management Improvements

The Tenable.io API now supports criteria filtering for agent bulk operations. Users can now specify whether or not to perform bulk operation on all agents or a subset of agents determined by filtering criteria. Previously, users could only specify an array of agent IDs or UUIDs when performing agent bulk operations.

Updated Endpoints

This update applies to the following endpoints:

Endpoint	Name	Description
POST /scanners/null/agent-groups/{group_id}/agents/_bulk/add	Add agents to group	Creates a bulk operation task to add agents to a group.
POST /scanners/null/agents/_bulk/addToNetwork	Add agents to a network	Creates a bulk operation task to add agents to a custom network.
POST /scanners/null/agent-groups/{group_id}/agents/_bulk/remove	Remove agents from group	Creates a bulk operation task to remove agents from a group.
POST /scanners/null/agents/_bulk/removeFromNetwork	Remove agents from a network	Creates a bulk operation task to remove agents from a custom network.
POST /scanners/null/agents/_bulk/unlink	Unlink agents	Creates a bulk operation task to unlink agents. For more information on unlinked agent data, see Unlink an Agent.

New Parameters

You can specify filter criteria by using the criteria object. The criteria object can contain the following parameters:

Parameter	Type	Description
all_agents	boolean	Indicates whether or not to match against all agents.
wildcard	string	A string used to match against all string-like attributes of an agent.
filters	array	An array of string or numeric operations to match against agents. For example, `name:match:laptop` or `core_version:lt:10.0.0`.
filter_type	string	Indicates how to combine the `filters` conditions. Possible values are `and` or `or`.
hardcoded_filters	string	Additional filters that will always be added as `and` conditions.

Examples

You can bulk add agents that contain the name laptop and where the core_version is less than 10.0.0 to a group by using the following criteria object in request body:

{
  "criteria": {
    "filters": [
      "name:match:laptop",
      "core_version:lt:10.0.0"
    ],
    "all_agents": false,
    "filter_type": "and"
  }
}

To use the above criteria object to bulk add agents to a group with the UUID 9bd87b50-7349-4a52-8a41-573b9a4b9bb6 you would use the following cURL request:

curl --request POST \
     --url https://cloud.tenable.com/scanners/null/agent-groups/9bd87b50-7349-4a52-8a41-573b9a4b9bb6/agents/_bulk/add \
     --header 'Accept: application/json' \
     --header 'Content-Type: application/json' \
     --data '
{
  "criteria": {
    "filters": [
      "name:match:laptop",
      "core_version:lt:10.0.0"
    ],
    "all_agents": false,
    "filter_type": "and"
  }
}
'