Reference: Advanced question syntax

Use reserved words or characters

Reserved words or characters in question text

The Tanium™ parser uses certain words and characters to interpret the question text that you enter as valid query syntax. For example, the parser uses the bracket characters [ and ] to enclose the values of parameterized sensors and uses variations of the word match to support regular expressions. You must enclose these reserved words and characters in quotation marks when you use them as string literals in questions. For example, to see all endpoints that have computer names containing the letter combination in, issue the question Get Computer Name from all machines with Computer Name contains "in".

ClosedView characters that require quotation marks in questions

  • "

    Use double quotation marks as an escape-character sequence for each instance of quotation marks in a text string. For example, to see which endpoints have a computer name that contains the string "test", issue the question:

    Get Computer Name from all machines with Computer Name contains """test"""

  • .

  • ,

  • :

  • ?

  • $

  • White spaces

    For example, to see which endpoints have a computer name that has a blank space before and after the string DBserver, issue the question:

    Get Computer Name from all machines with Computer Name contains " DBserver "

ClosedView words that require quotation marks in questions

  • all

  • and

  • any

  • contain

  • containing

  • contains

  • does match

  • does not match

  • ending

  • ends

  • equals

  • get

  • having

  • in

  • matches

  • matching

  • not

  • or

  • with

  • starting

  • starts

Reserved words in sensor names

Sensors with names that use reserved words require quotation marks when you use them as string literals in the Interact Ask a Question field. Otherwise, the dropdown list that displays suggested questions cannot accurately match your entry. For example, if you enter the Running Processes with MD5 Hash sensor without quotation marks, the dropdown list displays suggestions that confuse your entry with other sensors that contain the words MD5 Hash:

Figure  1:  Sensor name without quotations

If you use quotation marks around the sensor name, the dropdown list displays the correct question:

Figure  2:  Sensor name with quotations

ClosedView reserved words in sensor names

  • $serverNames

  • $serverIDs

  • $substring

  • $unescape

  • all

  • All

  • ALL

  • and

  • any

  • computers

  • Computers

  • COMPUTERS

  • contains

  • containing

  • equals

  • from

  • From

  • FROM

  • get

  • Get

  • GET

  • having

  • Having

  • HAVING

  • in

  • machines

  • Machines

  • MACHINES

  • matches

  • matching

  • not

  • number

  • Number

  • NUMBER

  • of

  • Of

  • OF

  • or

  • where

  • Where

  • WHERE

  • with

  • With

  • WITH

Use regular expression filters

The question parser supports regular expression matching based on Boost syntax. The following example matches computer names that begin with the letter q in the tanium.com domain.

Figure  3:  Matching a regular expression

The Detect Primary Alerts sensor uses a regular expression to collect results that match any digit in the range 0 to 9. Because alerts have numeric IDs, this expression excludes empty results.

Figure  4:  Regular expression to exclude empty results

You can also use a combination of negation and regular expressions to build filter expressions. For example, the predefined computer group No Computers uses a question with the not matches expression and a regular expression (.*) to match empty results. Because the Computer Name sensor always returns a string, this combination provides a way to prevent action deployment. To stop Tanium Cloudthe Tanium Server from deploying certain actions to any endpoints, configure those actions to target the Default action group, which includes only the No Computers computer group.

Figure  5:  Regular expression to not match anything

Use computer group filters

You can issue questions that specify a computer group in the from clause. Use quotation marks around the computer group name. The computer group can be a management group or filter group. For details about these types, see Managing computer groups.

For computer groups with filter-defined membership, the question parser converts the specified computer group name into the question that determines membership.

Figure  6:  From clause with computer group

Use sensor column filters

Multi-column sensors are designed to collect multiple pieces of related information in a single answer.

Figure  7:  Results from a multi-column sensor

Using the regular expression starts with, ends with, or contains to filter results for a multi-column sensor, such as Installed Applications, can be tricky because the result string for a multi-column sensor is actually a single string with column delimiters. If you are not careful, you might match a string in an unexpected column or unknowingly match a string in a hidden column. For a multi-column sensor, you can specify a particular column for results matching. The syntax is get <sensor> having <sensor>:<column> contains <value>. The column name is case sensitive. Note that single-column filtering works only if the sensor configuration specifies column delimiters (Split into multiple columns field) with a single character (such as |), not multiple characters (such as |:). To match results from all the columns, the syntax is get <sensor> contains <value>.

The following example uses a sensor column filter in the get clause.

Figure  8:  Sensor column filter in the get clause

The following example uses a sensor column filter in both the get clause and the from clause.

Figure  9:  Sensor column filter in the get clause and the from clause

Use $substring() filters

You can use $substring() filters to match result string patterns. The $substring() function takes the following arguments: sensor name, starting position (where 0 is the first position), number of characters.

The following example matches results from the Installed Applications sensor where the first two characters match the string Go.

Figure  10:  $substring() filter

You cannot use the $substring() filter with multi-column sensors.

Use the in operator for filtering

You can use the in operator to specify a collection of matching sensor results. The operator takes a comma-separated list of arguments that is parsed into a Boolean OR.

The following example uses the in operator to match a sensor filter in the from clause with results containing Virtual or Physical.

Figure  11:  in operator in the from clause

The following example uses the in operator to match a sensor column filter in the from clause. The question syntax is:

Get Computer Name and Installed Applications having Installed Applications:Name contains Adobe Reader from all machines with Installed Applications:Name contains Adobe Reader and Installed Applications:Version in(9.5.0,11.0.06)

Figure  12:  in operator with a sensor column filter

Use nested filters

In the from clause of a question, you can configure multiple filters, including nested filters.

The following example shows nested filters in the Question Builder. The example combines one matching expression with either one of the nested expressions.

Figure  13:  Nested filters in the Question Builder

You can also specify nested filters in the Ask a Question field.

Figure  14:  Nested filters in the Ask a Question field

The following example shows different Boolean logic: match both of these OR this one.

Figure  15:  Nested filters in the Ask a Question field

Target random endpoints

Use the Online Random Sample sensor to identify a random subset of online endpoints from all targeted endpoints. You might want to target random endpoints when you test a new package or configuration on a random subset of endpoints, or to check a random set of endpoints to ensure they have proper configurations prior to an audit. The Online Random Sample sensor is included in the Default Content pack.

The Online Random Sample sensor retrieves True and False results from all targeted endpoints. The sensor accepts a Sample % parameter from 0-100 to determine the rough percentage of endpoints that answer with True. For example, if you pass 25 as a parameter and target from all machines, approximately 25% of endpoints in the environment will return a True response. Because each endpoint evaluates the sensor and generates a random True or False answer according to the percentage that you specify, the number of endpoints that return True can vary. The default value for Sample % is 5.

Figure  16:  Online Random Sample sensor

Use advanced sensor options

Question results from Tanium Clients must conform with any advanced options that you specify for sensors in the question. You can configure advanced sensor options in the Question Builder (see Figure  17) or in the Ask a Question field (see the examples after Table 1).

Figure  17:  Question Builder: Advanced sensor options

The following table describes the advanced sensor options:

 Table 1: Advanced sensor options
Option Guidelines
Case Sensitivity Select whether Interact factors in upper-case and lower-case characters when grouping and counting question results:
  • Ignore case
  • Match case

See Example: Case Sensitivity.

Matching This option is available only in the from computers with section of the Question Builder, which corresponds to the from clause of a question in the Ask a Question field.

A Tanium Client might compute multiple results for certain sensors. For example, a client that has multiple interfaces returns multiple results for the IP Address sensor. You can use the Matching option as a filter such that a client answers the question only if its results conform to your selection:

  • Match Any Value: The client returns results if any of its results match the value that is specified in the question.
  • Match All Values: The client returns results only if all its results match the value that is specified in the question.

See Example: Matching.

Treat Data As Interact treats sensor values as the type of data that you specify. For a descriptions of the data types, see Tanium Console User Guide: Result Type. For an example, see Example: Treat data as type.
Maximum Data Age

Specify the maximum time for which the Tanium Client can use a cached result for the sensor, instead of reexecuting it for a fresh result, when answering questions. For example, you might specify 15 minutes for the File Size sensor. When a client receives a question that executes the File Size sensor, it caches the result. Over the next 15 minutes, if the client receives another question with the File Size sensor, it returns the cached result. After 15 minutes, if the client receives a question with the File Size sensor, it reexecutes the sensor script to return a fresh result. For an example, see Example: Maximum Data Age.

To improve the accuracy of results, use shorter ages for sensors with values that change frequently, such as status and utilization sensors. To reduce unnecessary CPU usage on endpoints, use longer ages for sensors with values that typically do not change frequently, such as the chassis type or Active Directory domain membership.

If you omit the Maximum Data Age, the Max Sensor Age setting in the sensor configuration determines the maximum time for cached results. See Tanium Console User Guide: Max Sensor Age.

Specify a Maximum Data Age only when issuing dynamic questions, not when creating saved questions or configuring endpoint membership in computer management groups and filter groups. Setting a Maximum Data Age that is lower than the Max Sensor Age increases CPU usage on endpoints.

The following examples describe how to enter advanced sensor options in the Ask a Question field using the syntax <sensor>?<option>=<value>.

Example: Treat data as type

The syntax for filtering by data type is <sensor>?type=<type>. The following example specifies Numeric as the type.

Figure  18:  Advanced Sensor Options: Treat Data as Numeric

The File Size data type in the Question Builder corresponds to the DataSize type in the Ask a Question field, where the syntax is <sensor>?type=DataSize. The following example returns results from endpoints where the installation folder of the Tanium Client is at least 10 GB.

Figure  19:  Advanced Sensor Options: Treat Data as File Size

Use the Treat Data as <type> option only with comparison operators, such as Free Memory > 300.

Example: Maximum Data Age

The syntax for setting the Maximum Data Age for cached results is <sensor>?maxAge=<value>. In the Question Builder, you can specify the age units (minutes, hours, days). In the Ask a Question field, the age is always in seconds. The following example specifies a maximum age of 3600 seconds.

Figure  20:  Advanced Sensor Options: Maximum Data Age

Example: Case Sensitivity

The Case Sensitivity option in the Question Builder corresponds to the ignoreCase option in the Ask a Question field, where the syntax is <sensor>?ignoreCase=[0|1]. The value 0 means match the case and the value 1 means ignore the case for sensor results with letters. The following example specifies the Case Sensitivity option with a value set to Ignore Case.

Figure  21:  Advanced Sensor Options: ignore case

Example: Matching

This Matching option applies only in the from clause of a question. The syntax for matching all or any results for a sensor is with [all] <sensor> contains <value>, where omitting the all option specifies Match Any Value. In the following example, the Matching option is set to Match All Values (with all) for the IP Address sensor. This example addresses a case where each endpoint might have multiple interfaces and you want to return results only from endpoints on which all the interfaces have an IP address that contains the string 192.

Figure  22:  Advanced Sensor Options: match all

Example: Multiple options

To specify multiple advanced options for a sensor, separate each option with an ampersand &. The syntax is <sensor>?<option 1>=<value>&<option 2>=<value>...&<option N>=<value>. The following example shows a question with two options for the Installed Applications sensor:

Figure  23:  Advanced sensor options - multiple options

Use advanced question options

Enable the Force Computer ID option to convert a single-sensor, counting question into a non-counting question by forcing Tanium Clients to include the computer ID in their answers. Note that the Question Results page does not include the computer ID results when you select this option. Converting to a non-counting question is a workaround that resolves cases where a counting question returns the too many results answer. For details, see Enable or disable live updates. You can enable the option in the Ask a Question field by using the Get?forceComputerIdFlag=1 statement. You can also enable the option in the Question Builder, under Advanced Question Options.