DocumentationAPI ExplorerRecipesCommunityChangelogRSSSubscribe
Documentation

GraphiQL Playground

Suggest Edits

Introduction

GraphiQL is a browser-based user interface for interactively testing and executing queries against the Tenable OT Security GraphQL API. This document describes the steps necessary to set up the GraphiQL playground for testing the Tenable OT Security API. It also explains the basic concepts of GraphQL queries and includes several example queries.

Prerequisites

Before using the GraphiQL playground, you need the following prerequisites:

  • API key—You need to generate an API key. To generate an API key for Tenable OT Security, see Generate an API Key.
  • Configure the GraphiQL playground—Before executing GraphQL queries, you'll need to configure:
    • The URL used for queries.
    • The HTTP headers to include your API key.

Configure GraphiQL Playground

Open the GraphiQL playground for your Tenable OT Security instance by pointing your browser to the GraphiQL URL. For example, https://{ipaddress}/graphiql. Once loaded, you see the interface shown in the screenshot below. It may or may not be pre-populated with data.

GraphiQL Playground

To configure the GraphiQL playground, you first need to change the URL used for queries. Second, you need to insert your API key into the HTTP headers. An API key is required for interacting with the Tenable OT Security API, and your API key is passed to the Tenable OT Security API via HTTP headers.

To change the URL used for queries:

Edit the existing URL next to the History button. Change the URL from https://{ipaddress}/graphiql to https://{ipaddress}/graphql without the letter i.

URL

To add your API key to the HTTP headers:

Click HTTP Headers in the bottom left to open the HTTP headers pane. Paste the JSON snippet below into the HTTP headers input box and insert your API key.

Note that when you first access the GraphiQL playground, the HTTP Headers pane might be collapsed at the bottom of the page. Click HTTP Headers to expand it.

{
	"X-APIKeys": "key=<INSERT_KEY>"
}

If you see a horizontal red line or a red notification next to one of the line numbers then there might be an issue with the formatting. Check what was pasted to make sure there aren’t any extra characters or missing brackets. Your HTTP headers should look like the screenshot below.

API Key

Execute a GraphQL Query

Once you have configured your API key and the URL used for queries, you're ready to execute your first GraphQL query in the playground. Queries are GraphQL operations that search for and return data from fields in the schema. A single query can search for and return data for a single field or multiple fields.

In the left-hand query pane, enter the following GraphQL query to return assets in Tenable OT Security:

query getAssets {
	assets {
		nodes {
			...inventoryAsset
		}
    count: totalCount
	}
}
fragment inventoryAsset on Asset {
	details
}

You should see data appear on the right hand results pane similar to the following screenshot:

GraphiQL Playground

If no data was returned from query, then you should verify the following:

  • The API key in the HTTP headers section is properly formatted and valid.
  • The specified URL has graphql instead of graphiql.
  • You copied and pasted the complete GraphQL assets query.

Query Variables

Variables simplify GraphQL queries by allowing you pass data separately and reuse the same query with different arguments.. A GraphQL request can be split into two sections: one for the query and another for variables.

For example, you can create a query to retrieve asset details and create a variable for the asset, thus allowing you to reuse the same query to retrieve details for different assets. Additionally, a query designed to pull the details for a specific asset specified in a variable performs much more quickly than a query designed to pull details for all assets.

The GraphQL query below utilizes an $asset variable to return asset details for an asset UUID specified as a variable.

query getAssetDetails($asset: ID!) {
	asset(id: $asset) {
		id
		details
	}
}

Before you can execute the GraphQL query above, you'll need to define the $asset query variable by assigning the asset UUID for the asset you want to retrieve details for.

{
	"asset":"6671545f-9b6f-4b9e-9009-b874ef40858f"
}

To add a query variable in the GraphiQL playground, click Query Variables in the bottom left to open the query variables pane. Paste the query variable snippet above into the input box.

Note that when you first access the GraphiQL playground, the Query Variables pane might be collapsed at the bottom of the page. Click the Query Variables header to expand it.

GraphiQL Playground

If you have any errors with the formatting, syntax, or variable then an error message will be displayed with a short explanation.

GraphiQL Playground

Once you have entered the query and the query variable, you can execute the query to retrieve the details for the asset UUID specified in the query variable.

Search Filters

You can add search expressions that filter the data returned in queries based on fields and parameters that you specify. Filters allow you to return only the data for the items you're interested in. Note that filters can be used in combination with query variables.

For example, the following GraphQL query utilizes filters to pull only assets of the NetworkAssetsCategory category and which aren't hidden. The results are then sorted by risk and id.

Enter the following GraphQL query into the query pane:

query getAssets(
  $filter: AssetExpressionsParams
  $search: String
  $sort: [AssetSortParams!]!
  $after: String
  $first: Int
) {
  assets(
    filter: $filter
    sort: $sort
    search: $search
    after: $after
    first: $first
  ) {
    nodes {
      ...inventoryAsset
    }
    count: totalCount
  }
}
fragment inventoryAsset on Asset {
  details
}

Before you execute the GraphQL query above, you'll need to define the query variables. Enter the following query variables in the query variable pane:

{
  "filter": {
    "op": "And",
    "expressions": [
      {
        "field": "category",
        "op": "Equal",
        "values": "NetworkAssetsCategory"
      },
      {
        "field": "hidden",
        "op": "Equal",
        "values": "false"
      }
    ]
  },
  "sort": [
    {
      "field": "risk",
      "direction": "DescNullLast"
    },
    {
      "field": "id",
      "direction": "AscNullLast"
    }
  ],
  "first": 200
}

Once you have entered the query and the query variables, you can execute the query.

Multiple Queries

The GraphiQL playground allows you to enter multiple GraphQL queries at once in the left-hand query pane. You can then choose which query to execute from the drop-down that appears when you click the play button.

For example, enter the following queries into the query pane:

query assetGroup  { assetGroups  { nodes { name, id, system } } } 
query protocolGroup { protocolGroups  { nodes { name, system, id } } }
query  scheduleGroup {scheduleGroups { nodes { name, id, system } } }
query  emailGroup   {emailGroups    { nodes { name,id  server {  name  } }  } }
query  portGroup    {portGroups    { nodes { name, id, system } } }
query  SyslogGroup    {syslogServers    { nodes { name, id } } }
query  emsGroup    {smtpServers    { nodes { name, id } } }
query  config    {config { DNSConf { value {nameservers }} privateNetworks { nodes}} }

Click the play button to choose which query to execute:

GraphiQL Playground Play

Example Queries

Some example queries along with their associated query variables are shown below to help you become accustomed to working with the Tenable OT Security API.

Example 1

This example pulls the system logs for your Tenable OT Security instance. System logs contain a list of all system events that occurred in the system (e.g. policy turned on, policy edited, event resolved etc.).

Enter the following GraphQL query into the query pane:

query getSystemLog {
  systemLog {
    nodes {
      message
      timeStamp
      userName
      __typename
    }
    __typename
  }
}

Example 2

This example pulls all events from Tenable OT Security and sorts the events by the parentEventTime field. Query variables are used to specify the sort field and direction.

Enter the following GraphQL query into the query pane:

query getAggregatedEvents(
  $filter: EventsAggregationsExpressionsParams
  $eventsFilter: EventsExpressionsParams
  $search: String
  $sort: [EventsAggregationsSortParams!]!
  $after: String
  $first: Int
) {
  eventAggregations(
    filter: $filter
    sort: $sort
    search: $search
    after: $after
    first: $first
  ) {
    ...aggregationConnection
  }
  count: events(filter: $eventsFilter, search: $search, slowCount: true) {
    totalCount
  }
}
fragment aggregationConnection on EventAggregationConnection {
  pageInfo {
    ...pageInfo
  }
  nodes {
    id
    parent {
      ...eventsGridItem
    }
    events {
      totalCount
    }
  }
}
fragment pageInfo on PageInfo {
  startCursor
  endCursor
  hasNextPage
  hasPreviousPage
  __typename
}
fragment eventsGridItem on Event {
  id
  logId
  time
  type
  category
  severity
  policy {
    id
    title
    archived
  }
  srcAssets {
    nodes {
      id
      name
      ips {
        nodes
      }
      macs {
        nodes
      }
      type
      hidden
    }
  }
  dstAssets {
    nodes {
      id
      name
      ips {
        nodes
      }
      macs {
        nodes
        __typename
      }
      type
      hidden
      __typename
    }
    __typename
  }
  protocol
  protocolRaw
  resolved
  resolvedUser
  resolvedTs
  comment
  srcIP
  srcMac
  dstIP
  dstMac
  eventType {
    canCapture
    exclusion
    actions
    __typename
  }
  hitId
  __typename
}

Enter the following query variables in the query variable pane:

{
  "sort": [
    {
      "field": "parentEventTime",
      "direction": "DescNullLast"
    }
  ]
}

Updated 3 days ago