Managing sensors

Sensors overview

A sensor is a script that runs on an endpoint to compute a response to a Tanium question. The Tanium Server distributes sensors to endpoints during Tanium Client registration. Sensors enable you to ask questions that collect information such as the following:

  • Hardware and software inventory and configuration
  • Running applications and processes
  • Files and directories
  • Network connections

The installation process for the Tanium Server automatically imports the Default Content pack that includes sensors for a wide range of common questions. Other Tanium solutions that you import might add more sensors, depending on which Tanium content packs or Tanium solution modules you import. If you cannot find a sensor you need within Tanium-provided content, you can create custom sensors.

A sensor configuration includes settings, script content, and script parameters. Sensors use industry-standard scripting languages rather than proprietary coding syntax. The best practice is for sensors to use the scripting engine available on the largest number of managed endpoints. On Windows endpoints, VBScript typically provides the most comprehensive out-of-the-box coverage because it is installed by default in every desktop release of Microsoft Windows since Windows 98 and in every Windows Server release since Windows NT 4.0 Option Pack. On macOS and Linux endpoints, shell script generally provides the most comprehensive out-of-the-box coverage. Of course, you can develop sensors using any other scripting language that the operating system supports (such as PowerShell on Windows), as long as the associated scripting engine already exists on the endpoint, or you can deploy and configure the engine on the endpoints that do not have it installed. You cannot edit the configurations of Tanium reserved sensors, which are core system sensors that include Computer Name, Action Statuses, Computer ID, and Download Statuses.

For the role permissions required to manage sensors, see Content management permissions.

View sensor configurations and runtime metrics

To see sensor configuration settings and runtime metrics:

  1. Go to Content > Sensors.

    To help you assess the impact that sensors have on endpoint resources, the top of the page displays Sensor Runtime Metrics. For each runtime threshold, the metrics indicate the number of sensors that exceeded it, the average runtime for those sensors, and the maximum runtime for any of those sensors. The Overall metrics indicate the average and fastest runtimes among all the sensors. For details and tasks related to runtime thresholds and indicators, see Managing question and sensor thresholds.

    Below the runtime metrics, the grid shows the configuration settings of each sensor.

  2. (Optional) Use the text field above the grid to filter by sensor name or use the Filter Results options to filter by Runtime thresholds, Content Set, Category (such as module, tags, or SQL), and user (Modified by). You can also click the Sensor Runtime Metrics to filter the grid based on sensors that exceeded the High, Medium, or Low runtime thresholds.

Edit a sensor

As a best practice, do not edit predefined sensors that are provided through content packs imported from Tanium. For details, see Tip 4: Limit customizations to Tanium content. Consult your Technical Account Manager (TAM) if editing the Tanium-provided sensors is necessary. Alternatively, you can clone Tanium-provided sensors (see Clone a sensor) and edit the copies. You can also edit custom sensors that you created from scratch. To edit a sensor:

  1. Go to Content > Sensors.
  2. Use the search and column sorting features to find the sensor that you want to edit.
  3. Select the sensor row, click Edit, and configure the settings described in Table 1.
  4. Save your changes.

Move sensors between content sets

You can move sensors between content sets as necessary to accommodate changes to the role-based access control (RBAC) configuration of your Tanium deployment. For example, you might want to move certain sensors to a content set that only highly privileged users can access.

  1. Go to Content > Sensors.
  2. Use the search and column sorting features to find the sensor that you want to move.
  3. Select the sensor row and select Move to Content Set > <content_set_name>.

Clone a sensor

Cloning is useful when you need to:

  • Create a modified version of a predefined sensor from a Tanium content pack. As a best practice, do not modify the original Tanium sensor.
  • Create a new sensor with settings that differ only slightly from an existing sensor; this is often easier than creating a new sensor from scratch.

Perform the following steps to clone a sensor:

  1. Go to Content > Sensors.
  2. Use the search and column sorting features to find the sensor that you want to clone.
  3. Select the sensor row, click Clone, and configure the settings as described in Table 1.
  4. Save your changes.

Create a sensor

  1. Go to Content > Sensors.
  2. Click New Sensor and complete the configuration as described in Table 1.
  3. Save the configuration.
Table 1:   Sensor configuration guidelines
Settings Guidelines
Name Specify a configuration name. The name appears in sensors lists on the Tanium Console. Observe the existing naming scheme so that you and other administrators can find it easily. Do not use an underscore character (_), which is a delimiter for sensor sub-columns. If the sensor name has an underscore, sensor-sourced packages cannot use the sensor as a sensor variable.

Important: If you change the sensor name, be sure to reconfigure content that references it. For example, you must update the sensor name in any saved questions that are configured with the previous name.

Description Enter a description. Include examples of formatted results. The description appears in the Sensors page and in the Browse Sensors dialog of the Question Builder.
Content Set Assign to a content set. The list is populated with all content sets for which you have Write Sensor permission.
Category Specify one of the categories that appears on the Sensors page and in the Browse Sensors dialog of the Question Builder.
Result Type The Question Results grid treats values that the sensor returns as the type of data you specify:
  • Date/Time (RFC822)
  • Date/Time (WMI)
  • File Size
  • Integer
  • IP Address
  • Numeric
  • Text
  • Time Duration
  • Version
Max Age Enter the maximum time for which the Tanium Client can use a cached result for this sensor when answering questions that use the sensor. For example, the maximum data age for the File Size sensor is 15 minutes by default. When a Tanium Client receives a question that executes the File Size sensor, it caches the result. Over the next 15 minutes, if the Tanium Client receives a question that includes the File Size sensor, it responds with the cached answer. After 15 minutes, if the Tanium Client receives a question that includes the File Size sensor, it executes the sensor script again to compute a fresh answer.

Use shorter ages for sensors that return values that change frequently, such as status and utilization sensors. Use longer ages for values that typically change infrequently, such as the chassis type or Active Directory domain membership.

Max Strings If you want to reduce the impact that question results have on Tanium Server disk space, select Enable and enter the maximum number of answer strings that the server stores for this sensor before removing the oldest strings. The server includes the string count for temporary sensors when calculating the string count for their source sensors. The default is 0, which specifies no limit. The string age is based on when the Tanium Server last used the string or received it from Tanium Clients.

Important: When limiting string growth, the best practice is to set the Max Strings Age instead of the Max Strings (see Manage sensor string growth). In extreme cases that might require a string count limit for individual sensors, consult your TAM before setting the Max Strings.

Max Strings Age If you want to reduce the impact that question results have on Tanium Server disk space, select Enable and specify the maximum age that answer strings can reach before the server removes them. The default is one week. The string age is based on the number of minutes since the Tanium Server last used the string or received it from Tanium Clients. For details, see Manage sensor string growth.
Ignore case in result values Group and count result values regardless of differences in upper-case and lower-case characters.
Hide this sensor from sensor lists and parse results Select this option if you want sensor lists throughout the user interface to exclude the object.
Split into multiple columns using delimiter (Multi-column sensors only) If the sensor script returns multiple results, display them in multiple columns on the Question Results grid. Specify the delimiter character used to separate result values in the script. Enter column names and corresponding result types, and arrange them in the order you want them displayed in the results grid. Select the Hide option to hide the column from the default view of the results grid. The following figure shows the settings for the Running Applications sensor.

Multi-column sensor settings

Note: When creating questions that filter multi-column sensors, single-column filtering works only if the sensor definition specifies column delimiters with a single character (such as |), not multiple characters (such as |:).

Scripts For each target platform:
  1. Click + to add a target platform.
  2. Set the Query Type to the desired scripting engine.
  3. Paste in script text.
Parameter Inputs (Parameterized sensors only) Click + and then Add Parameter to configure a parameter. Options include:
  • Checkbox—User enables a setting by checking a box. 0 or 1 is entered into the variable. Returns 1 if checked and 0 if not checked.
  • Date, Date Time, Date Time Range—User selects a date and time or a range. The date time format is epoch with milliseconds. For a range, the user specifies two date times separated by a pipe.
  • Drop Down List—User selects only one option from a list.
  • List—User selects one or more values. Multiple values are separated by a pipe.
  • Numeric—User enters a number. The input can be controlled with minimum and maximums. You can specify a Step Size to require that the input be divisible by the specified value. Snap Interval is the amount that a number is increased or decreased by pressing the up or down button respectively. The value for Step Size should be a multiple of the value for Snap Interval unless Snap Interval is 0. The user-selected number is entered into the variable.
  • Numeric Interval—User selects a number and an item from a list. The list item has a numeric value. The value entered into the variable is the result of the multiplication. For example, if a user selects 2 and selects High (with high having a value of 3), the value is 6 in the variable.
  • Plugin—Not intended for use by most users. Contact your TAM for additional information about its use.
  • Separator—A separator is a graphical way to separate sections in the user input form.
  • Text Area—User enters a large amount of text. The text is entered into the variable.
  • Text Input—User enters text input. Allowed entries can be controlled with regular expressions. The user input is entered into the variable.
  • Time—User selects a time from a drop-down list. The input can be subject to restrictions.
Sensor Preview Select a computer group or click Add to build one and then click Preview to see test results for the sensor.

Import or export a sensor configuration

As a best practice, develop and test content in your lab environment before distributing it to your production servers. The Tanium Console import and export features support this practice.

Export specific sensors

  1. Go to Content > Sensors.
  2. Select one or more sensors and click Export in the toolbar above the table header.
  3. Enter a File Name or accept the default, and then click OK. The Tanium Server exports the content file to the Downloads folder on the system you use to access the Tanium Console.

Export the complete sensors configuration

  1. Go to Content > Sensors and click Export All in the table header.

    Alternatively, or if you want to export other configuration objects in addition to sensors, go to any Content or Permissions page, click Export Content in the top right of the Tanium Console, select Sensors and any other object types, select the Export Format (JSON or XML), and click Export.

  2. Enter a File Name or accept the default, and then click OK. The Tanium Server exports the content file to the Downloads folder on the system you use to access the Tanium Console.

Import a sensors configuration

You can import files that are in JSON or XML format.

  1. Digitally sign the content file and ensure a public key is in place to validate the signature, as described under Authenticating content files.
  2. Go to any Content or Permissions page and click Import Content at the top right of the page.
  3. Click Choose File, find and select the configuration file, and click Open.
  4. Click Import. If object names in the file are the same as for existing objects, the Tanium Console itemizes the conflicts and provides resolution options for each one.
  5. Select resolutions for any conflicts. For guidance, see Conflicts and Best practices, or consult your TAM.
  6. Click Import again, and click Close when the import finishes.

Manage sensor quarantines

Tanium Client 7.2 or later supports sensor quarantines which, when enforced, prevent a sensor from running for the current question or action if that sensor exceeded the runtime timeout during a previous question or action. Enforcing quarantines is useful for limiting the impact on endpoint resources, such as CPU utilization, when questions and actions use excessively long-running sensors. The non-configurable timeout is set to one minute. By default, quarantines are not enforced: after a sensor exceeds the timeout and stops running, the sensor will have quarantined status but will still run for future questions or actions until it completes or times out. In this case, the Tanium Client uses the quarantined status just to record that the sensor timed out. Regardless of whether you enable enforcement, the Tanium Client stops any sensor at the moment it exceeds the timeout. You can enable or disable quarantine enforcement for all clients through a global setting. However, each client quarantines sensors and enforces the quarantines independently, so a sensor might be quarantined on some machines and not on others.

When a Tanium Client quarantines a sensor, the Tanium Console displays the following message in the Question Results grid: TSE-Error: Sensor evaluation timed out. When you issue a question that uses a sensor that is already quarantined and enforcement is enabled, the Question Results grid displays TSE-Error: The sensor is quarantined. The Tanium Client adds entries to the client logs and sensor history logs when it quarantines a sensor or prevents an already quarantined sensor from running.

If temporary sensors exceed the one-minute timeout, the Tanium Client quarantines the original sensor as well as all current and future temporary sensors that are based on the original sensor.

When enforcement is enabled, quarantined sensors do not run when used for targeting endpoints, regardless of whether the sensors are contained in computer groups. However, quarantined sensors might skew the targeting of a question that has a vague from clause, such as from all machines with Is Windows not equals true. In this case, Windows endpoints on which the Is Windows sensor is quarantined would match the condition not equals true because their response would be TSE-Error: The sensor is quarantined rather than true. As a best practice to avoid such outcomes, make the target clause as specific as possible and do not use negative matching conditions such as not equals true.

View quarantined sensors

Go to Content > Sensors > Quarantined Sensors to see details about the sensors that have quarantined status. The page displays the same Sensor Runtime Metrics and filtering options as the Sensor Management page (see View sensor configurations and runtime metrics).

Add a sensor to quarantine

You can manually quarantine a sensor on an endpoint if you anticipate that running the sensor will negatively affect the endpoint.

Quarantining a sensor does not automatically enable quarantine enforcement; only the EnableSensorQuarantine global setting controls enforcement.

  1. In the URL field of the browser that you use to access the Tanium Console, enter https://<Tanium_Server>/hash/<sensor>. For the <Tanium_Server>, enter the FQDN or IP address of the Tanium Server. The <sensor> must match the sensor name that the Tanium Console displays with respect to capitalization and spaces.

    The browser displays the hash value associated with the sensor.

  2. Access the operating system CLI on the endpoint and change directory (cd) to the Tanium Client installation folder.
  3. Enter the following command.

    TaniumClient quarantine add <sensor_hash>

Remove sensors from quarantine

You can use the Tanium Console to unquarantine a sensor on some or all endpoints if you imported Default Content (previously Initial Content - Base) version or later (see Manage Tanium content packs). After you unquarantine a sensor, the Tanium Client allows it to run for subsequent questions and actions, but will stop and quarantine the sensor again if it exceeds the timeout.

If you modify a sensor, Tanium Clients that receive its new definition will automatically unquarantine that sensor.

The Tanium Server cannot unquarantine sensors on endpoints that are offline. If you know that some endpoints might come online only at a later time, consider scheduling an action that uses the Un-Quarantine Sensor or Un-Quarantine Sensor (Non-Windows) package (see Deploying actions).

  1. Go to Content > Sensors > Quarantined Sensors.
  2. Select the sensors and click Unquarantine.
  3. Select the Action Group that includes the endpoints where you want to unquarantine the sensors.
  4. Preview the affected endpoints and then click Unquarantine.

Enable or disable enforcement of quarantined sensors

After you enable quarantine enforcement, Tanium Clients do not answer questions that use quarantined sensors and those sensors do not run for actions. After you disable enforcement, clients still quarantine sensors and log quarantine events, but do not prevent those sensors from running.

Your user account must have a role with the Write Global Settings (micro admin) permission to enable or disable quarantine enforcement. Users with the Administrator reserved role have this permission.

The first time you enable enforcement, you must add the EnableSensorQuarantine setting to the global settings on the Tanium Server as follows. By default, enforcement is disabled and the setting does not appear in the Tanium Console. After you add the setting, the Tanium Server applies it to all Tanium Clients.

  1. Access the Tanium Console, go to Administration > Global Settings, and click New Setting.
  2. Enter the following values and click Save.
    • Setting Name = EnableSensorQuarantine
    • Setting Value = 1
    • Affects = Client
    • Value Type = Numeric

Perform the following steps if you want to change the enforcement setting after adding it to the global settings:

  1. Go to Administration > Global Settings.
  2. Select EnableSensorQuarantine, click Edit, set the value to 1 to enable enforcement or 0 to disable enforcement, and click Save.

If you want to change the enforcement setting in specific Tanium Clients instead of all clients, add or edit the EnableSensorQuarantine setting in the local configuration of those clients (see Tanium Client User Guide: Tanium Client settings).