Upgrading from Finite State Legacy REST API to Finite State GraphQL API

Finite State's Legacy REST API is being deprecated in favor of the new GraphQL API. This document will help you migrate from the v1 API to the GraphQL API.

For example implementations, or if you are using Python, please reference the Finite State Python SDK.

Get Organizations

In the Finite State Legacy REST API, a client could have multiple Organizations. In the GraphQL API, each customer has a single Organization, but can have multiple Business Units. Business Units are referred to as "Groups" in the GraphQL API.

To get the Business Units for the Organization, you can make the following GraphQL query:

Business Units can be found in the application under Accounts > Business Units.

NOTE: Business Units are referred to as Groups in the GraphQL API.

Use the id field of the returned objects to query for data from a specific Business Unit.

You can click GraphQL, Variables, and Response in these code example headers to see the different parts of the query and response.

query GetBusinessUnits {
  allGroups {
    id
    name
  }
}

Get Issues for a Firmware

This query is similar to the query in Get Firmwares for a Product but adds a filter to get the Findings for a specific AssetVersion.

This query includes mergedFindingRefId : null in the filter to only get the findings that are not merged. If you want to include merged findings, remove this line from the filter.

For specific implemenation examples using pagination, or if you are using Python, see the get_all_paginated_results method in the Python SDK.

query GetFindingsForAnAssetVersion (
  $filter: FindingFilter
) {
  allFindings(filter: $filter) {
    title
    vulnIdFromTool
    description
    severity
    riskScore
    affects {
      name
      version
    }
  }
}

Get Software Components for a Firmware

Similar to the examples above, a "Firmware" is actually represented by an AssetVersion.

To get the Software Components for an AssetVersion, query allSoftwareComponentInstances and filter on the assetVersionRefId.

This query includes mergedFindingRefId : null in the filter to only get the Software Components that are not merged. If you want to include merged Software Components, remove this line from the filter.

query GetSoftwareComponentsForAnAssetVersion (
  $filter: SoftwareComponentInstanceFilter
) {
  allSoftwareComponentInstances(filter: $filter) {
    name
    version
  }
}

Get Number of Findings and Their Severity for a Firmware

Get the number (count) of Findings of each severity for an AssetVersion.

This query includes mergedFindingRefId : null in the filter to only get the findings that are not merged. If you want to include merged findings, remove this line from the filter.

NOTE: There is currently a limitation* in the GraphQL API on multiple aliased fields with the same name, so this will currently require four queries to get Critical, High, Medium, and Low. Valid values for the "severity" field are "CRITICAL", "HIGH", "MEDIUM", and "LOW".

*Finite State will be updating the API to support multiple aliased fields with the same name in the future.

query GetFindingSeverityForAnAssetVersion (
  $filter: FindingFilter
) {
	_allFindingsMeta(
    filter: $filter
  ) {
    count
  }
}

Get Findings Created After a Specific Date

To get the Findings for any entity above, add a createdAt_gt filter. Note you can use multiple filters, and also add additional parameters to the filter (e.g. use both the severity and createdAt_gt in the same filter).

This query includes mergedFindingRefId : null in the filter to only get the findings that are not merged. If you want to include merged findings, remove this line from the filter.

query GetFindingsCreatedAfterForAnAssetVersion (
  $filter: FindingFilter
) {
  allFindings(filter: $filter) {
    id
    title
    severity
    createdAt
  }
}

Get Tags for A Product

The Tags on Products and other entities feature is in development and is not yet available.