Built-in Support

PCAP Tools

pcapkit.toolkit.pcap contains the adapters for the PCAP format. The reassembly and flow tracing adapters return the data their pcapkit.foundation counterpart consumes, or None if the frame cannot be used for it. The TCP adapters here and in pcapkit.toolkit.pcapng read the segment with tcp_segment().

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

Make data for IPv4 reassembly.

Parameters:

frame (Frame) – PCAP frame.

Return type:

Packet[IPv4Address] | None

Returns:

Data for IPv4 reassembly.

  • If the frame can be used for IPv4 reassembly. A frame can be reassembled if it contains IPv4 layer (IPv4) and the DF (IPv4.flags.df) flag is False.

  • If the frame can be reassembled, then the dict mapping of data for IPv4 reassembly (c.f. reasm.ipv4.packet) will be returned; otherwise, returns None.

See also

pcapkit.foundation.reassembly.ipv4.IPv4

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

Make data for IPv6 reassembly.

Parameters:

frame (Frame) – PCAP frame.

Return type:

Packet[IPv6Address] | None

Returns:

Data for IPv6 reassembly.

  • If the frame can be used for IPv6 reassembly. A frame can be reassembled if it contains IPv6 layer (IPv6) and IPv6 Fragment header (RFC 2460 Section 4.5, i.e., IPv6_Frag).

  • If the frame can be reassembled, then the dict mapping of data for IPv6 reassembly (reasm.ipv6.packet) will be returned; otherwise, returns None.

See also

pcapkit.foundation.reassembly.ipv6.IPv6

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

Make data for TCP reassembly.

Parameters:

frame (Frame) – PCAP frame.

Return type:

Packet | None

Returns:

Data for TCP reassembly.

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

  • If the frame can be reassembled, then the dict mapping of data for TCP reassembly (reasm.tcp.packet) will be returned; otherwise, returns None.

See also

pcapkit.foundation.reassembly.tcp.TCP

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

Trace packet flow for TCP.

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.

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

  • If the frame can be traced, then the dict mapping of data for TCP flow tracing (trace.tcp.packet) will be returned; otherwise, returns 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.

class pcapkit.toolkit.pcap.TCPSegment(ip: Data_IPv4 | Data_IPv6, srcport: int, dstport: int, seq: int, ack: int, syn: bool, fin: bool, rst: bool, header: bytes, payload: bytes)[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. The reassembly and flow tracing adapters return the data their pcapkit.foundation counterpart consumes, or None if the frame cannot be used for it.

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

Make data for IPv4 reassembly.

Parameters:

frame (PCAPNG) – PCAP-NG frame.

Return type:

Packet[IPv4Address] | None

Returns:

Data for IPv4 reassembly.

  • If the frame can be used for IPv4 reassembly. A frame can be reassembled if it contains IPv4 layer (IPv4) and the DF (IPv4.flags.df) flag is False.

  • If the frame can be reassembled, then the dict mapping of data for IPv4 reassembly (c.f. reasm.ipv4.packet) will be returned; otherwise, returns None.

See also

pcapkit.foundation.reassembly.ipv4.IPv4

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

Make data for IPv6 reassembly.

Parameters:

frame (PCAPNG) – PCAP-NG frame.

Return type:

Packet[IPv6Address] | None

Returns:

Data for IPv6 reassembly.

  • If the frame can be used for IPv6 reassembly. A frame can be reassembled if it contains IPv6 layer (IPv6) and IPv6 Fragment header (RFC 2460 Section 4.5, i.e., IPv6_Frag).

  • If the frame can be reassembled, then the dict mapping of data for IPv6 reassembly (reasm.ipv6.packet) will be returned; otherwise, returns None.

See also

pcapkit.foundation.reassembly.ipv6.IPv6

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

Make data for TCP reassembly.

Parameters:

frame (PCAPNG) – PCAP-NG frame.

Return type:

Packet | None

Returns:

Data for TCP reassembly.

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

  • If the frame can be reassembled, then the dict mapping of data for TCP reassembly (reasm.tcp.packet) will be returned; otherwise, returns None.

See also

pcapkit.foundation.reassembly.tcp.TCP

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

Trace packet flow for TCP.

Parameters:

  • frame (PCAPNG) – PCAP-NG frame.

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

Return type:

Packet | None

Returns:

Data for TCP flow tracing.

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

  • If the frame can be traced, then the dict mapping of data for TCP flow tracing (trace.tcp.packet) will be returned; otherwise, returns 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.