Object Global table T

Global Table T index

Table T.host

Interact with the Trisul environment.

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

 T.host:is_homenet(“192.168.2.1”) 

Table T.K

Pre-defined constants to use with other Lua functions.

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

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) 

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

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.

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

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

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.

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"