Querying Tanium

Tanium provides endpoint visibility at unmatched speed and scale. Leveraging this high fidelity data about an organization’s IT and Security can power an endless variety of integrations. 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. For a list of the data points you can query from Tanium, a Sensor Inventory list is provided.

Methods

There are several ways to get data out of Tanium. Please review the Integration Methods article to help select which method is best suited to your use case.

This article will cover the most common scenarios for getting data out of Tanium.

  1. Design a saved question in the Interact module and use the Connect module to deliver the data from live endpoints downstream on a schedule
  2. Design a GraphQL query to pull live or cached data into your system.

Understanding Questions

Tanium has hundreds of sensors available in the core platform alone, and hundreds more when you consider the different modules that might be installed. A sensor is a script that runs on an endpoint to compute a response to a Tanium question. A Tanium Question is a query that you issue from the Tanium Server to managed endpoints. Multiple sensors can be used within questions, varying in complexity and in the level of impact on the endpoint. Some sensors, described as Parameterized Sensors, require user input for execution. Question syntax supports these parameters being passed inline.

Understanding this core concept in Tanium is a prerequisite for any integration. Start by reading the introduction to Asking Questions found here.

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.

Interact Questions

Interact is a core part of Tanium and all customers will have access to this module.

A question is composed of three parts:

  1. Sensors to use to gather data from Endpoints
  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.
It allows searching for sensors you want to run and prompts for any required or optional parameters.

If you prefer, you can manually type a question using Tanium’s natural language syntax. 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 hand of a question runs first and determines whether or not the left hand side will execute at all. The right side filters the machines that will answer the question. The left side of a question filters the results returned by a sensor to just the values of interest.

The basic format of a 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 the sensor output does not include a value meeting the left hand side filter condition, the respective device reports [no results]. This is why questions sometimes have the same filter on both the left and right hand side. For example, the following question has no right hand side filter. In other words, the question ends with "from all machines" and is only restricted by the user's assigned Computer Groups for management rights.

The left hand side filter is combing out all results that do not contain xyz. Since no Computer Name contains xyz, the [no results] is shown. 


Get computer name contains xyz from all machines


Question - Left Side Image

To avoid seeing [no results], a right side filter is also needed. This will block machines from answering the question that do not match the filter. In this case, 


Get computer name contains xyz from all machines with Computer Name contains xyz


Question - Right Side Image

The order of evaluation by endpoints is:

  1. Computer Groups - Whatever Computer Groups are assigned to a user for management right's get added to every question, which is why users should not have a lot of Computer Groups assigned for management rights; it makes the questions get 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.

Recall that a user's computer groups is the main filter that gets added to every single question. Users can only ask questions to machines for which they have management rights. This implicit part of the question is not shown in the question bar but is always present in outgoing questions since this is how the client determines whether or not a user has the rights to run the question in the first place.

Note: In addition to filters, there is a user preference "Hide error results from questions". This is an often-forgotten setting that is likely enabled. Toggle this setting to check that the sensors are not producing errors. The data may be getting returned, but if a sensor is experiencing an error, the results may be hidden.

Exporting Saved Questions with Connect

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 will 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

    • Reflects the results only from the endpoints that are currently online.

  • Recent

    • This set of results is available for saved questions only. It includes the results from the online endpoints, but also includes results from offline endpoints if those results still reside on the Tanium Server after the last time the server issued that question. The Tanium Server stores the results of saved questions for seven days by default.

  • Cached

    • This set of results reflects those that the Tanium Server collects by periodically querying all managed endpoints for specific sensors. The option appears only for questions in which all the sensors are registered for harvest in TDS. The server stores the results for 30 days by default.

Tanium Connect can be used to ask these saved questions on a user-defined schedule, sending the results to a variety of destinations, such as an external server, an AWS S3 bucket, or to your Splunk instance.

There are several advantages to using this method, not least of which is that it allows a user to get live, up-to-date data from Tanium endpoints in a way that requires zero code to be written. A second advantage is that Tanium Connect allows for advanced filtering of the data before it is sent to the configured destination.

Be aware that because saved questions only return results from endpoints that are currently online, you may need to schedule Connect to deliver the results to you frequently so that you can cache the results for offline systems. Depending on the nature of the data you need, you could also consider registering your sensors for harvest by TDS and receiving data from there.

API Gateway and GraphQL

The Tanium API Gateway provides an alternative way to query information from Tanium. Rather than Saved Questions, the API Gateway uses a GraphQL API to allow structured queries that comply with the published schema for information.

New to GraphQL and want to learn more? Already familiar with other types of APIs like REST or SOAP? https://graphql.org is a great place to get started.

Querying TDS

The default backend for the API Gateway is TDS, the Tanium Data Service. This is a caching layer, and it means that the GraphQL queries are very fast, don’t go to the endpoints directly, and can return results from offline machines.

A more detailed description of TDS, and how to configure the collection of its data collection here.

Querying the Tanium Server

Not all data from Tanium Sensors has been incorporated into the GraphQL Schema and not all Tanium Sensors return data that is appropriate to store in TDS.

To accommodate this, the API Gateway has a sensorReadings feature that allows you to read from any raw sensor. For sensors that are harvested by TDS, you can use sensorReadings with the default API Gateway data source. For sensors that are not harvest by TDS, you will need to use the alternative Tanium Server source.

Setting the query's source to the Tanium Server is done by setting the source of the endpoints query. 

{
  endpoints(source: {ts: {expectedCount: 1, stableWaitTime: 10}}) {
    edges {
      node {
        computerID
        name
        serialNumber
        ipAddress
      }
    }
  }
}

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.

If the integration is intended to run in an environment with an expected “tail” of results trickling in from endpoints beyond 30 seconds, then it is advised that the REST API be used to do the live Question.

Example Queries

Some example queries, including the query above, can be found in the API Gateway documentation here.

Migrating Questions to GraphQL

It is quite common to determine a set of data you want to export via a Question and then need to figure out how to construct the equivalent GraphQL query to get at the same data.

For example, a common question that may be asked is: 

Get Computer Name and Custom Tags from all machines

To convert this question into an API Gateway query, first identify which, if any, of the items are already part of the schema. This requires a search of the API Gateway’s schema, found here. In the case of this question, we can see that the computer name can be found by querying the name attribute.

There is no named field in the API Gateway schema for the Custom Tags sensor because it is unregistered. We need to refer directly to the sensor instead. To get the values returned by sensors in your query, include the sensorReadings field in your query. Provide the name of the sensor that you would like to run and the columns you want returned. In the case of the question above, a query might be: 

{ 
  endpoints() { 
    totalRecords 
    edges { 
      node { 
        name 
        sensorReadings(sensors:[{name:"Custom Tags"}]) { 
          columns { 
            sensor {name} 
            values 
          } 
        } 
      } 
    } 
  } 
}

Filters

GraphQL queries support the filtering of results. Documentation of filter syntax can be found here.

When querying the API Gateway, filters are used to limit the possible values returned by the targeted endpoints. This is equivalent to left-side filters in Tanium Questions. If you need to instead limit which endpoints are represented in the Query results (a right-side filter), you will need to create a new computer group matching the desired criteria and use that for targeting. 

{ 
  endpoints(filter:{sensor:{name:"Custom Tags"}, value:"InstalledByTCM"}) { 
    totalRecords 
    edges { 
      node { 
        name 
        sensorReadings(sensors:[{name:"Custom Tags"}]) { 
          columns { 
            values 
          } 
        } 
      } 
    } 
  } 
}

The Tanium Community forum is a great place for help with your queries.

Best Practices

If TDS can be used to get the data you need, it is usually a better option as a data source than a live question. To determine if the sensors you need to read are a good candidate for collection, 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, it means the sensor is probably appropriate for collection in TDS.

Sensor Preview Image

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?

These basic questions will help assess how impactful certain queries will be.

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.

Sensor Impact Image