Reference: Advanced question syntax

Use question filters

You can add filters to the get clause and from clause of a question:

  • get clause: The get clause specifies the sensors that Tanium Clients run to answer the question. Tanium CloudThe Tanium Server processes the filters after receiving the answers. Tanium Console then shows the filtered answers in the Question Results page. For example, the statement Get Running Processes contains chrome filters the Running Processes sensor to show processes with names that contain the string chrome on endpoints. Endpoints that do not match the filter return the answer [no results].

    Filter in get clause

  • from clause: The from clause specifies whether the question targets all Tanium Clients (from all machines) or only clients that evaluate the filtering sensor to a Boolean true. For example, the question Get Running Processes from all machines with CPU Consumption > 80% returns the names of all running processes on endpoints where CPU consumption exceeds 80%.

    Filter in from clause

    You also use filters to define the dynamic membership of computer management groups and filter groups. See Computer group membership.

    For more details on from clause filters, see Questions with target filters.

Use a combination of get and from filters in a question if you want the Question Results page to exclude endpoints that return [no results]. For example, the following question shows processes with names that contain the string chrome but only on endpoints that have at least one process name with that string.

Filter in get and from clauses

Filter expressions can match strings or regular expressions. The following table describes the supported filter operators as they appear when you use the Interact Question Builder. The table also describes how some operators are normalized after you enter the expressions in the Ask a Question field or issue a question from the Question Builder.

If you use operator words as string literals instead of as filters in question text, you must enclose the words in quotation marks. See Use reserved words or characters.

 Table 1: Filter operators
Filter operator Usage
contains The sensor value contains the specified string.

Example: running processes contains "chrome"

does not contain The sensor value does not contain the specified string.
starts with The sensor value starts with the specified string.

Example: starts with "chrome"

When you issue the question, the expression is translated to a regular expression using the matches operator.

does not start with The sensor value does not start with the specified string.
ends with The sensor value ends with the specified string.

Example: ends with "chrome.exe"

When you issue the question, the expression is translated to a regular expression using the matches operator.

does not end with The sensor value does not end with the specified string.
matches

The sensor value matches the specified regular expression in Boost syntax. For details, see Use regular expression filters.

For sensors in the get clause of a question, use the matches operator to match any value in a list. In the Ask a Question field, enclose the values in quotation marks and parentheses "( )", and use the pipe character | as a separator. In the Question Builder, you can skip the quotation marks; Interact adds them automatically when you issue the question. For example, the following question matches the user names root or reboot:

Get Last Logged In User matches "(root|reboot)" from all machines

In the from clause of a question, you can also use the in operator to match values in a list.

does not match

The sensor value does not match the specified regular expression.

When you issue the question, the expression shown in the question field uses not matches in place of does not match.

in (from clause only)

The sensor value is equal to one of the specified strings. Enclose the values in parentheses and use commas as separators.

When you issue the question, the question field shows the expression with equals in place of in and with or in place of commas.

Example: the filter with Chassis Type in (Virtual,Physical) in the Ask a Question field becomes with (Chassis Type equals Virtual or Chassis Type equals Physical) when you issue the question.

For details, see Use the in operator for filtering.

In the get clause of a question, the in operator is not available but you can use the matches operator instead.

is equal to

The sensor value is equal to the specified value or string.

When you issue the question, the expression shown in the question field uses equals in place of is equal to.

is not equal to

The sensor value is not equal to the specified value or string.

When you issue the question, the expression shown in the question field uses not equals in place of is not equal to.

is less than

The sensor value is less than the specified value.

When you issue the question, the expression shown in the question field uses a symbol (<) in place of the operator words.

Example: installed application version[chrome] < 12

is less than or equal to

The sensor value is less than or equal to the specified string.

When you issue the question, the expression shown in the question field uses symbols (<=) in place of the operator words.

Example: installed application version[chrome] <= 12

is greater than

The sensor value is greater than the specified value.

When you issue the question, the expression shown in the question field uses a symbol (>) in place of the operator words.

Example: installed application version[chrome] > 12

is greater than or equal to

The sensor value is greater than or equal to the specified string.

When you issue the question, the expression shown in the question field uses symbols (>=) in place of the operator words.

Example: installed application version[chrome] >= 12

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

Tanium questions support regular expression matching based on Boost syntax.

Example: Match a starting character

The following example matches computer names that begin with the letter q in the domain tanium.com.

Figure  3:  Matching a regular expression

Example: Match any digit

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

Example: Negation

You can also use a combination of negation and regular expressions to build filter expressions. For example, the predefined computer group No Computers has a membership definition that 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 dynamic (filter-defined) membership, the question parser converts the specified computer group name into the question that determines membership. See Computer group 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 (see Split into multiple columns) 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

In a multi-column sensor, the $substring() filter applies across all the columns. You cannot apply the $substring() filter to a specific column.

Use the in operator for filtering

In the from clause of a question, use the in operator to specify a collection of matching sensor results. The in operator applies the is equal to operator (see Filter operators) to any value in a comma-separated list that you enclose in parentheses. After you issue the question, the question field shows the expression with equals in place of in and with a Boolean or in place of commas.

In the get clause of a question, the in operator is not available but you can use the matches operator instead. See matches.

The following example shows the in operator applied to results containing Virtual or Physical.

Figure  11:  Question with in operator

The following example shows the question syntax after you issue the question.

Figure  12:  Issued question with in operator

The following question applies the in operator to values (115.0.1901.188 or 115.0.1901.200) in a specific column (Version) of the multi-column sensor (Installed Applications):

Get Installed Applications having Installed Applications:Name equals Microsoft Edge from all machines with ( Installed Applications:Name equals Microsoft Edge and Installed Applications:Version?type=Version in (115.0.1901.188,115.0.1901.200 ) )

Figure  13:  Question with in operator applied to a sensor column filter

After you issue the question, its syntax changes to:

Get Installed Applications having Installed Applications:Name equals Microsoft Edge from all machines with ( Installed Applications:Name equals Microsoft Edge and ( Installed Applications:Version?type=Version equals 115.0.1901.188 or Installed Applications:Version?type=Version equals 115.0.1901.200 ) )

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  14:  Nested filters in the Question Builder

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

Figure  15:  Nested filters in the Ask a Question field

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

Figure  16:  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 content-only solution Default Content.

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  17:  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  18) or in the Ask a Question field (see the examples after Table 2).

Figure  18:  Question Builder: Advanced sensor options

The following table describes the advanced sensor options:

 Table 2: 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 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 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  19:  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  20:  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  21:  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  22:  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  23:  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  24:  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.