TCP Chain¶
This module contains the TCPChain flow analysis chain which can be used by PATHspider’s Observer for recording basic TCP [RFC793] behaviour details. This module also contains a helper function that may be used by chains for the parsing of TCP options and a number of useful TCP related constants that can be used to interpret the results added to flow records by TCPChain.
- class pathspider.chains.tcp.TCPChain[source]¶
This flow analysis chain records details of basic TCP behaviour in the flow record. It will determine when a 3WHS has completed and has simplified logic for determining when a TCP flow has completed.
Field Name
Type
Description
tcp_synflags_fwd
int
SYN flags seen in the forward direction
tcp_synflags_rev
int
SYN flags seen in the reverse direction
tcp_fin_fwd
bool
At least one FIN flag was seen in the forward direction
tcp_fin_rev
bool
At least one FIN flag was seen in the reverse direction
tcp_rst_fwd
bool
At least one RST flag was seen in the forward direction
tcp_rst_rev
bool
At least one RST flag was seen in the reverse direction
tcp_connected
bool
The 3WHS completed
- new_flow(rec, ip)[source]¶
For a new flow, all fields will be initialised to
False
excepttcp_synflags_*
which will be set toNone
.- Parameters:
rec (dict) – the flow record
ip (plt.ip or plt.ip6) – the IP or IPv6 packet that triggered the creation of a new flow record
- Returns:
Always
True
- Return type:
bool
- tcp(rec, tcp, rev)[source]¶
Records basic TCP behaviour details.
- SYN Flags
This will record the SYN flags observed in each direction. These will not be recorded again if there are futher segments in the flow with a SYN bit set, the first SYN observed wins.
- FIN and RST Flags
If a segment has the FIN or RST flags, the relevant fields are set to true.
- 3WHS
If a SYN was observed in the forward direction, and a SYNACK in the reverse direction and the segment passed is an ACK in the forward direction then
tcp_connected
will be set to True.- Flow Completion
If a FIN has been observed in one direction and this segment contains a FIN in the other direction, a flow is considered complete. If a RST has been observed in either direction, a flow is considered complete.
- Parameters:
rec (dict) – the flow record
tcp – the TCP segment that was observed to be part of this flow
rev (bool) – True if the packet was in the reverse direction, False if in the forward direction
- Returns:
True if flow should continue to be observed, False if the flow should be passed on for merging (i.e. the flow is complete)
- Return type:
bool
- pathspider.chains.tcp.TCP_ACK = 16¶
TCP Flag - ACK
- pathspider.chains.tcp.TCP_CWR = 128¶
TCP Flag - CWR
- pathspider.chains.tcp.TCP_ECE = 64¶
TCP Flag - ECE
- pathspider.chains.tcp.TCP_FIN = 1¶
TCP Flag - FIN
- pathspider.chains.tcp.TCP_PSH = 8¶
TCP Flag - PSH
- pathspider.chains.tcp.TCP_RST = 4¶
TCP Flag - RST
- pathspider.chains.tcp.TCP_SA = 18¶
TCP Flags - SYN and ACK
- pathspider.chains.tcp.TCP_SAE = 82¶
TCP Flags - SYN, ACK, ECE
- pathspider.chains.tcp.TCP_SAEC = 210¶
TCP Flags - SYN, ACK, ECE and CWR
- pathspider.chains.tcp.TCP_SEC = 194¶
TCP Flags - SYN, ACK and ECE
- pathspider.chains.tcp.TCP_SYN = 2¶
TCP Flag - SYN
- pathspider.chains.tcp.TCP_URG = 32¶
TCP Flag - URG
- pathspider.chains.tcp.TO_EOL = 0¶
TCP Option - End of options list
- pathspider.chains.tcp.TO_EXID_FASTOPEN = (249, 137)¶
TCP Option Experiment ID - TCP Fast Open
- pathspider.chains.tcp.TO_EXPA = 254¶
TCP Option - Experimental Option A
- pathspider.chains.tcp.TO_EXPB = 255¶
TCP Option - Experimental Option B
- pathspider.chains.tcp.TO_FASTOPEN = 34¶
TCP Option - TCP Fast Open Cookie
- pathspider.chains.tcp.TO_MPTCP = 30¶
TCP Option - Multipath TCP
- pathspider.chains.tcp.TO_MSS = 2¶
TCP Option - Maximum Segment Size
- pathspider.chains.tcp.TO_NOP = 1¶
TCP Option - No Operation
- pathspider.chains.tcp.TO_SACK = 5¶
TCP Option - Selective Acknowledgement
- pathspider.chains.tcp.TO_SACKOK = 4¶
TCP Option - Selective Acknowledgement Permitted
- pathspider.chains.tcp.TO_TS = 8¶
TCP Option - Timestamp
- pathspider.chains.tcp.TO_WS = 3¶
TCP Option - Window Scaling
- pathspider.chains.tcp.tcp_options(tcp)[source]¶
Parses and extracts TCP options from a python-libtrace TCP object.
Warning
This is a pure Python implementation of a TCP options parser and does not benefit from the speed advantage generally realised by calling to libtrace functions written in C through python-libtrace.
- Parameters:
tcp (plt.tcp) – The TCP header to extract options from
- Returns:
A mapping of option kinds to values
- Return type:
dict