DocumentationAPI ExplorerRecipesCommunityChangelogRSSSubscribe
Documentation

Attack Surface Management

Suggest Edits

Tenable Attack Surface Management (ASM) is a cloud-based discovery and inventory solution that helps organizations identify internet-facing assets—both known and unknown. By analyzing DNS records, IP addresses, and autonomous system numbers (ASNs), it uncovers exposed assets and enriches them with over 180 metadata fields to support effective asset inventory and risk prioritization.

Validation Criteria

Your integration with Tenable Attack Surface Management should meet the following criteria:

  • Ensure that all API calls from your integration use a standard User-Agent string as outlined in the User-Agent Header guide. This enables Tenable to identify your integration's API calls to assist with debugging and troubleshooting.
  • Contact Tenable via the Tech Alliances Application to validate your third-party integration with Tenable's product or platform.
  • Explain how your integration uses Tenable's API and the specific endpoints that are being utilized. Tenable may request access to your integration's codebase to validate scalability and provide best practice recommendations.
  • Ensure that your integration uses the proper naming conventions, trademarks, and logos in your integration's user interface. You can download a Media Kit on Tenable's media page.

Data Export Workflow

A high-level workflow for exporting asset inventory data from Tenable Attack Surface Management using the List assets in your inventory endpoint is illustrated in the following diagram.

Tenable ASM Data Export Workflow

The general workflow:

  1. Construct Inventory Request
    • Query Parameters—Choose query parameters to determine how the data retrieved should be shaped.
    • Body Parameters—Choose body parameters to define optional filers to narrow the result set.
  2. Page Through Data

Creating Inventory Export Requests

An inventory request contains two sets of parameters, query parameters and body parameters. The query parameters detail how to shape the data being requested, and the body parameters detail a list of filters to apply to optionally narrow the data returned in the result set.

Query Parameters

  • columns—A comma-separated list of columns to return in the data set. For the list of columns, Tenable recommends the properties listed below for most use cases. To explore all available properties, use the List asset properties endpoint.
  • sortby—The column name (property) to sort the results by.
  • sortorder—The order to sort the results by. Use true to sort the results in ascending order and false to sort the results in descending order.
  • limit—The number of records to retrieve per page. Tenable recommends a page size between 2000 and 10000.
  • after—(Paging option 1) The last asset ID from the previous page. Tenable Attack Surface Management ignores the offset query parameter if this parameter is used.
  • offset—(Paging option 2) The starting record to retrieve. This parameter can be used in combination with the limit parameter to page through the result set.

Recommended properties to use for columns:

  • id—The unique ID of the asset.
  • bd.original_hostname—The host name of the asset (CNAME records).
  • bd.hostname—The host name of the asset.
  • bd.severity_ranking—The severity ranking of the asset. Possible values are critical, high, medium, low, and none.
  • bd.record_type—The DNS record type of the asset.
  • bd.addedtoportfolio—The date and time when the asset was added to the current inventory.
  • ports.ports—A list of open ports on the asset.
  • screenshot.redirect_chain—The chain of HTTP or client-side redirects that navigated the system to screenshot.finalurl.
  • screenshot.finalurl—The final URL the asset redirects to.
  • ports.cves—A list of CVE IDs that are applicable to the asset.

Body Parameters

  • column—A column (property) to filter on.
  • type—The type of filter to apply (comparison operator). Refer to the Robust Filtering in the Tenable Attack Surface Management User Guide for the full list of filtering types.
  • value—The value to use for comparison in the filtering operation. Use ISO 8601 format for time-based values (e.g., 2025-05-01T01:00:00.000Z) to ensure compatibility with the filtering engine.

Example Request

The following is an example inventory asset request:

// POST https://asm.cloud.tenable.com/api/1.0/inventory?columns=id,bd.original_hostname,bd.hostname,bd.severity_ranking
[
  {
    "column": "severity_ranking",
    "type": "is",
    "value": "critical"
  }
]

Example pyTenable snippet

The following is an example pyTenable code snippet for an inventory asset request: For more information about inventory asset requests with pyTenable, see Inventory in the pyTenable documentation.

from tenable.asm import TenableASM

asm = TenableASM()

for item in asm.inventory.list(("severity_ranking", "is", "critical")):
  print(item)

Updated 3 days ago