Built-in Support

Each reassembly or flow tracing adapter below returns the data its pcapkit.foundation counterpart consumes, or None for a frame it cannot use.

PCAP Tools

pcapkit.toolkit.pcap contains the adapters for the PCAP format. The TCP adapters here and in pcapkit.toolkit.pcapng read the segment with tcp_segment(), and the DTLS ones the record with _dtls_fragments().

pcapkit.toolkit.pcap.ipv4_reassembly(frame)[source]

Make data for IPv4 reassembly.

A frame can be reassembled if it contains an IPv4 layer (IPv4) and the DF (IPv4.flags.df) flag is False. In an IP-in-IP tunnel, the layer is the first that is a fragment (see _fragment()).

Parameters:

frame (Frame) – PCAP frame.

Return type:

Packet[IPv4Address] | None

Returns:

Data for IPv4 reassembly (reasm.ipv4.packet) if the frame can be reassembled; otherwise None.

See also

pcapkit.foundation.reassembly.ipv4.IPv4

pcapkit.toolkit.pcap.ipv6_reassembly(frame)[source]

Make data for IPv6 reassembly.

A frame can be reassembled if it contains an IPv6 layer (IPv6) and an IPv6 Fragment header (RFC 2460 Section 4.5, i.e., IPv6_Frag). In an IP-in-IP tunnel, the layer is the first that has one (see _fragment()).

Parameters:

frame (Frame) – PCAP frame.

Return type:

Packet[IPv6Address] | None

Returns:

Data for IPv6 reassembly (reasm.ipv6.packet) if the frame can be reassembled; otherwise None.

See also

pcapkit.foundation.reassembly.ipv6.IPv6

pcapkit.toolkit.pcap.tcp_reassembly(frame)[source]

Make data for TCP reassembly.

A frame can be reassembled if it contains a TCP layer (TCP), or a TCP segment whose header the TCP parser rejected, as it does one the snapshot length cut short (#1518).

Parameters:

frame (Frame) – PCAP frame.

Return type:

Packet | None

Returns:

Data for TCP reassembly (reasm.tcp.packet) if the frame can be reassembled; otherwise None.

See also

pcapkit.foundation.reassembly.tcp.TCP

pcapkit.toolkit.pcap.dtls_reassembly(frame)[source]

Make data for DTLS handshake-message reassembly.

A frame can be reassembled if UDP carries a DTLS layer (DTLS) whose cleartext handshake record holds a fragmented message (DTLSHandshake.is_fragmented, RFC 6347 Section 4.2.3). Only the frame’s first record is read.

Parameters:

frame (Frame) – PCAP frame.

Return type:

tuple[Packet, ...] | None

Returns:

Data for DTLS reassembly (reasm.dtls.packet), one per fragmented message, if the frame can be reassembled; otherwise None.

See also

pcapkit.foundation.reassembly.dtls.DTLS

Added in version 1.6.0.

pcapkit.toolkit.pcap.tcp_traceflow(frame, *, data_link)[source]

Trace packet flow for TCP.

A frame can be traced if it contains a TCP layer (TCP), or a TCP segment whose header the TCP parser rejected, as it does one the snapshot length cut short (#1518).

Parameters:

  • frame (Frame) – PCAP frame.

  • data_link (LinkType) – Data link layer protocol (from global header).

Return type:

Packet | None

Returns:

Data for TCP flow tracing (trace.tcp.packet) if the frame can be traced; otherwise None.

See also

pcapkit.foundation.traceflow.tcp.TCP

Auxiliary Functions

pcapkit.toolkit.pcap.tcp_segment(frame)[source]

The TCP segment frame carries, or None if it carries none.

The TCP reassembly and flow tracing adapters of this module and of pcapkit.toolkit.pcapng all read the segment with this.

Parameters:

frame (ProtocolBase) – PCAP frame or PCAP-NG block.

Return type:

TCPSegment | None

Returns:

The fields of the TCP layer if pcapkit parsed one, with those of the IP layer that carries it – in a tunnel, the innermost (#1581). Otherwise, the fields of the fixed 20-octet TCP header (RFC 9293 Section 3.1) if the payload of the innermost IP layer is a Raw the TCP parser rejected, of protocol TCP, from a datagram that is not a later fragment, with at least those 20 octets captured; else None. A segment past FRAME_LAYER_LIMIT is kept raw without being parsed, not rejected, so it is not read (#1610).

Note

A capture snapped inside the TCP header leaves a Data Offset that runs past the captured octets, and the TCP parser rejects such a header by design (#1404), so the segment arrives as Raw. The ports, numbers and flags are all in the fixed header, so the segment still belongs to its flow, as it does for dpkt, scapy and Wireshark (#1518). The header and payload are then the captured octets either side of the Data Offset. Inside a tunnel, this holds of the IP layer carrying the segment, as it does without one.

pcapkit.toolkit.pcap._fragment(frame, version)[source]

Fetch the IPv4 or IPv6 layer of a frame that IP reassembly reads.

Parameters:
Return type:

IPv4 | IPv6 | None

Returns:

The first version layer, from the outside in, that is a fragment – for IPv4, one with MF set or a non-zero Fragment Offset, for IPv6, one with an IPv6 Fragment header; with none, the outermost version layer; with no version layer, None.

Note

In an IP-in-IP tunnel (RFC 2003, RFC 2473, RFC 4213) either datagram may be the fragmented one: the inner, each fragment of it carried whole by the tunnel, or the tunnel’s own, whose first fragment alone carries the inner header. Each is reassembled on its own header (#2307). A frame of no tunnel has one layer to choose from.

pcapkit.toolkit.pcap._dtls_fragments(frame, *, num, timestamp)[source]

Make data for DTLS handshake-message reassembly from a frame’s DTLS record.

The DTLS adapters of this module and of pcapkit.toolkit.pcapng read the record with this.

Parameters:

  • frame (ProtocolBase) – PCAP frame or PCAP-NG block.

  • num (int) – Original packet range number.

  • timestamp (float) – Capture timestamp, in seconds since the Unix epoch.

Return type:

tuple[Packet, ...] | None

Returns:

One record per fragmented handshake message in the frame’s first DTLS layer, if UDP carries it and it is a cleartext handshake record holding one; otherwise None. The buffer ID is the IP and UDP endpoints nearest above the record, with its epoch (RFC 6347 Section 4.1).

Added in version 1.6.0.

class pcapkit.toolkit.pcap.TCPSegment(ip, srcport, dstport, seq, ack, syn, fin, rst, header, payload)[source]

Bases: NamedTuple

The fields of a TCP segment that the reassembly and flow tracing records take.

tcp_segment() returns one.

ip: IPv4 | IPv6

Info of the IP layer carrying the segment, the innermost one in a tunnel.

srcport: int

TCP source port.

dstport: int

TCP destination port.

seq: int

TCP sequence number.

ack: int

TCP acknowledgement number.

syn: bool

TCP synchronise (SYN) flag.

fin: bool

TCP finish (FIN) flag.

rst: bool

TCP reset (RST) flag.

header: bytes

Raw TCP header, as captured.

payload: bytes

Raw TCP payload, as captured.

PCAP-NG Tools

pcapkit.toolkit.pcapng contains the adapters for the PCAP-NG format.

pcapkit.toolkit.pcapng.ipv4_reassembly(frame)[source]

Make data for IPv4 reassembly.

A frame can be reassembled if it contains an IPv4 layer (IPv4) and the DF (IPv4.flags.df) flag is False. In an IP-in-IP tunnel, the layer is the first that is a fragment (see pcapkit.toolkit.pcap._fragment()).

Parameters:

frame (PCAPNG) – PCAP-NG frame.

Return type:

Packet[IPv4Address] | None

Returns:

Data for IPv4 reassembly (reasm.ipv4.packet) if the frame can be reassembled; otherwise None.

See also

pcapkit.foundation.reassembly.ipv4.IPv4

pcapkit.toolkit.pcapng.ipv6_reassembly(frame)[source]

Make data for IPv6 reassembly.

A frame can be reassembled if it contains an IPv6 layer (IPv6) and an IPv6 Fragment header (RFC 2460 Section 4.5, i.e., IPv6_Frag). In an IP-in-IP tunnel, the layer is the first that has one (see pcapkit.toolkit.pcap._fragment()).

Parameters:

frame (PCAPNG) – PCAP-NG frame.

Return type:

Packet[IPv6Address] | None

Returns:

Data for IPv6 reassembly (reasm.ipv6.packet) if the frame can be reassembled; otherwise None.

See also

pcapkit.foundation.reassembly.ipv6.IPv6

pcapkit.toolkit.pcapng.tcp_reassembly(frame)[source]

Make data for TCP reassembly.

A frame can be reassembled if it contains a TCP layer (TCP), or a TCP segment whose header the TCP parser rejected, as it does one the snapshot length cut short (#1518).

Parameters:

frame (PCAPNG) – PCAP-NG frame.

Return type:

Packet | None

Returns:

Data for TCP reassembly (reasm.tcp.packet) if the frame can be reassembled; otherwise None.

See also

pcapkit.foundation.reassembly.tcp.TCP

pcapkit.toolkit.pcapng.dtls_reassembly(frame)[source]

Make data for DTLS handshake-message reassembly.

A frame can be reassembled if UDP carries a DTLS layer (DTLS) whose cleartext handshake record holds a fragmented message (DTLSHandshake.is_fragmented, RFC 6347 Section 4.2.3). Only the frame’s first record is read (see pcapkit.toolkit.pcap._dtls_fragments()).

Parameters:

frame (PCAPNG) – PCAP-NG frame.

Return type:

tuple[Packet, ...] | None

Returns:

Data for DTLS reassembly (reasm.dtls.packet), one per fragmented message, if the frame can be reassembled; otherwise None.

See also

pcapkit.foundation.reassembly.dtls.DTLS

Added in version 1.6.0.

pcapkit.toolkit.pcapng.tcp_traceflow(frame, *, nanosecond=False)[source]

Trace packet flow for TCP.

A frame can be traced if it contains a TCP layer (TCP), or a TCP segment whose header the TCP parser rejected, as it does one the snapshot length cut short (#1518).

Parameters:

  • frame (PCAPNG) – PCAP-NG frame.

  • nanosecond (bool) – Whether to use nanosecond precision.

Return type:

Packet | None

Returns:

Data for TCP flow tracing (trace.tcp.packet) if the frame can be traced; otherwise None.

See also

pcapkit.foundation.traceflow.tcp.TCP

Auxiliary Functions

pcapkit.toolkit.pcapng.block2frame(block, *, nanosecond=False)[source]

Convert PCAP-NG block to PCAP frame.

Parameters:
Return type:

Frame

Returns:

PCAP frame.