Object Global table T

The global table named T can be accessed from anywhere. It defines some constants and utility functions.

Global Table T index

T.contextid A number that identifies the context of this lua script. You can have more than one instance of your script loaded see Threading
T.probeid A string that identifies the probe within the domain running this script, such as probe0
T.probeversion The version of the Trisul Probe running this script, such as 6.0.2779
T.args The -args command line option from trisul
T.enginetype A string backend or frontend – scripts may want to use this
T.host Host methods that can be called from LUA
T.K Constants
T.util Utility methods
T.async Methods to call async LUA functions out of fast packet path
T.re2 A fast and powerful regex engine (Google RE2)
T.ac A minimal but fast Aho-Corasick multi pattern matcher
T.log Function to log a message that goes into the main Trisul logging framework.
T.alertgroups Backend scripts only : A table of { alertgroup name, guid } currently loaded. Also see: Using T.alertgroups
T.countergroups A table of { countergroup name, guid } currently loaded. Only for backend scripts. For frontend scripts this field has a nil
T.resourcegroups Backend scripts only : A table of { resourcegroup name, guid } currently loaded.
T.ftsgroups Backend scripts only : A table of { FTS (Full Text Search) name, guid } currently loaded.
T.sessiongroups Backend scripts only : A table of { session group name, guid } currently loaded.
T.env Environment and Trisul Config file

Table T.host

Interact with the Trisul environment.

Use the object calling notation T.host:function(..) to invoke these methods.

Name In Out Description
get_homenets none Table, Array of [ string IP, string Netmask ] Get home networks defined by Trisul.
is_homenet number 32bit IPv4 or string IPv4 in dotted decimal bool Is the 32-bit IPv4 address within the home network?
get_configpath none string directory Configuration directory
get_datapath none string directory Data directory
createkey guid counter group id, string – key, string – label Create a userlabel for a given key. Use this to pre-load human labels for keys
prepare_config guid – plugin id, string template file plugin config Prepare a configuration file for your plugin
broadcast guid – message id, guid class id, string message none Broadcast a state update to other plugins

Table T.K

Pre-defined constants to use with other Lua functions.

loglevel Log levels EMERG, FATAL, ALERT, CRIT, ERROR, WARN, NOTICE, INFO, DEBUG Usage : print(T.K.loglevel.ERROR) => 4
vartypes Meter types COUNTER, RATE_COUNTER, GAUGE, RUNNING_COUNTER

Constants T.K.vartype

Constants : Types of counters.

This table defines counter types supported by Trisul. You typically use this table when creating custom countergroups

COUNTER Increment a counter that resets to zero at start of every time bucket
RATE_COUNTER Equal to COUNTER / Bucket Size in seconds
GAUGE Instantaneous values
RUNNING_COUNTER Increment or decrement a counter, does not reset every time bucket
AVERAGE Average of all samples in the window.
DELTA_RATE_COUNTER Delta counter per second. Use this for SNMP like samples that represent a running counter but when you need to do a c2 – c1 to get the total volume. The RATE part indicates that the final value will be (c2-c1)/bucketsize
MAXIMUM Maximum of all samples in the window
MINIMUM Minimum of all samples in the window
window
every counter group has a streaming window of bucketsize seconds. This is by default 60 seconds, but can be as low as 1 second.

Table T.util

Useful utility functions written in C, exported to LUA via T.util table. We find them most handy for network related scripting.


-- called using T.util. (dot format)

local hexstr= T.util.bin2hex( binstr) 

Name In Out Description
ntop number 32-bit IPv4 string IP in dotted decimal format Convert a 32 bit number to IPv4 address string
pton string ip in dotted decimal number 32 bit IP address Convert an IPv4 address string to a number
bor number p ,number q number p OR q bitwise OR of two numbers
band number p,number q number p AND q bitwise AND of two numbers
testbit32 number p, number (bit position) bool Test bit position of a 32 bit number. LSB=0, MSB=31
T.util.testbit32(num,8)@ returns true if bit 8 = 1
bitval32 number p, number (start bit), number width number Get value of continous bits.
T.util.bitval32(num,20,4) returns the numeric value of bits 20,19,18,17. Bit numbering start from 0 (C-style)
split string the string to split, string the delimiter array of string tokens Split a string into tokens local tok_array = T.util.split(args,',')
splitm string the string to split, string the delimiter multiple string returns Split a string into tokens and returns multiple values. Example local flowid,path = T.util.splitm(args,',')
hash string to hash , optional number number of bits wide hash number the hash code Compute a hash of the input string – Uses Murmur2 hash, output is n-bits wide.
local h =T.util.hash("Mystring",16) The second argument nbits is optional with a default of 32
bin2hex string can include binary string the hex Convert the binary to hex
hex2bin string a hex string binary Convert the hex to binary string
bit32 in Lua 5.2 note The bit utilities have been provided because we are using LuaJIT which does not support Lua5.2’s bit32 library.

Function T.re2

The LUA regex functionality is quite limited. Google RE2 is a fast, threadsafe, and powerful Regex engine. You may want to use this Regex engine over Lua’s default find and match methods in the following cases.

  1. T.re2 also allows you to employ very common string matching idioms like (octet-stream|application-x|application-pdf) which arent available in Lua’s find method.
  2. T.re2 allows you to precompile the regexes once and run them later
Name In Out Description
T.re2 string, table (optional) A re2 object Precompile the regex string and return an re2 object. The optional second argument is a table containing boolean RE2::Options.

RE2 Options

The following RE2 options are supported, the default values are in parantheses


    //   utf8             (true)  text and pattern are UTF-8; otherwise Latin-1
    //   posix_syntax     (false) restrict regexps to POSIX egrep syntax
    //   longest_match    (false) search for longest match, not first match
    //   log_errors       (true)  log syntax and execution errors to ERROR
    //   literal          (false) interpret string as literal, not regexp
    //   never_nl         (false) never match \n, even if it is in regexp
    //   never_capture    (false) parse all parens as non-capturing
    //   case_sensitive   (true)  match is case-sensitive (regexp can override
    //                              with (?i) unless in posix_syntax mode)

Simple use

A sample illustrating a typical use.


  -- precompile in onload
  onload = function() 

    my_regex = T.re2("User-Agent\\s*:\\s*(.*)\r\n")

  end

  onflowattribute = function(...)
    --
    -- my_regex is a precompiled re2 object, just compare
    -- or extract from a target string
    ---
    if my_regex:partial_match( a_string ) then 
      ..
    end

With RE2 options

We create a RE2 object with a regex and the “case_sensitive” and another option


  -- precompile in onload
  onload = function() 

    my_regex = T.re2("User-Agent\\s*:\\s*(.*)\r\n",  { case_sensitive = true, posix_syntax = true})

  end

Function T.ac

A fast and minimal Aho-Corasick multi pattern matcher.

T.ac table (An array of patterns) An AC object Load all the patterns into an AC matcher and return an AC matcher object

A sample illustrating a typical use.


  onload = function() 
    -- add patterns in array and create a new AC matcher 
    ac_headers   = T.ac({ "Host:",
                        "User-Agent:",
                        "Referer",
                        "Server:",
                        "Content-Type:",
                        "Content-Length:"} )

   
   -- later on you can use the match methods
   ac_headers:match_all(...)

Function T.log

Adds a log message to the main Trisul log file. Trisul automatically adds the lua script filename to the log message so you know where the message is actually coming from. Also see Printing and Logging from LUA script

Name In Out Description
T.log T.K.loglevel – optional loglevel
string – log message
none Log a message to the Trisul log file, usually located for the default setup in /usr/local/var/log/trisul-probe/domain0/probe0/context0 . The default loglevel is T.K.loglevel.DEBUG
T.logerror string – msg none Useful shortcut to log a message with loglevel of ERROR. T.logerror(msg) is the same as T.log(T.K.loglevel.ERROR,msg)
T.logwarning string – msg none Log a message with WARN category
T.logdebug string – msg none Log a message with DEBUG category
T.loginfo string – msg none Log a message with INFO category

Usage

The following snippets demonstrates the usage of T.log



T.log( T.K.loglevel.INFO,  "Your log message from lua ")
T.log( "This message has uses the default DEBUG log level  ")

T.log(T.K.loglevel.ERROR, "This is an error from my LUA script")
T.logerror( "This is an error message from my LUA script, same as above T.log() call")


Table T.alertgroups

This section applies equally to T.countergroups, T.resourcegroups, T.sessionggroups, T.ftsgroups as well.

The purpose for this table is to provide a searchable name to guid mapping table of all the alertgroups currently loaded in Trisul. The backend alert_monitor scripts require you to specify a GUID that identifies the entity you are attaching the script to. If you do not know the GUID of the alert group but you know the name, you can use this table. See below.

Example alert_monitor code

If you know the GUID of the alert group named Malware Domain as {FAC478BC-8891-0009-5F31-80774B010086} you can attach an alert monitor as shown below


TrisulPlugin = { 

alert_monitor  = {
 
  alert_guid = '{FAC478BC-8891-0009-5F31-80774B010086}',

Say you only know the name Malware Domain , this is where you use the T.alertgroups table to find the GUID


TrisulPlugin = { 

alert_monitor  = {
 
  alert_guid = function()
    for name ,guid in pairs(T.alertgroups) do
        if name:match("Malware Domain") then return guid; end
    end
  end,



Table T.env

Trisul environment. Allows you to read probe configuration for the context in which the LUA script is loaded.

Name In Out Description
configfile string – path of config file Full path of the trisulProbeConfig.xml file used by the running Trisul instance
get_config string – ‘xml path’. See description column string – value of config parameter Read a configuration parameter from the Trisul Probe configuration file. The XML Path supported is a very simple format “Node>Node>..Node”. So to read the config parameter User under App parent node the path is App>User

Usage

The most common use case of T.env is to find out where the following directories :

  • the “run state” directory — where per-run files, unix sockets are stored
  • the “config” directory — where persistent config is stored

Use 1 From a debug session



print("the path is "..T.env.configfile)

print("the username of Trisul process in config file (App>User) is "..T.env.get_config("App>User"))

Use 2 Opening a socket in runstate directory



local rundir  = T.env.get_config("App>RunStateDirectory")

local socket_file = rundir.."/myinput.socket"