Tutorial: Plugin Pcap Extraction

As detailed in the pcap extraction tutorial, T2 is capable to extract flows into pcaps using the pcapd plugin. The regex_pcre and dnsDecode are an example for this operation. In order to implement this feature in your own plugin, specialized macros are supplied, which will be detailed in this tutorial. You do not need to enable the ALARM_MODE it also works in the normal flow mode.

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

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

If you did not read the tutorials before, here is the basic plugin which we will extend: tcpWin Extract it and copy it under your plugins directory if you have not already. You may also use any of your versions developed during earlier tutorials. If you follows the plugin alarm mode tutorial, adding the pcapd plugin does the trick as demonstrated in the pcap extraction tutorial. Otherwise follow the following instructions.

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 alarm mode.

Implementing the FL_ALARM capability

Open tcpWin.c in an editor, move to the claimLayer4Information() callback and add the T2_SET_STATUS() line marked by <--.

Now pcapd will extract all packets of a flow where the FL_ALARM is set.

If you want to have the global FL_ALARM status including flow and alarm count shown as a warning in the end report, then add the T2_REPORT_ALARMS() macro in the onFlowTerminate() callback as marked by <--.

Save the file, recompile, run t2 on the pcap.

$ t2build tcpWin
...
$ t2 -r ~/data/faf-exercise.pcap -w ~/results/
================================================================================
Tranalyzer 0.8.7 (Anteater), Tarantula. PID: 40742
================================================================================
[INF] Creating flows for L2, IPv4, IPv6
Active plugins:
    01: basicFlow, 0.8.7
    02: tcpStates, 0.8.7
    03: tcpWin, 0.8.7
    04: txtSink, 0.8.7
    05: pcapd, 0.8.7
[INF] basicFlow: IPv4 Ver: 4, Rev: 20102019, Range Mode: 0, subnet ranges loaded: 310421 (310.42 K)
[INF] basicFlow: IPv6 Ver: 4, Rev: 20102019, Range Mode: 0, subnet ranges loaded: 21495 (21.50 K)
Processing file: /home/wurst/data/faf-exercise.pcap
...
--------------------------------------------------------------------------------
tcpStates: Aggregated anomaly flags: 0x4a
pcapd: number of packets extracted: 1467 (1.47 K) [24.86%]
--------------------------------------------------------------------------------
...
Aggregate flow status: 0x0002000000004000
[WRN] 4 alarms in 1 flows [1.39%]
[INF] IPv4
$

Note the [WRN] which is 0x0002000000000000 in the aggregate flow status, printed above. Try a tawk -V to decode the flow status:

$ tawk -V flowStat=0x0002000000004000

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

   bit | flowStat              | Description
   =============================================================================
    14 | 0x0000 0000 0000 4000 | IPv4
    49 | 0x0002 0000 0000 0000 | Alarm mode & pcapd dumps packets from this flow to new pcap if not -e option

See?!

Now move to the results directory and look into it.

$ cd ~/results
$ ls
faf-exercise_flows.txt  faf-exercise_headers.txt  faf-exercise_pcapd.pcap
$

Note the file faf-exercise_pcapd.pcap, which represents the extracted packets belonging to the flow where the FL_ALARM bit is set. To verify, select these flows using tawk.

$ tawk 'bitsanyset($flowStat, 0x0002000000000000)' faf-exercise_flows.txt | tcol
%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       0x0002000000004000  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  07       "Private network"  49330    143.166.11.10  us       "Dell"    64334    6        0x42       0x01        4
$

Have fun!

The next tutorial will teach you how to develop a plugin in Rust

See Also