Tutorial: Plugin Force Mode

As detailed in force mode tutorial T2 is capable to operate in a plugin controlled flow release. For example, the basicStats plugin can force the termination of a flow. 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 FORCE_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 FORCE_MODE 1 // netflow mode: parameter induced flow termination, implemented by plugins

Or use the following t2conf command:

$ t2conf tranalyzer2 -D FORCE_MODE=1

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

$ t2build -e
$ t2build tranalyzer2 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 haven’t already. Now you are all set for the force mode implementation.

Implementing the force mode capability

If your plugin wants to implement the force mode, then specific code related to the force mode, but be surrounded by #if FORCE_MODE == 1 and #endif // FORCE_MODE == 1 instructions and the T2_RM_FLOW(flowP) macro must be used.

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 claimLayer4Information(...) callback the code surrounded by the FORCE_MODE pragmas.

Just use the T2_RM_FLOW(...) macro and your flow will be terminated if your condition applies and all core and flow status bits will be set automatically. So save the file, compile tcpWin and execute T2.

$ t2build tcpWin
$ t2 -r ~/data/faf-exercise.pcap -w ~/results/
Tranalyzer 0.8.7 (Anteater), Tarantula. PID: 5081
[INF] Creating flows for L2, IPv4, IPv6 [FORCE]
Active plugins:
    01: basicFlow, 0.8.7
    02: tcpStates, 0.8.7
    03: tcpWin, 0.8.7
    04: txtSink, 0.8.7
[INF] basicFlow: IPv4 Ver: 3, Rev: 01072019, Range Mode: 0, subnet ranges loaded: 312743 (312.74 K)
[INF] basicFlow: IPv6 Ver: 3, Rev: 01072019, Range Mode: 0, subnet ranges loaded: 21494 (21.49 K)
Processing file: /home/wurst/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.004231 sec
Finished unloading flow memory. Time: 0.004248 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: 3533 (3.53 K) [59.86%]
Number of B packets: 2369 (2.37 K) [40.14%]
Number of A bytes: 4423178 (4.42 M) [88.58%]
Number of B bytes: 570236 (570.24 K) [11.42%]
Average A packet load: 1251.96 (1.25 K)
Average B packet load: 240.71
tcpStates: Aggregated anomaly flags: 0x4b
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: 74
Number of processed A flows: 37 [50.00%]
Number of processed B flows: 37 [50.00%]
Number of request     flows: 37 [50.00%]
Number of reply       flows: 37 [50.00%]
Total   A/B    flow asymmetry: 0.00
Total req/rply flow asymmetry: 0.00
Number of processed   packets/flows: 79.76
Number of processed A packets/flows: 95.49
Number of processed B packets/flows: 64.03
Number of processed total packets/s: 0.12
Number of processed A+B packets/s: 0.12
Number of processed A   packets/s: 0.07
Number of processed   B packets/s: 0.05
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.05 GB [0.08%]
Aggregate flow status: 0x0000020000004000
[WRN] Number of flows terminated by force mode: 2 [2.70%]
[INF] IPv4

Note the warning at the end of the T2 report. So we have total now 74 flows (originally 72), and two were released early. The following packets are deposited into a new flow having the same n-tuple. Let’s select the early terminated flows by a logical AND using the RMFLOW bit in flowStat as defined in flow.h in T2 core:

$ tawk -V flowStat=0x0000020000004000

The flowStat column with value 0x0000020000004000 is to be interpreted as follows:

   bit | flowStat              | Description
    14 | 0x0000 0000 0000 4000 | IPv4
    41 | 0x0000 0200 0000 0000 | Force mode: remove this flow instantly

The tawk to select all forced flow is then:

$ tawk 'bitsanyset($flowStat, 0x0000020000000000)' faf-exercise_flows.txt
dir	flowInd	flowStat	timeFirst	timeLast	duration	numHdrDesc	numHdrs	hdrDesc	srcMac	dstMac	ethType	ethVlanID	srcIP	srcIPCC	srcIPWho	srcPort	dstIP	dstIPCC	dstIPWho	dstPort	l4Proto	tcpStates	tcpWinStat	tcpWinThCnt
A	36	0x0000020000004000	1258594163.408285	1258594164.647755	1.239470	1	3	eth:ipv4:tcp	00:08:74:38:01:b4	00:19:e3:e7:5d:23	0x0800	09	"Private network"	49330	us	"Dell"	64334	6	0x02	0x01	2
B	37	0x0000020000004001	1258594165.319087	1258594191.015208	25.696121	1	3	eth:ipv4:tcp	00:08:74:38:01:b4	00:19:e3:e7:5d:23	0x0800	09	"Private network"	49330	us	"Dell"	64334	6	0x43	0x01	2

See? Play a bit around!

If you are interested in details, the macro T2_RM_FLOW(...) implements the following code in global.h:

The corresponding variables are defined in main.c:

The T2_RM_FLOW(...) macro sets RMFLOW in flow status. The core will act on that signal and releases all flows in the rm_flows[num_rm_flows] stack holding all flow pointers to be terminated next time the core is active. Moreover, it increments the numForced counter for the end report.

The dimension of rm_flows is defined in global.h. Currently there are only 10 elements defined, so you can also terminate dependent flows, such as in ICMP. If you uncomment the line above in global.h and increase the dimension of the stack to the whole flow memory size in main.c, Then, a plugin, which dumps all flows in the memory, let’s say every 30 sec, is easily achieved. A very powerful concept, but always be sure of what you are doing. If you have problems don’t hesitate to contact the Anteater, he’ll help

$ t2conf tranalyzer2 -D FORCE_MODE=0
$ t2build -R

Have fun!

The next tutorial will teach you how to add support for pcap extraction.

See Also