# 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: see [Monad egress IP addresses](../../guides/egress-ip-addresses.mdx)
     - 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

| Setting                    | Type    | Required    | Description                                                                                                                            |
| -------------------------- | ------- | ----------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| **Base URL**               | string  | Yes         | The base URL of your Tanium instance (e.g., `https://<customerName>-api.cloud.tanium.com` for cloud or `https://<server>` for on-prem) |
| **GraphQL Query**          | string  | Yes         | The GraphQL query to execute against the endpoint to fetch data                                                                        |
| **Interval Seconds**       | integer | Yes         | Time interval in seconds between consecutive GraphQL API calls (minimum: 10, default: 10)                                              |
| **Record Location**        | string  | Yes         | Location of the records array in the GraphQL response. See [Record Location](../../../guides/record-location) for syntax and examples. |
| **Variables**              | array   | No          | Array of variables to pass with each GraphQL request                                                                                   |
| **Enable Pagination**      | boolean | Yes         | Enable pagination support (default: false)                                                                                             |
| **Pagination Cursor Path** | string  | Conditional | JSONPath location for the pagination cursor/token in the response (required if pagination is enabled)                                  |
| **Has Next Page Path**     | string  | Conditional | JSONPath location to check if there are more pages available (required if pagination is enabled)                                       |
| API Rate Limit | object | No | Optional limit on the connector's outbound request rate to the source API. Leave blank to use the connector's default behavior. See [API Rate Limiting](../../../guides/rate-limiting) for the field format, limits, and how to choose a value. |

### Secrets

| Setting   | Type   | Required | Description                                  |
| --------- | ------ | -------- | -------------------------------------------- |
| **Token** | string | No       | The API token for authentication with Tanium |

### Variables Structure

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

```json
[
  {
    "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:**
```graphql
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

```json
{
  "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

```json
{
  "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

```json
{
  "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
```graphql
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: see [Monad egress IP addresses](../../guides/egress-ip-addresses.mdx)
     - 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

## Related Articles

- [Tanium GraphQL API Documentation](https://help.tanium.com/bundle/ug_gateway_cloud/page/gateway/graphql.html)
- [Tanium Cloud API Documentation](https://help.tanium.com/bundle/ug_gateway_cloud/page/gateway/overview.html)
- [Tanium On-Prem API Documentation](https://help.tanium.com/bundle/ug_gateway_onprem/page/gateway/overview.html)
- [GraphQL Specification](https://spec.graphql.org/)

## Sample Records

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

### Endpoint Record
```json
{
  "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"
}
```