PcapFileEx.Flows.TCPExtractor (pcap_file_ex v0.5.5)

Extracts and reassembles TCP segments from PCAP files.

This module provides shared TCP extraction logic used by both HTTP/1 and HTTP/2 analyzers. It handles:

Decoding packets from various formats (Ethernet, null loopback, etc.)
Extracting TCP segment information
Reassembling TCP flows with sequence number ordering
Detecting and filtering retransmissions

Segment Format

Each extracted segment is a map with:

%{
  flow_key: {{src_ip, src_port}, {dst_ip, dst_port}},
  direction: :a_to_b | :b_to_a,
  data: binary(),
  src_port: integer(),
  dst_port: integer(),
  seq_num: integer(),
  timestamp: DateTime.t()
}

Example

{:ok, segments} = TCPExtractor.extract("capture.pcap")

# Filter by port
{:ok, segments} = TCPExtractor.extract("capture.pcap", port: 8080)

Summary

Types

segment()

Functions

extract(pcap_path, opts \\ [])

Extracts TCP segments from a PCAP file.

extract_from_stream(packet_stream, opts \\ [])

Extracts TCP segments from a stream of packets.

group_by_flow(segments)

Groups segments by flow key.

Types

segment()

@type segment() :: %{
  flow_key: {{tuple(), non_neg_integer()}, {tuple(), non_neg_integer()}},
  direction: :a_to_b | :b_to_a,
  data: binary(),
  src_port: non_neg_integer(),
  dst_port: non_neg_integer(),
  seq_num: non_neg_integer(),
  timestamp: DateTime.t()
}

Functions

extract(pcap_path, opts \\ [])

@spec extract(
  Path.t(),
  keyword()
) :: {:ok, [segment()]} | {:error, term()}

Extracts TCP segments from a PCAP file.

Options

:port - Filter to specific TCP port (default: nil, all ports)

Returns

{:ok, segments} where segments is a list of reassembled TCP segments ordered by timestamp, or {:error, reason} on failure.

Examples

{:ok, segments} = TCPExtractor.extract("capture.pcap")
{:ok, segments} = TCPExtractor.extract("capture.pcap", port: 8080)

extract_from_stream(packet_stream, opts \\ [])

@spec extract_from_stream(
  Enumerable.t(),
  keyword()
) :: [segment()]

Extracts TCP segments from a stream of packets.

Use this when you already have a packet stream.

Options

:port - Filter to specific TCP port (default: nil, all ports)

group_by_flow(segments)

@spec group_by_flow([segment()]) :: %{required(tuple()) => [segment()]}

Groups segments by flow key.

Returns a map of {flow_key => segments} where segments are ordered by timestamp.