Apply Dynamic Tags

You can create dynamic tags, that is, asset tags that Tenable.io automatically applies to assets based on defined rules. The rules match common asset attributes, for example, IP address or hostname, or other tags that may be already applied to assets.

Tenable.io applies a dynamic tag when you add a new asset (via scan, connector import, or leveraging the Tenable.io API). When you update an existing asset, Tenable.io re-evaluates the asset and removes the tag if the asset's attributes no longer match the tag rules. Tenable.io also re-evaluates tagged assets when you create or update tag rules.

To apply a dynamic tag:

1. Familiarize yourself with asset object attributes and their values. Examine the asset object returned by the GET /assets/{asset_id} endpoint.
2. Get the list of filters that you can use to define dynamic tag rules with the GET /tags/assets/filters endpoint. The filter definitions include the field or tag names to match, the operators that you can use with the filter, and the rules for matching the values (control field), for example, a regular expression or a list of valid Values.

For definitions of the asset attribute fields you might use as filters, see Asset Attribute Definitions.

The following is an example of a filter for the ipV4 address property:

{
  "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"
  ]
}

3. Create a new tag or edit an existing tag, and specify the asset selection rules as the filters property. Note that you can define multiple rules for a single tag. To match all rules in the set, use the and object. To match any of the rules, use the or object.

📘

Note

Tenable.io supports a maximum of 1,000 rules per tag. This limit means that you can specify a maximum of 1,000 and or or conditions for a single tag value. Additionally, Tenable.io supports a maximum of 1,024 values in a comma-delimited string for the value of an individual rule.

Below, you can find examples for rules based on the following attributes:

• IP Address/CIDR
• Operating System
• Other Asset Tags
• Installed Software
• Asset Assessed

Example: Rule Based on IP Address/CIDR

"filters": {
  "asset": {
    "and": [
      {
        "field": "ipv4",
        "operator": "eq",
        "value": "192.0.2.0/24"
      }
    ]
  }
}

Example: Rule Based on Operating System

"filters": {
  "asset": {
    "and": [
      {
        "field": "operating_system",
        "operator": "match",
        "value": "FreeBSD"
      }
    ]
  }
}

Example: Rule Based on Other Asset Tags

"filters": {
  "asset": {
    "or": [
      {
        "field": "tag.US Timezone",
        "operator": "set-has",
        "value": "US Central"
      }, 
      {
        "field": "tag.US Timezone",
        "operator": "set-has",
        "value": "US Pacific"
      }
    ]
  }
}

Example: Rule Based on Installed Software

The example below represents the conditional rule set to apply a tag to assets where any of three specified versions of Apple Quicktime is installed.

"filters": {
  "asset": {
    "or": [
      {
        "field": "installed_software",
        "operator": "eq",
        "value": "cpe:/a:apple:quicktime:7.7.1"
      },
      {
        "field": "installed_software",
        "operator": "eq",
        "value": "cpe:/a:apple:quicktime:7.7.6"
      },
      {
        "field": "installed_software",
        "operator": "eq",
        "value": "cpe:/a:apple:quicktime:7.7.9"
      }
    ]
  }
}

Example: Rule Based on Unassessed Assets

The example below represents the conditional rule set to apply a tag to assets that Tenable.io has discovered but not yet assessed for vulnerabilities. For more information, see Manage Unassessed Assets.

"filters": {
  "asset": {
    "or": [
      {
        "field": "asset_assessed",
        "operator": "eq",
        "value": false
      }
    ]
  }
}