Getting Data From Tanium

Tanium provides endpoint visibility at unmatched speed and scale. Leveraging this high fidelity IT and Security data can bring tremendous value to other systems in an organization. This is the most common integration scenario for Tanium partners and customers. You can get hardware and software information directly from the source: the endpoints themselves. Whether you need basic Asset information like Operating System and Patch Status, or something more complex like an endpoint’s Risk Score or latest Compliance Assessment, Tanium is the best source.

A sensor is a script that runs on an endpoint to compute a response to a Tanium question. Tanium has hundreds of sensors available in the Core Platform alone, and hundreds more when you consider the different modules that might be installed. Understanding this core concept in Tanium is a prerequisite for any integration. Start by reading the introduction to Asking Questions found here.

For a list of the data points you can query from Tanium, see the Sensor Inventory List.

Data Sources

There are several different data sources inside of Tanium that an integration can get data from. The best source to choose depends on what data you need and if you need it via a push or a pull.

• Tanium Data Service (TDS): This is Tanium's primary data caching layer and stores recent sensor data from online and offline endpoints as well as virtual sensor data from the different Tanium solutions.
• Tanium Solutions: Some Tanium modules, such as Asset and Comply, have their own data stores.
• Live Endpoints: An endpoint that is online can answer live queries and send data directly.

TDS is the preferred data source for integrations whenever possible. It returns recent data very quickly from online and offline endpoints and is low impact on the environment. Refer to Best Practices to determine if the sensors you need should be collected in TDS. Integrating with live endpoints via DEC, Stream, or live questions should be reserved for cases where the data can't be retrieved from TDS. Tanium solution data that isn't available in TDS is generally accessed using Connect to push or Module Rest APIs to pull.

Methods

Tanium provides several methods to export your data. While the Integration Methods article can help identify which method is best suited to your integration use case at a high level, this article will cover the most common integration scenario: getting data out of Tanium to ingest into another system.

If you're a veteran Tanium user, you have likely used some of the older methods available to extract information. Tanium offers several newer available options for retrieving data. It is worthwhile to investigate if migrating existing integrations to a newer option would benefit your organization, and what options might be leveraged for building new integrations. For example, our partners and customers have experienced improvements in performance and data quality by migrating from Saved Questions to Reporting, or from the Platform REST API to GraphQL.
To illustrate this, we'll walk through how to get the same data set 4 different ways. We'll be retrieving the list of endpoints where a specific piece of software is installed. In priority order, these methods are:

1. Design a Report using the Reporting solution to export data using Connect or GraphQL
2. Design a GraphQL endpoints query to pull live or cached data
3. Export data from Asset using a View
4. Design a saved question in the Interact module and use the Connect module to deliver the data on a schedule
   

The methods described in this guide cover the vast majority of integration scenarios. However, be aware that additional special-purpose methods exist to retrieve certain data directly from a Tanium Solution or Managed endpoint.

• Module-specific Connect sources for tasks such as exporting Comply Findings
• Tanium Stream to get a data feed directly from endpoints
• Various Module REST APIs
• Other GraphQL queries for data from Asset, Discover, etc.

Reporting

Tanium Reporting allows you to visually explore data from TDS in a grid view to design a Report. You can flatten the data in the report based on any collected Sensor. Reports are the preferred method of accessing data from Tanium for most scenarios as they have several benefits over the other data access methods. Note that Tanium Reporting is a separate solution from Asset Module Reports.

• Ease-of-Use: Reports are intuitive and easy to design for non-programmers, allowing you to focus on the data itself rather than the access method.
• Flexibility: Reports can either be delivered as a push via the Connect module or as a pull using GraphQL in Tanium Gateway.
• Efficiency: Because it uses TDS as its data source, Reporting is a fast and efficient way to get data for both online and offline endpoints.

While Reporting is the best method to get data from Tanium for many scenarios, there are times when another method will be the better choice. Examples:

• You need to run ad-hoc queries where the fields returned or the filters applied change. A GraphQL endpoints query is the best choice for this.
• You need to retrieve data that is not stored in TDS. For this, you'll need to leverage a live GraphQL query or a module-specific Connect feed.
• You have complex filtering requirements, such a per-row/left side filtering, regular expressions, or advanced comparison operators. Use a Saved Question or GraphQL endpoints query.
• You need to investigate a live endpoint. This may require Direct Connect through GraphQL or the Threat Response API.

Example: Get Endpoints with Adobe Refresh Manager using Reporting

Using the Tanium Data Console, create a custom report that provides a list of endpoints that Asset SIU reports having Adobe Refresh Manager installed.

Once you have created a report that shows the data you need, you can either set up a Connect job to push that data to your downstream system or use GraphQL to pull the report data.

Pushing Report data with Connect

Create a new Connection with the Tanium Reporting (Source Data) Source and select your custom report.

Pulling Report data with GraphQL

You can pull report data using GraphQL using the Report ID. The easiest way to get this is by looking at the URL query parameter in your browser when you view the report. You can also retrieve the Report ID programmatically using the reports GraphQL query. Use the returned cursor information to page through the results.

query getReportResultData($id: ID!, $first: Int) {
  reportResultData(id: $id, first: $first) {
    edges {
      node {
        columns {
          values
        }
      }
    }
    viewDetails {
      columns {
        name
        sourceName
        sourceColumnName
      }
    }
     collectionInfo {
      active
      startCursor
    }
  }
}

Variables:

{
  "id": "3d299636-6edd-46be-a830-103e16f509d9",
  "first": 200
}

GraphQL Endpoints Query

A Tanium Gateway GraphQL endpoints query is the most advanced way to retrieve data from Tanium. It has a comprehensive set of filtering capabilities and is well suited to integrations that run ad-hoc queries for data. The endpoints query leverages TDS for data by default, but can also target the Tanium Server to get data directly from live endpoints. GraphQL queries can only be used to programmatically pull data and is not compatible with the Connect module for pushing data. GraphQL queries support the filtering of results. Documentation of filter syntax can be found here.
Use the returned cursor information to page through the results.

Example: Get Endpoints with Adobe Refresh Manager using GraphQL

query getAdobeRefreshManager($cursor: Cursor, $first: Int, $sensor: String!, $endpointfilter: EndpointFieldFilter, $rowfilter: SensorValueFilter, $columns: [String!]) {
  endpoints(after: $cursor, first: $first, filter: $endpointfilter) {
    totalRecords
    edges {
      node {
        sensorReadings(
          sensors: [{name: $sensor, columns: $columns, filter: $rowfilter}]
        ) {
          columns {
            name
            values
            sensor {
              name
            }
          }
        }
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

Variables:

{
  "first": 1000,
  "cursor": null,
  "sensor": "Asset SIU Installed Products",
  "endpointfilter": {
    "filters": [
      {
        "sensor": {
          "name": "Asset SIU Installed Products",
          "column": "Vendor"
        },
          "op": "CONTAINS",
          "value": "Adobe"
      },
      {
        "sensor": {
          "name": "Asset SIU Installed Products",
          "column": "Name"
        },
          "op": "CONTAINS",
          "value": "Refresh Manager"
      }
    ]
  },
  "rowfilter": {
    "filters": [
      {
        "column": "Vendor",
        "op": "CONTAINS",
        "value": "Adobe"
      },
      {
        "column": "Name",
        "op": "CONTAINS",
        "value": "Refresh Manager"
      }
    ]
  },
  "columns": [
    "Vendor",
    "Name",
    "Version"
  ],
  "column": "Vendor",
  "vendor": "Adobe"
}

Asset Module API

If you need data about endpoints that have been offline longer than 30 days, the Asset Module API is the correct way to get the data. Data for offline endpoints ages out of TDS after 30 days, whereas the Asset DB keeps it for 180 days by default. Create a custom view in the Asset Workbench that contains the data you need and then retrieve the data using the Asset Module REST API assets endpoint, specifying the View ID. The easiest way to get the ID is by looking at the URL in your browser when you create the View. You can also retrieve the View ID programmatically using the /plugin/products/asset/v1/views endpoint. Page through the results using the minimumAssetId and limit query parameters.

Example: Get Endpoints with Adobe Refresh Manager using Asset API

curl --location 'https://mycompany.cloud.tanium.com/plugin/products/asset/v1/assets?viewId=51&minimumAssetId=1&limit=200' \
--header 'session: token-XXXXXX'

Saved Questions

A Tanium Question is a query that you issue from the Tanium Server to managed endpoints. This is considered a legacy method for getting data from Tanium and is no longer the preferred method of integration for most scenarios.
Multiple sensors can be used within questions, varying in complexity and in the level of impact on the endpoint. Questions can be constructed using Tanium's natural language syntax or using the Question Builder in Interact. The Interact Solution is part of Tanium Core, so all customers will have access to it.

A question is composed of three parts:

1. Sensors to use to gather data from endpoints, including any parameters
   
2. Computer Group to target
3. Optional Filters on which endpoints should answer the question

The easiest way to design a Question in Interact is to use the Question Builder since it allows searching for sensors you want to run and prompts for any required or optional parameters. Question Builder will generate the natural language version of the question for you, which can then be saved for later use.

Questions are composed of the primary clauses get and from.

Syntax: 

    get <sensor name> from <computer group>  

-------------------- 
Example: 

    get Computer Name from all machines  

Question Filtering

Tanium questions have two primary options to limit question results returned by each endpoint. The right of a question runs first and determines whether an endpoint should answer the question at all. The filters on the left side of a question filter the results returned by a sensor to just the values of interest
In Summary:

• Right Side filters control which endpoints will answer the question.
• Left Side filters, AKA per-row filters, limit the specific values returned by sensors from each endpoint.
  

The basic format of a filtered question is as follows, with the from all machines being the centerpiece of the question.

get <sensor> <relational operator> <value> 
from all machines <sensor> <relational operator> <value> (plus assigned computer groups)

If an endpoint meets the criteria from the right side filter condition but the sensor does not include a value meeting the left side filter condition, the respective device reports [no results]. This is why questions often have the same filter on both the left and right side. This differs from Tanium Reporting, which filters out the [no results] responses automatically.

The order of evaluation by endpoints is:

1. Computer Groups: Computer Groups assigned to a user for management rights get appended to every question. Users should not have many Computer groups assigned for management rights, as it makes the generated questions very long.

2. Right Side Filters: If the user has sent a question with right side filters, these are evaluated next. If this evaluates to false, the Tanium Client sends the question onward, and the left side of the question never gets evaluated. If the right side filter evaluates to true, the question is queued for answering by the Tanium Client, and the next step occurs.

3. Left Side Filters: If the left side filters evaluate to true, then the answer is provided by the Tanium Client. If the left side filters are false, [no results] is returned, because the question is constructed in such a way that this endpoint is intended to answer the question.

Saving a Question

Once you’ve crafted a question that you’re satisfied with, you can save this question with a helpful name for future reuse. Documentation describing this process can be found here. If you run a saved question in the Tanium Interact UI, you will see that the results table has tabs for three different result sets: Current, Recent, and Cached. The differences between each are outlined below, but more detail can be found here.

• Current: This reflects live results only from those endpoints that are currently online.

• Recent: This set of results is available for saved questions only. It uses an older caching mechanism on the Tanium Server and should rarely, if ever, be used for integrations.

• Cached: This set of results reflects the data stored in TDS and includes both online and offline endpoints.

Example: Get Endpoints with Adobe Refresh Manager using Saved Question

Get Computer Name and Asset SIU Installed Products matches .*Adobe.*Refresh Manager.* from all machines with Asset SIU Installed Products matches .*Adobe.*Refresh Manager.*

Exporting with Connect

Tanium Connect can be used to ask these saved questions on a user-defined schedule, sending the results to a variety of downstream systems. The same 3 data source options for saved questions that are available in the Interact console are available when sending the question from Connect.

• To get results from endpoints that are online at the time it is asked, use the Saved Question source. You can check the Include Recent Answers box to match the recent option in Interact.
• To get results from online and offline endpoints using data in TDS, use the Tanium Data Service source. This matches the cached option in Interact.

WARNING: When you configure a Connect job using the Tanium Data Service source, all sensors used in the question will be automatically registered for collection in TDS. Please ensure these sensors are good candidates for TDS before creating the connection.

Querying the Tanium Server

Not all Tanium Sensors return data that is appropriate to store in TDS. In those cases, it is necessary to query the data with a live question. This is best accomplished using the GraphQL endpoints query and setting the source parameter to ts. See example here. There are several options for how to determine "completion" of a query, but stableWaitTime is usually a reasonable choice unless you know exactly how many endpoints should respond.

Live Query Completion Conditions

A live query will run and continue collecting results from endpoints until any of the following completion criteria is met:

• 30 seconds has elapsed.
• The optional expectedCount parameter was used and that many endpoints have responded to the question.
• The optional stableWaitTime parameter was used and at least 1 endpoint has returned a result, but the specified number of seconds has elapsed with no additional responses received.

Refresh Cursors

To ensure you get the responses from any "long tail" endpoints that are slow to respond to questions, you'll need to use a refresh cursor. This will get all the results from any endpoints whose response arrives after the initial completion condition.

Example Queries

Additional Tanium Gateway GraphQL examples, including for targeting live endpoints, are found in the Tanium Gateway documentation here.

Best Practices

If TDS has the data you need, it is almost always the best option for a data source over a live question due to its fast response time and low-impact design. To determine if the sensors you need to read are a good candidate for collection in TDS, go to the Interact Module workbench and select the Gear Icon at the top right. Click the sensor you are interested in and select Add from the dropdown menu at the right. If you see a message like the one in the image below with a green checkbox(This sensor returns a low number of unique results. Confirm to register this sensor for collection.), it means the sensor is probably appropriate for collection in TDS.

In terms of resource consumption, questions and sensors will have varying impacts on endpoints when asking a live Question. As sensors are scripts executed on the endpoints, they consume resources from said endpoint. For the most part, Tanium questions have a light impact on the endpoint itself, but some sensors are more costly than others. Regardless, you should never create an integration that is querying live endpoints every few minutes for data.

When assessing your question, be aware of whether or not the question is a counting question. This will impact the size of the response received by the Tanium server. More unique data points will consume more resources. Next, assess the specific sensors that make up the question, considering things such as:

• What is the cardinality of the results? A sensor that returns many unique values is more expensive.
• How long does each sensor take to run?
• How many endpoints are being targeted?
• How often will this question be run?

A good indicator of sensor performance can be found by reviewing the average execution time. Navigate to Administration > Content > Sensors and click the Show option at the top left for runtime.

Access Control

A user can ask questions using sensors that are part of Content Sets they have access to and can target endpoints that are in Computer Groups they have access to. You can read about Tanium RBAC here. Users can only ask questions to machines for which they have management rights. This is an implicit component of any query for data from Tanium, regardless of the method. While not explicitly shown in the question bar, report, or other data access method, management rights are always applied.