Filtering

Tenable Attack Surface Management (ASM) supports flexible, granular filtering to help you retrieve only the assets relevant to your use case. Filters are supplied as a JSON array in the request body. Each object in the array represents a single filter condition, and multiple conditions can be combined to build complex queries.

If no filters are provided, the API returns all assets.

Each filter object contains the following properties:

• column — The asset property to filter on.
• type — The comparison operator to apply (see Supported Filter Types).
• value — The value to compare against. Some filter types allow this field to be omitted.

Example: Filter assets whose metadata changed after September 1, 2024.

[
  {
    "column": "bd.last_metadata_change",
    "type": "after",
    "value": "2024-09-01"
  }
]

Supported Columns

Asset filters operate on any property included in the asset definition. All asset properties can be used as filter columns.

For a complete list of available properties and their data types, refer to the assets array in the example 200 response of the List assets in inventory endpoint.

Supported Filter Types

Different filter types are available depending on the data type of the column being filtered. Use the property definitions in the assets array of the List assets in inventory endpoint to determine which data type a column belongs to.

The following sections describe supported filter types for each data type, along with special-case behaviors and examples.

String Filters

String filters allow you to match exact values, partial values, or patterns.

Supported Types

• is
• is not
• is one of
• is not one of
• starts with
• ends with
• contains
• does not contain
• is unknown
• has any value

📘

Note

The filter types is one of and is not one of require a newline-separated list of values in the value field. For example, "value": "one\ntwo\nthree\n".

Special Columns

• own_body.html supports only: contains, does not contain, is unknown, and has any value.

Example:

{
  "column": "own_body.html",
  "type": "contains",
  "value": "<script>"
}

Boolean Filters

Boolean filters match true/false values or unknown states.

Supported Types

• yes
• no
• is unknown
• has any value

📘

Note

Boolean filters do not require a value field.

Example:

{
  "column": "ipgeo.cloudhosted",
  "type": "yes"
}

Number Filters

Number filters match exact values, ranges, or sets of numbers.

Supported Types

• is
• is not
• is one of
• is not one of
• greater than
• less than
• is unknown
• has any value

Special Columns

• bd.addedtoportfolio — Timestamp; supports date filter types.
• bd.tags — List of tag IDs; supports only is, is not, and is unknown.

Example:

{
  "column": "ports.ports",
  "type": "is",
  "value": "22"
}

Date Filters

Date filters allow matching by absolute date or relative time (days ago).

Supported Types

• more than
• exactly
• less than
• after
• on
• before
• is unknown
• has any value

📘

Note

The filter types more than, exactly, and less than accept a number representing days ago.

Special Columns

• ssl.valid_to supports: is expired, is not expired, expires in, expired less than, expired more than, expires on, expires after, expires before, is unknown, and has any value.
  • value may be omitted for is expired and is not expired.
• ports.lastseen — Filtering is not supported.

Example:

{
  "column": "ssl.valid_from",
  "type": "after",
  "value": "2024-09-01"
}

Combining Filters

Filters can be combined by including multiple filter objects in the same request. By default, the API applies AND logic, returning only assets that satisfy every condition.

Example: Metadata changed after September 1, 2024 and hostname ends with .com.

[
  {
    "column": "bd.last_metadata_change",
    "type": "after",
    "value": "2024-09-01"
  },
  {
    "column": "bd.original_hostname",
    "type": "ends with",
    "value": ".com"
  }
]

Expression Filter

Use the expression filter to specify whether the API should treat the conditions as AND (all must match) or OR (any may match).

Format:

• column: expression
• type:
  • all filters — Require all conditions (default behavior).
  • any filters — Match if at least one condition is true.
• value: Optional

Example: Match assets meeting either condition.

[
  {
    "column": "expression",
    "type": "any filters"
  },
  {
    "column": "bd.last_metadata_change",
    "type": "after",
    "value": "2024-09-01"
  },
  {
    "column": "bd.original_hostname",
    "type": "ends with",
    "value": ".com"
  }
]