Example: Parameterized packages

Parameterized packages prompt you to specify values for command-line parameters when deploying actions. For example, when you deploy an action that uses the Tanium-provided Registry - Set Value package, the Action Deployment page prompts you to enter the Registry Key Name and other key value parameters.

Figure  1:  Parameterized package

If you configure the action for periodic redeployment, it becomes a scheduled action. When a scheduled action is based on a parameterized package, the package definition, including the substituted values, is saved in an object called a temporary package. On the endpoint, the Tanium Client runs the temporary package when it has a directive to run the scheduled action that calls it. A scheduled action continues to use the temporary package even if the package from which it was based is updated. Therefore, if a package is updated, and you want the scheduled action to use the updated code, you must re-issue or edit the scheduled action and click the Update Source Package option for the Deployment Package setting.

Package script and command-line parameters

When you configure a parameterized package (see Create a package), the Command specifies a script. The parameters that are coded in the script and the order in which values are specified during action deployment are aligned according to position, not number. In the following example, the script parameters are numbers 0 through 4.

Figure  2:  set-value.vbs script parameters

The command-line parameters are numbered $1 through $5.

Figure  3:  Command-line parameters (click image to enlarge)

Tanium Cloud The Tanium Server encodes parameter data before passing it to the underlying script and the data must have UTF-8 decoding applied before use. The VB script for the Registry - Set Value example in Figure  2 uses an @include to the i18n/UTF8Decode.vbs script. This script ensures that user input in the Tanium Console form is properly encoded when passed to the package script.

'- Begin file: i18n/UTF8Decode.vbs
' UTF8Decode
' Used to convert the UTF-8 style parameters passed from 
' the server to sensors in sensor parameters.
' This function should be used to safely pass non english input to sensors.
Function UTF8Decode(str)
    Dim arraylist(), strLen, i, sT, val, depth, sR
    Dim arraysize
    arraysize = 0
    strLen = Len(str)
    for i = 1 to strLen
        sT = mid(str, i, 1)
        if sT = "%" then
            if i + 2 <= strLen then
                Redim Preserve arraylist(arraysize + 1)
                arraylist(arraysize) = cbyte("&H" & mid(str, i + 1, 2))
                arraysize = arraysize + 1
                i = i + 2
            end if
            Redim Preserve arraylist(arraysize + 1)
            arraylist(arraysize) = asc(sT)
            arraysize = arraysize + 1
        end if
    depth = 0
    for i = 0 to arraysize - 1
		Dim mybyte
        mybyte = arraylist(i)
        if mybyte and &h80 then
            if (mybyte and &h40) = 0 then
                if depth = 0 then
                    Err.Raise 5
                end if
                val = val * 2 ^ 6 + (mybyte and &h3f)
                depth = depth - 1
                if depth = 0 then
                    sR = sR & chrw(val)
                    val = 0
                end if
            elseif (mybyte and &h20) = 0 then
                if depth > 0 then Err.Raise 5
                val = mybyte and &h1f
                depth = 1
            elseif (mybyte and &h10) = 0 then
                if depth > 0 then Err.Raise 5
                val = mybyte and &h0f
                depth = 2
                Err.Raise 5
            end if
            if depth > 0 then Err.Raise 5
            sR = sR & chrw(mybyte)
        end if
    if depth > 0 then Err.Raise 5
    UTF8Decode = sR
End Function
'- End file: i18n/UTF8Decode.vbs

In shell scripts, you can use a function similar to the following to decode the parameter data:


percent_decode() {
        local data=$(echo "$1" | sed 's/%/\\\x/g')
        /usr/bin/printf '%b' "$data"

myVariable=`percent_decode "||parameter_value||"`

The printf utility might not be available or might not work correctly on all Linux, macOS, and UNIX platforms. A more fool-proof but less elegant implementation is:


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||"`

Parameter input settings

Parameter Inputs that you specify in the package configuration determine the settings that the Tanium Console prompts users to configure upon deploying an action that uses the package. Add one parameter at a time. The first one you add is matched to the command line variable $1, the second is matched to variable $2, and so on.

You can select and drag to rearrange the items in the Parameter Inputs list that appears in the navigation menu on the left side of the form. Be sure the final order lines up with the numbered parameters in the command.

Figure  4:  Parameter input settings (click image to enlarge)

The most common widget for user input is a text box, but you can select any of the following options. For the List, Text Area, and Text Input widgets, you can add Validation Expressions to define the allowed values. The expressions are based on Perl Compatible Regular Expressions (PCRE). Boolean AND logic applies if you add fields for multiple expressions. You can apply Boolean OR logic to multiple expressions by entering them as a single field entry with vertical bars "|" as separators. Each expression field has an adjacent text box where you can enter a description to help users understand the expression. For example, if the expression is \S{5}, you might enter the help text Value must be at least 5 characters.

Include validation for input parameters in the script, not just in Validation Expressions.

Because it is the Tanium Console that validates expressions, not the Tanium Server, the validation does not apply to custom packages that you import or that you create through the Tanium API.

  • 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: The user selects only one item 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 Step Size value should be a multiple of the Snap Interval value 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.
  • Separator: A separator is a graphical way to separate sections in the user input form.
  • Text Area: User enters a large amount of text, which is entered into the variable.
  • Text Input: User enters text, which is entered into the variable.
  • Time: User selects a time from a dropdown list. The input can be subject to restrictions.

Most parameter types provide Options for specifying read-only values that help users understand how to configure the parameters when deploying an action. The following example shows the read-only values that you can specify for Text Input. The Preview section shows how the settings appear to users who deploy an action that uses the package.

Figure  5:  Parameter options
Read-only values

Note that the Provide Help Text content appears as a tooltip when a user hovers over Information Info:

Figure  6:  Provide Help Text
Provide Help Text