Tenable Cloud Exposure

Tenable Cloud Exposure is a powerful cloud-native application protection platform (CNAPP) designed to simplify even the most complex cloud security challenges. By combining full asset discovery, deep risk analysis, runtime threat detection, and compliance, it rapidly exposes and closes priority security gaps caused by misconfigurations, risky entitlements, and vulnerabilities. With its unique identity-first approach, Tenable Cloud Exposure dramatically reduces the cloud attack surface and enforces least privilege at scale, helping organizations minimize risk and strengthen their overall security posture.

Validation Criteria

Your integration with Tenable Cloud Exposure 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 Email ([email protected]) to validate your third-party integration with Tenable's product or platform.
Explain how your integration uses Tenable's API and the specific endpoints utilized. Tenable may request read access to your integration's codebase to validate scalability and recommend best practices.
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.

GraphQL

Tenable Cloud Exposure uses a GraphQL API, providing flexibility and precise control over the data you retrieve. The API is available via a single endpoint (/graphql) and follows the standard GraphQL schema defined in the official GraphQL documentation. For more information, see the Tenable Cloud Exposure API documentation.

Best Practices

To build robust and reliable integrations with the Tenable Cloud Exposure GraphQL API, follow these best practices:

Set a Sensible Polling Interval

Limit automated polling to once per day.
For user-triggered, on-demand requests, enforce a cooldown period (e.g., 12 hours).

Use Documented and Supported Fields

Restrict integrations to documented fields; avoid relying on undocumented fields, which may change without notice.
Do not use deprecated fields. Always refer to the documentation for recommended replacements.
If Tenable updates field structures or naming conventions, advance notice will be provided. Third parties should update their integrations within 30 days of notification to maintain compatibility.

Query Only Relevant Fields

Retrieve only the fields you actually need.
Avoid unnecessary fields to maintain efficiency and reduce system overhead.

Prefer Broad Filters

Use broader filters instead of highly complex, granular queries.
For detailed views, export the full dataset and apply filtering on locally cached data.

Rate Limiting and Quotas

Tenable may enforce rate limits or usage quotas to safeguard system performance, maintain security, and ensure fair usage across all customers.

Use Pagination

GraphQL APIs support cursor-based pagination, which enables you to efficiently retrieve large datasets in smaller chunks. Instead of requesting everything at once, you request a limited number of results and fetch additional pages as needed. For more details, see Pagination in the official GraphQL documentation.

To paginate through results, use the first and after arguments:

first: {number} — The number of results to return in the request.
after: {cursor} — The cursor pointing to where the next page of results should begin.

Best practices for pagination:

Always check pageInfo.hasNextPage to determine if more data is available.
Use reasonable page sizes (50–100 results depending on query type) to avoid performance issues.
Store and reuse cursors when needed to navigate through result sets.

Example: Fetch First Five Items

The following query retrieves the first five virtual instances with critical or high vulnerabilities:

query {
  VulnerabilityInstances(first: 5, filter: {VulnerabilitySeverities: [Critical, High]}) {
    pageInfo {
      endCursor
      hasNextPage
    }
    nodes {
      Resolved
      Software {
        Name
      }
      Resource {
        Id
        Name
              }
      Vulnerability {
        Id
        Severity
        CvssScore
      }
    }
  }
}

Example: Paginate Through Findings

Step 1: Initial Query

Start by setting after: null to retrieve the first set of results:

query {
  Findings(first: 10, after: null) {
    nodes {
      Policy {
        Name
      }
      Status
      CreationTime
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

Sample Response

{
  "data": {
    "Findings": {
      "nodes": [
        {
          "Policy": {
            "Name": "Inactive IAM role"
          },
          "Status": "Open",
          "CreationTime": "2024-08-13T00:49:10.532Z"
        },
        ...
      ],
      "pageInfo": {
        "hasNextPage": true,
        "endCursor": "cursor10"
      }
    }
  }
}

Since pageInfo.hasNextPage is true, use pageInfo.endCursor (cursor10) to fetch the next page.

Step 2: Fetch the Next Page

Use after: "cursor10" to fetch the next set of results:

query {
  Findings(first: 10, after: "cursor10"){
    nodes {
      Policy {
        Name
      }
      Status
      CreationTime
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

Sample Response

{
  "data": {
    "Findings": {
      "nodes": [
        {
          "Policy": {
            "Name": "Virtual Machine has vulnerabilities that should be addressed"
          },
          "Status": "Open",
          "CreationTime": "2024-09-14T00:43:10.578Z"
        },
        ...
      ],
      "pageInfo": {
        "hasNextPage": false,
        "endCursor": "cursor20"
      }
    }
  }
}

When pageInfo.hasNextPage is false, all results have been retrieved. Otherwise, continue paginating using the most recent endCursor.

Supported Use Cases

Tenable Cloud Exposure supports several common integration patterns that partners can use to retrieve cloud security data through the GraphQL API. These use cases describe high-level workflows and provide example queries that illustrate the recommended approach. Each example request selects every field the use case supports, so that you can see what is available; select only the fields your integration needs. For more information, see Query Only Relevant Fields.

Access to these use cases is granted as part of Tenable's partner validation process. If your integration has not yet completed validation, these queries may return no results.
For validation requirements, see the Validation Criteria.

Each query type has an associated pagination limit. Queries that exceed these limits will not be blocked, but the resulting performance issues or timeouts are not supported. For guidance on improving performance, see Best Practices.

Query Inventory

Retrieve all cloud inventory entities across accounts and providers. This use case is suitable for partners building asset inventories, CMDB enrichment, or resource-level reporting. Optionally, you can include custom properties, labels, tags, and cloud-specific identifiers such as ARNs for AWS resources.

Pagination limit: 100

Supported filters:

filter: {
  AccountIds: ["***"]
  Providers: [***]
}

👍
Tip
You can optionally filter inventory by account, provider, region, or resource type to reduce query scope and improve performance.

Example request:

query {
  Entities(first: 100, after: null, filter: {
    AccountIds: ["***"]
    Providers: [***]
  }) {
    nodes {
      AccountId
      AccountName
      CustomProperties {
        Name
        Values { Value }
      }
      CreatorOriginator { Id }
      CreatorIdentity { Id }
      CreationTime
      Id
      Labels
      Name
      Provider
      Region
      SyncTime
      Tags { Key Value }
      Type: __typename
      ... on AwsResource { Arn }
      ... on ContainerImage {
        OperatingSystem
        OperatingSystemType
      }
      ... on VirtualMachine {
        OperatingSystem
        OperatingSystemType
      }
    }
    pageInfo { hasNextPage endCursor }
  }
}

Query Findings

Retrieve all findings across accounts and cloud providers. You may optionally include related resource information. This use case is suitable for partners building security dashboards, compliance views, alerting systems, and correlation pipelines.

Pagination limit: 100

Supported filters:

filter: {
  AccountIds: ["***"]
  Categories: [***]
  Families: [***]
  Providers: [***]
  Severities: [***]
  Statuses: [***]
  SubStatuses: [***]
  Types: [***]
}

Example request:

query {
  Findings {
    nodes {
      AccountId
      AccountName
      AccountPath
      Context
      CreationTime
      Description
      Id
      Link
      OpenTime
      Policy {
        Category
        Description
        Id
        Name
        ScopeId
      }
      Provider
      Remediation {
        Console {
          Steps
        }
      }
      Resources {
        Id
      }
      Severity
      Status
      SubStatus
      StatusUpdateTime
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

Query Vulnerabilities

Retrieve vulnerability details, including severity scores, exploitability indicators, and the sources that reported each vulnerability. This use case is suitable for partners enriching their own vulnerability records, or correlating Tenable severity and VPR data with other sources.

Pagination limit: 10,000

Supported filters:

filter: {
  VprSeverities: [***]
}

📘
Note
High-volume integrations should use pagination and query only required fields. Additionally, use the VprSeverities filter to narrow results to the severities you need.

Example request:

query {
  Findings {
    nodes {
      AttackVector
      CvssScore
      CvssSeverity
      Description
      EpssScore
      Exploitable
      ExploitMaturity
      Id
      Links
      Names
      Severity
      Sources {
        CvssScore
        CvssVector
        CvssVersion
        Name
        Severity
      }
      VprScore
      VprSeverity
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

Query Vulnerabilities by Virtual Machine

List all scanned virtual machines and retrieve both open and resolved vulnerabilities associated with each instance. This use case supports partners performing vulnerability tracking, CMDB enrichment, and risk analytics.

Pagination limit: 10,000

Supported filters:

filter: {
  Resolved: ***
  VprSeverities: [***]
}

📘
Note
High-volume integrations should use pagination and query only required fields. Additionally, use filters to narrow results to relevant severities or resolved/unresolved instances.

Example request:

query {
  VulnerabilityInstances {
    nodes {
      FirstScanTime
      ResolutionTime
      Resolved
      Software {
        Name
        Type
        Version
      }
      Resource {
        Id
        Name
      }
      SoftwarePaths
      SoftwareResolutionVersions
      Vulnerability {
        Id
        Severity
        CvssScore
        Description
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

Query Vulnerability Findings Only

Retrieve findings specific to vulnerabilities, excluding configuration, compliance, and entitlement findings. This use case is intended for partners focused solely on vulnerability enrichment or correlation.

Pagination limit: 100

Supported filters:

filter: {
  Types: [***]
}

👍
Tip
Use the Types filter to focus only on vulnerability-related findings.

Example request:

query {
  Findings(
    filter: {
      Types: [
        VirtualMachineOperatingSystemUnpatchedFinding,
        VirtualMachineVulnerabilityFinding
      ]
    }
  ) {
    nodes {
      Id
      Policy { Name }
      Status
      Remediation {
        Console {
          Steps
        }
      }
      Description
      Resources {
        Name
        ... on VirtualMachine {
          Vulnerabilities {
            Id
          }
        }
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}