DocumentationAPI ExplorerRecipesCommunityChangelogRSSSubscribe
Documentation

Bulk Asset Operations

Suggest Edits

You can use the Tenable Vulnerability Management API perform bulk operations on assets:

  • Move assets specified by IPv4 addresses from one network to another.
  • Update the Asset Criticality Rating (ACR) for multiple assets.
  • Delete assets from Vulnerability Management based on asset attribute queries.

After you submit requests for asset bulk operations, they create asynchronous jobs in Vulnerability Management.

Move assets

To move assets from one network to another:

  1. Identify the assets you want to move and their IPv4 addresses.
  2. Find the UUID of the source and destination networks using the GET /networks endpoint. Note that the default network UUID is always 00000000-0000-0000-0000-000000000000.
  3. Move the assets using the POST /api/v2/assets/bulk-jobs/move-to-network endpoint. The asset addresses in the targets property can be represented as a comma-separated list, a range, or CIDR, or a combination of these formats. The following is an example of the request payload:
{
    "targets": "1.1.1.1, 2.2.2.2-2.2.2.200, 3.3.3.0/24",
    "destination": "3e5a2dae-9914-4323-9424-038614e5a6f1",
    "source": "00000000-0000-0000-0000-000000000000"
}

Update ACR for assets

You must have a Lumin license to update the Asset Criticality Rating (ACR) for your organization's assets. To add Lumin to your Vulnerability Management license, contact your Tenable representative.

In Lumin, Tenable assigns an ACR to each asset on your network to represent the asset's relative risk as an integer from 1 to 10. You can use a Vulnerability Management API endpoint to overwrite the Tenable-provided ACR with a value you find more appropriate to the asset or assets.

The acr_score attribute is only present in assets if Lumin is added to your Vulnerability Management instance. For more information, see Lumin Metrics in the Tenable Vulnerability Management User Guide.

To update the ACR for multiple assets:

  1. Identify the assets you want to update. You can identify assets based on any of the following asset attributes: UUID, FQDN, MAC address, NetBIOS name, or ipv4 address.
  2. Update the ACR for those assets using the POST /api/v2/assets/bulk-jobs/acr endpoint. For example:
[
    {
        "acr_score": 9,
        "reason": [
            "Business Critical"
        ],
        "asset": [
            {
                "fqdn": [
                    "example.com"
                ]
            }
        ]
    },
    {
        "acr_score": 8,
        "reason": [
            "Business Critical"
        ],
        "asset": [
            {
                "id": "7aa32f9d-7255-4a4b-a390-4f8ea3d38118"
            }
        ]
    }
]
  1. (Optional) Verify the update by viewing the affected assets.

Bulk delete assets

To bulk delete assets:

  1. Get the list of filters to select the assets for deletion using the GET /filters/workbenches/assets endpoint. The filter definitions include the asset attribute to match, the operators that you can use with the filter, and the rules for matching the values (control attribute), for example, a regular expression or a list of valid values. The following is an example of a filter for the ipv4 attribute:
{
  "control": {
    "readable_regex": "e.g. 192.0.2.1, 192.0.2.0/24, 192.0.2.100-192.0.2.199",
    "type": "entry",
    "regex": "^(\\s*((?=\\d+\\.\\d+\\.\\d+\\.\\d+(?:\\/|-|\\s*,|$))(?:(?:25[0-5]|2[0-4]\\d|1\\d\\d|[1-9]?\\d)\\.?){4})(?:(?:\\/(?:3[0-2]|[12]?\\d))|((?:-(?=\\d+\\.\\d+\\.\\d+\\.\\d+)(?:(?:25[0-5]|2[0-4]\\d|1\\d\\d|[1-9]?\\d)\\.?){4})|(?:\\s*,(?:\\s*)))?)+)+$"
  },
  "name": "ipv4",
  "readable_name": "IPv4 Address",
  "operators": [
    "eq"
  ]
}
  1. Delete the assets using the POST /api/v2/assets/bulk-jobs/delete endpoint. Use the query parameter of the request payload to specify the filters for selecting assets. To select assets that match all of multiple conditions, specify the conditions inside the and array. To select assets that match any of multiple conditions, specify the conditions inside the or array. You can also nest conditions, for example, specify a set of or sub-conditions for a condition inside the and array. The following are the examples of the request payload.

Example: Single Condition Query

{
    "query": {
        "field": "ipv4",
        "operator": "eq",
        "value": "1.1.1.1, 2.2.2.2-2.2.2.200, 3.3.3.0/24"
    }
}

Example: Multiple Condition Query

{
    "query": {
        "and": [
            {
                "field": "ipv4",
                "operator": "eq",
                "value": "1.1.1.1, 2.2.2.2-2.2.2.200, 3.3.3.0/24"
            },
            {
                "field": "network_id",
                "operator": "eq",
                "value": "00000000-0000-0000-0000-000000000000"
            }
        ]
    }
}

Example: Nested Condition Query

{
    "query": {
        "and": [
            {
                "field": "network_id",
                "operator": "eq",
                "value": "00000000-0000-0000-0000-000000000000"
            },
            {
                "or": [
                    {
                        "field": "fqdn",
                        "operator": "eq",
                        "value": "mycomputer.company.org"
                    },
                    {
                        "field": "host.target",
                        "operator": "eq",
                        "value": "MyComputer"
                    }
                ]
            }
        ]
    }
}

Updated 3 days ago