# 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`

  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)

    For a new flow, all fields will be initialised to `False` except `tcp_synflags_*` which will be set to `None`.

    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)

    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)

  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