Tutorial: Plugin Alarm Mode

As detailed in alarm mode tutorial T2 is capable to operate in a plugin controlled flow release. The regex_pcre and dnsDecode plugins are an example. In order to implement this feature in your own plugin specialized macros are supplied, which will be detailed in this tutorial. First switch on the ALARM_MODE in tranalyzer.h.

$ cd ~/tranalyzer2/tranalyzer2/src
$ vi tranalyzer.h
....
...
// Tranalyzer User Operational modes

// Operation modes, Plugins which use these modes have to be recompiled

#define ALARM_MODE 1 // only flow output if an Alarm based plugin fires
#define ALARM_AND  0 // if (ALARM_MODE == 1) then 1: AND, 0: OR
...

Reset your plugin directory into a pristine state and compile the following basic plugins:

$ t2build -e
...
$ t2build basicFlow tcpStates txtSink
...
$

If you did not read the tutorials before, here is the basis plugin which we will extend: tcpWin

The anonymized sample pcap can be downloaded here: faf-exercise.pcap. Please extract it under your data folder: ~/data, if you not already have. Now you are all set for the alarm mode.

Implementing the alarm capability

If your plugin wants to contribute information to the

So open tcpWin.c in an editor and add two global variables after the tcpWinFlows definition. Look for the <– markers below.

Then add in the onFlowTerminate callback the lines marked by <– which triggers an alarm if the Threshold count is > 0. You can replace the variable in T2_REPORT_ALARM by any other logical statement or variable.

The macro T2_REPORT_ALARMS() implements the following state-machine:

The variable supOut is a global switch suppressing the output. numAlarms denotes the aggregate of all flow alarms. So your plugin can reimplement any state-machine you want and control the output suppression to your liking. The easiest would be to set supOut = 1, then no flow would ever appear in the flow file, rather useless, right.

If you set ALARM_AND 1 in tranalyzer.h then any plugin can reset a flow terminate, so all plugins implementing ALARM_MODE must agree.

Now save tcpWin.c, compile it and execute T2

$ t2build tcpWin

...

$ t2 -r ~/data/faf-exercise.pcap -w ~/results/
================================================================================
Tranalyzer 0.8.4 (Anteater), Tarantula. PID: 23303
================================================================================
[INF] Creating flows for L2, IPv4
Active plugins:
    01: basicFlow, 0.8.4
    02: tcpStates, 0.8.4
    03: tcpWin, 0.8.4
    04: txtSink, 0.8.4
[INF] basicFlow: IPv4 Ver: 4, Rev: 1062019, Range Mode: 0, subnet ranges loaded: 66658 (66.66 K)
Processing file: /home/stefan/tranalyzer-website/tranalyzer/download/data/faf-exercise.pcap
Link layer type: Ethernet [EN10MB/1]
Dump start: 1258544215.037210 sec (Wed 18 Nov 2009 11:36:55 GMT)
Dump stop : 1258594491.683288 sec (Thu 19 Nov 2009 01:34:51 GMT)
Total dump duration: 50276.646078 sec (13h 57m 56s)
Finished processing. Elapsed time: 0.003957 sec
Finished unloading flow memory. Time: 0.003961 sec
Percentage completed: 100.00%
Number of processed packets: 5902 (5.90 K)
Number of processed bytes: 4993414 (4.99 M)
Number of raw bytes: 4993414 (4.99 M)
Number of pcap bytes: 5087870 (5.09 M)
Number of IPv4 packets: 5902 (5.90 K) [100.00%]
Number of A packets: 1986 (1.99 K) [33.65%]
Number of B packets: 3916 (3.92 K) [66.35%]
Number of A bytes: 209315 (209.31 K) [4.19%]
Number of B bytes: 4784099 (4.78 M) [95.81%]
Average A packet load: 105.40
Average B packet load: 1221.68 (1.22 K)
--------------------------------------------------------------------------------
tcpStates: Aggregated anomaly flags: 0x4a
--------------------------------------------------------------------------------
Headers count: min: 3, max: 3, average: 3.00
Number of TCP packets: 5902 (5.90 K) [100.00%]
Number of TCP bytes: 4993414 (4.99 M) [100.00%]
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Number of processed   flows: 72
Number of processed A flows: 36 [50.00%]
Number of processed B flows: 36 [50.00%]
Number of request     flows: 36 [50.00%]
Number of reply       flows: 36 [50.00%]
Total   A/B    flow asymmetry: 0.00
Total req/rply flow asymmetry: 0.00
Number of processed   packets/flows: 81.97
Number of processed A packets/flows: 55.17
Number of processed B packets/flows: 108.78
Number of processed total packets/s: 0.12
Number of processed A+B packets/s: 0.12
Number of processed A   packets/s: 0.04
Number of processed   B packets/s: 0.08
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Number of average processed flows/s: 0.00
Average full raw bandwidth: 795 b/s
Average full bandwidth : 792 b/s
Max number of flows in memory: 18 [0.01%]
Memory usage: 0.02 GB [0.03%]
Aggregate flow status: 0x0000000000004000
[WRN] ALARM MODE; Number of alarms: 4 [5.56%]
[INF] IPv4
$

Note the warning at the end of the T2 report. So of 72 flows only one flow was released producing four alarms.

$ tcol faf-exercise_flows.txt
%dir  flowInd  flowStat            timeFirst          timeLast           duration   numHdrDesc  numHdrs  hdrDesc       srcMac             dstMac             ethType  ethVlanID  srcIP          srcIPASN  srcIPCC  srcIPWho                 srcIPLat_Lng_relP  srcPort  dstIP          dstIPASN  dstIPCC  dstIPWho  dstIPLat_Lng_relP  dstPort  l4Proto  tcpStates  tcpWinStat  tcpWinThCnt
A     36       0x0000000000004000  1258594163.408285  1258594191.015208  27.606923  1           3        eth:ipv4:tcp  00:08:74:38:01:b4  00:19:e3:e7:5d:23  0x0800              192.168.1.105  0         09       "Private network      "  666_666_-1         49330    143.166.11.10  0         --       "--"      0_0_0              64334    6        0x42       0x01        4

It would be nice to have the amount of alarm flows already in the end report, so implement the following statements marked by <-- in tcpWin.c:

Add a global 32 bit variable:

and increment the 32bit counter if winThCnt events occurred:

Now add the pluginReport function after the onFlowTerminate block.

Now recompile and rerun T2:

$ t2build tcpWin
...
BUILD SUCCESSFUL

$ t2 -r ~/data/faf-exercise.pcap -w ~/results/
...
--------------------------------------------------------------------------------
tcpStates: Aggregated anomaly flags: 0x4a
tcpWin: Number of Alarm flows below win threshold 1: 1
--------------------------------------------------------------------------------
...
[WRN] ALARM MODE; Number of alarms: 4 [5.56%]
[INF] IPv4
$

See? Now you do not need to write a script which counts the number of flows in the flow file. Play a bit around and improve the program, e.g. modify the alarm condition if more than one winThreshold occurrences happen.

Have fun!