Trace TCP Flows

pcapkit.foundation.traceflow is the interface to trace TCP flows from a series of packets and connections.

Note

This was implemented as the demand of my mate @gousaiyang.

Data Structure

trace.packet

Data structure for TCP flow tracing (dump()) is as following:

tract_dict = dict(
    protocol=data_link,                     # data link type from global header
    index=frame.info.number,                # frame number
    frame=frame.info,                       # extracted frame info
    syn=tcp.flags.syn,                      # TCP synchronise (SYN) flag
    fin=tcp.flags.fin,                      # TCP finish (FIN) flag
    src=ip.src,                             # source IP
    dst=ip.dst,                             # destination IP
    srcport=tcp.srcport,                    # TCP source port
    dstport=tcp.dstport,                    # TCP destination port
    timestamp=frame.info.time_epoch,        # frame timestamp
)

trace.buffer

Data structure for internal buffering when performing reassembly algorithms (_buffer) is as following:

(dict) buffer --> memory buffer for reassembly
 |--> (tuple) BUFID : (dict)
 |       |--> ip.src      |
 |       |--> ip.dst      |
 |       |--> tcp.srcport |
 |       |--> tcp.dstport |
 |                        |--> 'fpout' : (dictdumper.dumper.Dumper) output dumper object
 |                        |--> 'index': (list) list of frame index
 |                        |              |--> (int) frame index
 |                        |--> 'label': (str) flow label generated from ``BUFID``
 |--> (tuple) BUFID ...

trace.index

Data structure for TCP flow tracing (element from index tuple) is as following:

(tuple) index
 |--> (Info) data
 |     |--> 'fpout' : (Optional[str]) output filename if exists
 |     |--> 'index': (tuple) tuple of frame index
 |     |              |--> (int) frame index
 |     |--> 'label': (str) flow label generated from ``BUFID``
 |--> (Info) data ...

Implementation

class pcapkit.foundation.traceflow.TraceFlow(fout=None, format=None, byteorder='little', nanosecond=False)

Bases: object

Trace TCP flows.

__call__(packet)

Dump frame to output files.

Parameters

packet (Dict[str, Any]) – a flow packet (trace.packet)

__init__(fout=None, format=None, byteorder='little', nanosecond=False)

Initialise instance.

Parameters

• fout (Optional[str]) – output path

• format (Optional[str]) – output format

• byteorder (str) – output file byte order

• nanosecond (bool) – output nanosecond-resolution file flag

dump(packet)

Dump frame to output files.

Parameters

packet (Dict[str, Any]) – a flow packet (trace.packet)

static make_fout(fout='./tmp', fmt='pcap')

Make root path for output.

Positional arguments:

fout (str): root path for output fmt (str): output format

Returns

dumper of specified format and file extension of output file

Return type

Tuple[Type[dictdumper.dumper.Dumper], str]

Warns

• FormatWarning – If fmt is not supported.

• FileWarning – If fout exists and fmt is None.

Raises

FileExists – If fout exists and fmt is NOT None.

submit()

Submit traced TCP flows.

Returns

traced TCP flow (trace.buffer)

Return type

Tuple[Info]

trace(packet, *, check=True, output=False)

Trace packets.

Parameters

packet (Dict[str, Any]) – a flow packet (trace.packet)

Keyword Arguments

• check (bool) – flag if run validations

• output (bool) – flag if has formatted dumper

Returns

If output is True, returns the initiated Dumper object, which will dump data to the output file named after the flow label; otherwise, returns the flow label itself.

Return type

Union[dictdumper.dumper.Dumper, str]

Notes

The flow label is formatted as following:

f'{packet.src}_{packet.srcport}-{packet.dst}_{info.dstport}-{packet.timestamp}'

_buffer

Buffer field (trace.buffer).

Type

dict

_endian

Output file byte order.

Type

Literal[‘little’, ‘big’]

_fdpext

Output file extension.

Type

str

_foutio

Dumper class.

Type

Type[dictdumper.dumper.Dumper]

_fproot

Output root path.

Type

str

_newflg

New packet flag.

Type

bool

_nnsecd

Output nanosecond-resolution file flag.

Type

bool

_stream

Stream index (trace.index).

Type

list

property index

Index table for traced flow.

Return type

Tuple[Info]