Input filter

FRONTEND SCRIPT

Custom data acquisition for driving the Trisul pipelines.

  1. read packet data from non PCAP sources
  2. process “flow like” data from arbitrary formats
  3. plug into custom alert platforms

Running these type of scripts

Unlike other LUA scripts the input_filter script needs to be run on the command line because it drives the Trisul-Probe.

You run trisul-probe like so. See trisul executable


trisul -demon /usr/local/etc/trisul-probe/domain0/probe0/context0/trisulProbeConfig.xml \
   -mode lua   \ 
     -in /home/kev/my-input-filter.lua   \
       -args hello-argument 

Structure

Arguments in T.args

All input filter scripts can access the global variable T.args this is the parameter that is passed using .. -args args123 while running the Trisul Probe executable.

Table inputfilter


inputfilter = {

  step = function(packet, engine )
    ... 
    -- get next packet or batch of packets 
  end,

  step_alert  = function()
    ...
    -- get next alert or batch of alerts 
  end,

}
name description
function step called when trisul ready for new packet(s)
function step_alert called when trisul ready for new alert(s)

LUA functions reference

The step functions are called by Trisul framework at the appropriate time.

Function step

Purpose

Process a packet.

When called

Process a packet or a batch of packets. You can do two things.

  1. construct a real packet and use “set_packet” on the supplied “Packet” parameter
  2. just call methods on the “Engine” object supplied

Parameters

newpacket An Packet object if you wish to construct a new packet, use the set_packet method to set the packet bytes
engine An Engine object use this object to add metrics, resources, or alerts into the Trisul framework

Return value

Return true if you want to be called again
Return false if you have EOF.

Example

Function step_alert

Read a new alert object.

Purpose

This method is repeatedly called – if you have a new alert object from your input framework return that object.

When called

When Trisul checks to see if you have a new alert.

Parameters

No parameters

Return value – alert

The Trisul framework will call step_alert at appropriate times making sure it wont starve any of the sources.

When the step_alert is called – you need to return

  1. nil – if you dont have any alert to process.
  2. the following table – if you do have an alert.
NO BLOCK
Do not block in the step_alert function. This means you cant wait on some socket connection on an alert. Use Non Blocking socket or file reads.

If you have an alert, return this table with the following fields

field type mandatory/optional description
AlertGroupGUID guid string mandatory field A GUID that specifies the type of alert
TimestampSecs numeric mandatory field epoch secs
TimestampUsecs numeric default 0 epoch usecs
SigIDKey string mandatory field SignatureID or someother type of key that uniquely identifies the type of alert
SigIDKeyLabel string mandatory field A user label or description for the SigIDKey. This is placed in Trisul framework as a UserLabel for the Key for display purposes.
SensorID numeric default 0 Which sensor
ProtocolFamily numeric default 0 Protocol family 0 = IPv4 or 1=IPv6 – we dont actually use this to interpret the SourceIP and DestIP fields, just pass it onto the storage for correlation with snort
SourceIP string default “0.0.0.0” The IPv4 or IPv6 address. Hostnames are not allowed
SourcePort string default “0” port number or any string identifying non TCP/UDP transport eg. igmp or icmp01 to denote ICMP message type 1
DestIP string default “0.0.0.0” IPv4 or v6 address string
DestPort string default “0” See Source Port
Protocol numeric default 0 IP Protocol number. “6” for TCP, “17” for UDP etc
SigGenerator numeric default 0 snort SigGenerator, we dont process just send it to backend storage for correlation with SIEM
SigRev numeric default 0 Signature revision
ClassificationKey string default “c-xx” The type of classification. CID in Snort parlance
Priority numeric default 1 Alert Priority (1 = Crit, 2=Maj, 3=Minor)
EventID numeric default 0 Snort compatiable used for correlation only
AcknowledgeFlag numeric default 0 0=Unacknowledged Alert, 1=Acknowledged
AlertDetails string default "" Any extra text you want to append to the alert (searchable via Trisul)
AlertStatus string default “ALARM ALARM or CLEAR. Actually you can set it to any string that is meaningful to your particular alert group

Usage