Tanium 6.x: Sensor Authoring

Introduction

A Tanium Sensor plays one of the most important roles in enabling an organization to gather real-time inventory, configuration, and compliance data elements from managed computers across hundreds of thousands of geographically distributed devices within seconds. A compact, efficient script, a Sensor gathers specific information from the local device and then writes the results to the computer's standard output channel. The Tanium Client captures that output and forwards the results through the platform's unique "ring" architecture within seconds for display in the Tanium Console:

SensorAuthoringAnswersOnly.png

Based on the context of the question entered by the user—even with a misspelling—the console's natural language parser presents a set of properly formatted questions that include the Sensor(s) most likely to provide the desired results:


After the console user selects the desired query, the Tanium Server formats the question into a message which the Tanium Client within each ring designated as the "Leader" gathers. Upon receipt, the client executes the Sensor(s) named in the question on the local endpoint. The client converts the result to a hash value and then forwards the compressed results to the next device in the ring—with the last client sending a single, optimized message that includes all results back to the console for display:

SensorAuthoringQuestionAndAnswer.png

A key advantage of Tanium over other software used to gather configuration and compliance details from managed computers is the ease and speed at which an authorized Tanium Console operator can extend the solution beyond the hundreds of out-of-the-box Sensors to report new information from machines by creating Sensors using familiar, industry-standard scripting languages rather then arcane, proprietary coding syntax. Ideally, the language of choice for Sensor development is based on the scripting engine available on the largest number of devices under management as well as the scripting experience and background of the people who will be responsible for creating new Sensors. For computers running a Microsoft Windows operating system, VBScript typically provides the most comprehensive "out-of-the-box" coverage since it has been installed by default in every desktop release of Microsoft Windows since Windows 98 and in Windows Server since Windows NT 4.0 Option Pack.

Of course, any other scripting language the Microsoft Windows operating system supports, such as PowerShell, can also be used to develop Sensors, as long as the respective scripting engine already exists or can be deployed and configured on the systems that do not have it already installed. For example, PowerShell is part of many newer Microsoft operating systems, but it may require changes to the PowerShell Execution Policies on the target computers before any PowerShell scripts can be run on the endpoint successfully.

For computers running Mac OS X or a Linux operating system, using shell script generally provides the most comprehensive "out-of-the-box" coverage to support Sensor development. Again, Sensors can be developed using any Mac OS X or Linux supported scripting languages as long as the respective scripting engine already exists or can be deployed and configured on the systems that do not have it already installed.

Some Sensors cannot be edited. A Tanium "Reserved Sensor" is a core system Sensor whose code is not meant to be edited by clients. At this writing, Reserved Sensors include Computer Name, Action Statuses, Computer ID, Downloaded Statuses, and Manual Group Memberships. These sensors are used so often by the Tanium platform they are not designed to be edited by a customer. If a customer would like to create their own Sensor with the same functionality of a Reserved Sensor, a new Sensor can be created with a new name (e.g. "Customer - Computer Name").

Sensor development and management

From the Authoring->Sensors tab of the console, authorized console users can review the library of existing Sensors as well as create, edit, and delete Sensors. In addition, administrators can import shared Sensor XML files or export them for archival.

AuthoringSensorsTabDeleteEditCreateV3.png

Basic Sensor Authoring

To create a new Sensor, from the Authoring->Sensors click the "Add New Sensor" link located in the upper right corner of the console tab which launches the following input dialog:

AuthoringSensorsAddHelloWorldV2.png

Edit Sensor dialog box Input Fields

Name
Enter a value to uniquely identify each Sensor created.
Note: If you change the name of a sensor that another piece of content—e.g., a saved question, a saved question associated with a dashboard, as well as a saved question or action targeted in a scheduled action—references, be sure to update the content referring to those Sensors as a name mismatch generates errors in the related content.
Category
Associate the Sensor with a Category to make it easier for other console users to locate existing Sensors. Either select an existing category name from the list or create a new one by entering the desired category name.
Result Type
Select the appropriate Result Type to control the way Sensor result data is sorted within a Tanium Console Answer Grid.
When Answering Questions, ensure results are newer than
Specify the amount of time that must elapse before a Sensor’s code is re-run instead of a returning a cached result, if one is available. Use a short time duration for Sensors whose returned values change frequently, such as the current time on a client. Use longer time duration intervals for values that typically change infrequently, such as the computer's Active Directory Domain membership or the chassis type of the device.
Ignore case in result values
Enable this option to have the Console group and count result values regardless of differences in upper-case and lower-case characters.
Exclude result values when parsing questions
Enable this option for any Sensor that returns values that are unlikely to be used as part of a question. By default, the Tanium Server archives the unique result values gathered from the managed computers in response to a Sensor. This allows the natural language parser to determine the most likely Sensor to return a particular value when a console user enters a result value as part of a question rather than using a Sensor name. Enabling this option will improve parsing performance on questions overall.
Description
Document the purpose of the Sensor. Include examples of formatted results when possible
OS Platform Selector
Use the + button to add an additional Query Expression field for each Operating System for which a script will be included as part of the Sensor definition. Use the - button to remove the Query Expression field for any OS for which a script will not be part of the Sensor definition.
Query Type
Select the Scripting Engine intended to execute the script entered at the Query Expression field.
Query Expression
Key in or copy & paste the script for the respective platform selected under the OS Platform Selector.

Once the Sensor is saved in the Tanium Console, it is immediately available for use on all endpoints.

Upon receipt of a question such as "Get Hello World from all machines", the Tanium Client will execute the example Sensor, "Hello World". The associated script simply writes the words "Hello World" to the computer's standard output channel which is then captured by the client and forwarded through the ring to the Tanium Server for display in an Answer Grid within the Tanium Console:

AuthoringSensorsHelloWorldResultsTable.png


Any console user with at least the Sensor Author role can view the code to the default Sensors distributed with the Tanium server. Tanium encourages Sensor Authors to use out-of-the-box Sensor code as a basis for new Sensors which need to be created to solve specific problems in customer environments.

Advanced Sensor Authoring

Not only can an individual Sensor return more than one result from each computer, a Sensor can also be defined to accept console user input when a question is asked so that a single Sensor can be used to address a wider range of potential questions.

Multi-Column Sensors

A multi-column Sensor gathers a set of data elements from each computer rather than just a single property. A multi-column Sensor's script must add a delimiter between each property as it writes to the standard output channel. When the server display the results in the console, it will place each delimited value into a separate column. The following example illustrates how results from the multi-column Sensor CPU Details will be displayed: 

AuthoringSensorsMulti-columnSensor.png


The Sensor’s definition includes named column headers in a particular order, and the Sensor’s output contains a delimited set of values, in the same order as the column headers. When the Sensor is used in a question, the Answers Grid will use those headers: 

AuthoringSensorsCPUDetailsResults.png


Some multi-column Sensors may not display every retrieved property the client reports in the Answer Grid of the console. When the Sensor's output is used as dynamic input to a Package’s command line parameters, then all of the Sensor's output values may not be meaningful to include in the console display.

Parameterized Sensors

A Parameterized Sensor accepts input from the console user at the time a question is asked. For example, the "Registry Value Data" Sensor prompts the console user for the name of the registry key and associated key value for which the operator wants to see data:

AuthoringSensorsRegistryValueDataQuestion.png

Once the console operator clicks "ok", the console will substitute the data entered at the prompts into a properly formatted question, visible from the Ask a Question prompt, which will be targeted to the managed computers and the reported results displayed in an Answer Grid: 

AuthoringSensorsRegistryValueDataResult.png

Creating a new Sensor or adapting an existing Sensor to accept input from the console when asking a question requires two simple steps:

  1. Within the script that supports the Sensor, enclose any variables to be assigned a value with user input between a set of double-pipe symbols, parameter data is percent encoded by the console before it is passed to the underlying script and must be decoded before use. for example:
    '========================================
    ' Registry Value Data
    '========================================
    
    strKey = unescape("||strKey||")
    strValue = unescape("||strValue||")
    

    or in the case of shell scripts:

    #!/bin/sh
    
    percent_decode() {
            local data=$(echo "$1" | sed 's/%/\\\x/g')
            /usr/bin/printf '%b' "$data"
    }
    
    myVariable=`percent_decode "||parameter_value||"`

    NOTE: printf may not be available or work correctly on all varients of *nix and OS X. A more fool-proof but less elegant implementation is:

    #!/bin/sh 
    
    brute_force_percent_decode() {
            # decode everything between 0x20-0x7E except:
            #0 1 2 3 4 5 6 7 8 9 (0x30-0x39)
            #A B C D E F G H I J K L M N O P Q R S T U V W X Y Z (0x41-0x5A)
            #a b c d e f g h i j k l m n o p q r s t u v w x y z (0x61-0x7A)
            echo "$1" | sed -e 's/%20/ /g' \
            -e 's/%21/!/g' \
            -e 's/%22/"/g' \
            -e 's/%23/#/g' \
            -e 's/%24/$/g' \
            -e 's/%25/%/g' \
            -e 's/%26/\&/g' \
            -e "s/%27/'/g" \
            -e 's/%28/(/g' \
            -e 's/%29/)/g' \
            -e 's/%2[aA]/*/g' \
            -e 's/%2[bB]/+/g' \
            -e 's/%2[cC]/,/g' \
            -e 's/%2[dD]/-/g' \
            -e 's/%2[eE]/./g' \
            -e 's#%2[fF]#/#g' \
            -e 's/%3[aA]/:/g' \
            -e 's/%3[bB]/;/g' \
            -e 's/%3[cC]/</g' \
            -e 's/%3[dD]/=/g' \
            -e 's/%3[eE]/>/g' \
            -e 's/%3[fF]/?/g' \
            -e 's/%40/@/g' \
            -e 's/%5[bB]/[/g' \
            -e 's/%5[cC]/\\/g' \
            -e 's/%5[dD]/]/g' \
            -e 's/%5[eE]/^/g' \
            -e 's/%5[fF]/_/g' \
            -e 's/%60/`/g' \
            -e 's/%7[bB]/{/g' \
            -e 's/%7[cC]/|/g' \
            -e 's/%7[dD]/}/g' \
            -e 's/%7[eE]/-/g'
    }
    
    myVariable=`brute_force_percent_decode "||parameter_value||"`
    AuthoringSensorsParameters.png
  2. Click the "advanced settings" link to configure the prompt to be presented to the user.

    Any text entered into the Parameter Text field will be displayed to the end user literally while any text enclosed in a set of double-pipe symbols will appear as a text field for the user to enter data as shown in the image below:

    AuthoringSensorsCreatingPromptForParameters.png

Sensor Parameters

Several options are available for parameter inputs. The following table explains each option and what information is sent to the variable.

Data Input Description
Text Input Users can enter text input. Allowed entries can be controlled with regular expressions. The user input is entered into the variable.
Drop Down List Users can select only one option from a list. The value selected by the user is entered into the variable.
Check Box Users can enable a setting by checking a box. 0 or 1 is entered into the variable. Returns 1 if checked and 0 if not checked.
Numeric Users can enter a number. The input can be controlled with minimum and maximums. In addition Step Size will require that the input be divisible by the Step Size. Snap Interval is the amount that a number will be increased or decreased by pressing the up or down button respectively. Please note Step Size should be a multiple of Snap Interval unless Snap Interval is 0. The user selected number is entered into the variable.
Numeric Interval Allows a user to select 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 will be 6 in the variable.
Date Time Users can select a date and time. The date time format in epoch with milliseconds is entered into the variable.
Date Range Two date times in epoch with milliseconds is entered into the variable separated by a pipe.
List Users can select one or more values. The values selected are entered into the variable separated by a pipe.
Text Area Users can enter a large amount of text. The text is entered into the variable.
Plugin This is not intended for use by most customers. Please contact a Technical Account Manager for additional information about its use.
Separator A separator is a graphical way to separate sections. There is no input or output.

Please note that Max Characters set to 0 will allow unrestricted data input. Choosing the number 20 will limit the users to 20 characters.

Sensor Output as Package Input

This is really a Package authoring issue as much as a Sensor authoring issue. But as an example of using Sensor output as Package input, an operator can create a package that kills the task by name as reported by the Running Processes sensor. 

AuthoringSensorsKillPackageV2.png

This is a simple package that, when deployed, would kill the running process an operator has selected as a result of asking “Get Running Processes on all machines” across the enterprise, unless the question had a filter section such as “where organizational unit contains” or is drilled down into using another Saved Question such as “Workstations in Asia Pacific.”

Retrieving 64-bit Windows OS Registry and File System Data from within a 32-bit application

Because the Tanium Client is a 32-bit application, be sure to review the KB article describing Sensor "bitness" issues to better understand the impact that Microsoft Windows "redirection" and "reflection" have on a Sensor's script when executed on a computer running a 64-bit OS.

Troubleshooting

Please refer to the Troubleshooting Sensors page on the Tanium KB for details about Troubleshooting a new or modified Sensor.

Have more questions? Submit a request