Skip to main content

Gateway GraphQL

Connects to Tanium Gateway to execute custom GraphQL queries and retrieve structured data from Tanium security platform.

Description​

The Tanium GraphQL input connector allows you to fetch data from any Tanium GraphQL endpoint by executing custom GraphQL queries. It provides access to the full Tanium data model through GraphQL, enabling you to collect specific data points and relationships from your Tanium security platform.

This connector is built on top of the universal GraphQL input and is pre-configured with Tanium-specific authentication and endpoint settings, making it easier to connect to Tanium instances.

Features​

  • Custom GraphQL Queries: Execute any valid GraphQL query against your Tanium endpoint
  • Automatic Pagination: Built-in cursor-based pagination support with configurable paths
  • Tanium Authentication: Pre-configured authentication using Tanium session tokens
  • State Management: Maintains pagination state for incremental data collection
  • Flexible Record Location: JSONPath support for extracting records from nested response structures

Requirements​

  1. A Tanium instance with GraphQL API access enabled
  2. An API token with permissions to access the required data
  3. The base URL of your Tanium instance (e.g., https://<customerName>-api.cloud.tanium.com for cloud or https://<server> for on-prem)
  4. Knowledge of the Tanium GraphQL schema and desired query structure

Setup Instructions​

  1. Generate an API Token:

    • Log in to your Tanium instance
    • Navigate to Administration > Permissions > API Tokens
    • Click Create API Token
    • Fill in the Description field with a meaningful name for your token
    • Select the Expiry duration in days
    • Configure Allow whitelist IPs if needed for enhanced security requirements. For most deployments, using 0.0.0.0/0 (all IPs) is recommended for operational simplicity. If your organization requires IP restrictions, whitelist Monad's IP addresses:
      • For Monad SaaS: 35.81.245.33, 35.83.26.83, 35.84.110.88
      • For Monad on-premises: Your Monad instance's IP address
    • Click Create to generate the token
    • Copy the generated token and store it securely

  2. Obtain the Base URL:

    • Note the API URL of your Tanium instance
    • For Tanium Cloud: https://<customerName>-api.cloud.tanium.com
    • For on-premises: https://<server>

  3. Test Your GraphQL Query:

    • Use the Tanium GraphQL explorer or API documentation to test your query
    • Ensure your query returns the expected data structure
    • Note the JSONPath location of your records in the response

Configuration​

Settings​

SettingTypeRequiredDescription
Base URLstringYesThe base URL of your Tanium instance (e.g., https://<customerName>-api.cloud.tanium.com for cloud or https://<server> for on-prem)
GraphQL QuerystringYesThe GraphQL query to execute against the endpoint to fetch data
Interval SecondsintegerYesTime interval in seconds between consecutive GraphQL API calls (minimum: 10, default: 10)
Record LocationstringYesJSONPath location of the records array in the GraphQL response (e.g., "data.endpoints.edges")
VariablesarrayNoArray of variables to pass with each GraphQL request
Enable PaginationbooleanYesEnable pagination support (default: false)
Pagination Cursor PathstringConditionalJSONPath location for the pagination cursor/token in the response (required if pagination is enabled)
Has Next Page PathstringConditionalJSONPath location to check if there are more pages available (required if pagination is enabled)

Secrets​

SettingTypeRequiredDescription
TokenstringNoThe API token for authentication with Tanium

Variables Structure​

Variables are defined as an array of objects with Name and Value properties:

[
  {
    "Name": "first",
    "Value": "100"
  },
  {
    "Name": "status",
    "Value": "ACTIVE"
  }
]

Pagination Configuration​

When Enable Pagination is set to true, you must configure:

  1. Pagination Cursor Path: JSONPath to extract the next page cursor from the response
  2. Has Next Page Path: JSONPath to check if more pages are available

The connector automatically uses after as the cursor variable name in your GraphQL query.

Example Pagination Setup​

GraphQL Query:

query GetEndpoints($first: Int!, $after: String) {
  endpoints(first: $first, after: $after) {
    edges {
      node {
        id
        name
        computerName
        ipAddress
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

Configuration:

  • Record Location: data.endpoints.edges
  • Pagination Cursor Path: data.endpoints.pageInfo.endCursor
  • Has Next Page Path: data.endpoints.pageInfo.hasNextPage

Example Configurations​

Simple Endpoints Query​

{
  "settings": {
    "base_url": "https://mycompany-api.cloud.tanium.com",
    "graphql_query": "query { endpoints { edges { node { id name computerName ipAddress } } } }",
    "interval_seconds": 300,
    "record_location": "data.endpoints.edges[*].node",
    "enable_pagination": false
  },
  "secrets": {
    "api_token": "your-tanium-token-here"
  }
}

Paginated Computer Groups Query​

{
  "settings": {
    "base_url": "https://tanium.example.com",
    "graphql_query": "query GetComputerGroups($first: Int!, $after: String) { computerGroups(first: $first, after: $after) { edges { node { id name type expression } } pageInfo { hasNextPage endCursor } } }",
    "interval_seconds": 600,
    "record_location": "data.computerGroups.edges[*].node",
    "variables": [
      {
        "Name": "first",
        "Value": "50"
      }
    ],
    "enable_pagination": true,
    "pagination_cursor_path": "data.computerGroups.pageInfo.endCursor",
    "has_next_page_path": "data.computerGroups.pageInfo.hasNextPage"
  },
  "secrets": {
    "api_token": "your-tanium-token-here"
  }
}

Assets Query with Filtering​

{
  "settings": {
    "base_url": "https://mycompany-api.cloud.tanium.com",
    "graphql_query": "query GetAssets($filter: String!) { assets(filter: $filter) { edges { node { id computerName serialNumber manufacturer operatingSystem } } } }",
    "interval_seconds": 1800,
    "record_location": "data.assets.edges[*].node",
    "variables": [
      {
        "Name": "filter",
        "Value": "operatingSystem:Windows"
      }
    ],
    "enable_pagination": false
  },
  "secrets": {
    "api_token": "your-tanium-token-here"
  }
}

Common GraphQL Queries​

Endpoints with Basic Information​

query {
  endpoints {
    edges {
      node {
        id
        name
        computerName
        ipAddress
        operatingSystem
        lastSeen
      }
    }
  }
}

Best Practices​

  1. Query Optimization: Write efficient GraphQL queries that only fetch required fields to minimize response size
  2. Pagination: Use pagination for large datasets to avoid timeouts and memory issues
  3. Rate Limiting: Configure appropriate intervals between requests to respect API quotas
  4. Error Handling: Monitor logs for GraphQL errors and schema validation issues
  5. Testing: Use the Tanium GraphQL explorer to test queries before deployment
  6. Authentication: Store API tokens securely and rotate them regularly

Troubleshooting​

Common Issues​

  1. Invalid GraphQL Query:

    • Ensure your query is valid GraphQL syntax and matches the Tanium schema
    • Use the Tanium GraphQL explorer to test queries
    • Check field names and types against the schema

  2. Record Location Not Found:

    • Verify the JSONPath in record_location matches your response structure
    • Use tools like JSONPath evaluators to test your path expressions
    • Check the actual response structure in logs

  3. Authentication Failures:

    • Verify your API token is valid and has proper permissions
    • Check token expiration and rotate if necessary
    • Ensure the token has access to the data you're querying
    • Verify that Monad's IP addresses are whitelisted if IP restrictions were configured during token creation.
    • Check if the token was created with appropriate expiry duration.
    • Regenerate the token if it has expired or permissions have changed.

  4. IP Whitelist Issues:

    • If you configured IP whitelisting during token creation, ensure Monad's IP addresses are included:
      • For Monad SaaS: 35.81.245.33, 35.83.26.83, 35.84.110.88
      • For Monad on-premises: Your Monad instance's IP address
    • Consider using 0.0.0.0/0 for simpler configuration if your security policies allow it.
    • Check if your organization uses NAT or proxy servers that might change the outbound IP.
    • Update the token's IP whitelist if Monad's IP addresses have changed.

  5. Pagination Issues:

    • Ensure cursor paths are correct and match the response structure
    • Verify your GraphQL query includes pagination variables
    • Check that the after variable is properly defined in your query

  6. Connection Issues:

    • Verify the base URL is correct and accessible
    • Check for firewall or network restrictions
    • Ensure the GraphQL endpoint is available at /plugin/products/gateway/graphql

Error Messages​

  • "graphql request returned an error": Check your query syntax and schema compatibility
  • "record location not found in response": Verify your JSONPath in the record location setting
  • "authentication failed": Check your API token and permissions
  • "invalid cursor": Verify pagination cursor paths and query structure

Sample Records​

The output format depends on your GraphQL query and record location. Here are examples for common queries:

Endpoint Record​

{
  "id": "12345",
  "name": "DESKTOP-ABC123",
  "computerName": "DESKTOP-ABC123",
  "ipAddress": "192.168.1.100",
  "operatingSystem": "Windows 11 Enterprise",
  "lastSeen": "2024-10-27T10:30:00Z",
  "manufacturer": "Dell Inc.",
  "serialNumber": "ABC123DEF456"
}