DocumentationAPI ExplorerRecipesConnectChangelogRSSSubscribe
Documentation

Tenable Cloud Security

Suggest Edits

Tenable Cloud Security 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 Security 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 Security 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 Security 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 Security API documentation.

Best Practices

To build robust and reliable integrations with the Tenable Cloud Security 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 Security 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.

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 }
    }
    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: ["***"]
  Providers: [***]
  Statuses: [***]
  Types: [***]
}

Example Request

query {
  Findings {
    nodes {
      AccountId
      AccountName
      AccountPath
      CreationTime
      Description
      OpenTime
      Policy {
        Category
        Name
      }
      Provider
      Remediation {
        Console {
          Steps
        }
      }
      Resources {
        Id
      }
      Severity
      Status
      SubStatus
      StatusUpdateTime
    }
    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

📘

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
      }
      Resource {
        Id
        Name
      }
      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

👍

Tip

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

Example Request

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

Updated 10 days ago