3rd-Party Support ¶

Returns:

Data for IPv4 reassembly.

If the packet can be used for IPv4 reassembly. A packet can be reassembled if it contains IPv4 layer (scapy.layers.inet.IP) and the DF (scapy.layers.inet.IP.flags.DF) flag is False.
If the packet can be reassembled, then the dict mapping of data for IPv4 reassembly (reasm.ipv4.packet) will be returned; otherwise, returns None.

pcapkit.toolkit.scapy.ipv6_reassembly(packet, *, count=-1)[source]¶

Make data for IPv6 reassembly.

Parameters:

packet (Packet) – Scapy packet.
count (int) – Packet index. If not provided, default to -1.

Return type:

Returns:

Data for IPv6 reassembly.

If the packet can be used for IPv6 reassembly. A packet can be reassembled if it contains IPv6 layer (scapy.layers.inet6.IPv6) and IPv6 Fragment header (RFC 2460 Section 4.5, i.e., scapy.layers.inet6.IPv6ExtHdrFragment).
If the packet can be reassembled, then the dict mapping of data for IPv6 reassembly (reasm.ipv6.packet) will be returned; otherwise, returns None.

Raises:

ModuleNotFound – If Scapy is not installed.

pcapkit.toolkit.scapy.tcp_reassembly(packet, *, count=-1)[source]¶

Store data for TCP reassembly.

Parameters:

packet (Packet) – Scapy packet.
count (int) – Packet index. If not provided, default to -1.

Return type:

pcapkit.foundation.reassembly.tcp.TCP

Returns:

Data for TCP reassembly.

If the packet can be used for TCP reassembly. A packet can be reassembled if it contains TCP layer (scapy.layers.inet.TCP).
If the packet can be reassembled, then the dict mapping of data for TCP reassembly (reasm.tcp.packet) will be returned; otherwise, returns None.

See also

pcapkit.toolkit.scapy.tcp_traceflow(packet, *, count=-1)[source]¶

Trace packet flow for TCP.

Parameters:

packet (Packet) – Scapy packet.
count (int) – Packet index. If not provided, default to -1.

Return type:

Returns:

Data for TCP reassembly.

If the packet can be used for TCP flow tracing. A packet can be reassembled if it contains TCP layer (scapy.layers.inet.TCP).
If the packet can be reassembled, then the dict mapping of data for TCP flow tracing (trace.tcp.packet) will be returned; otherwise, returns None.

See also

Auxiliary Functions¶

pcapkit.toolkit.scapy.packet2chain(packet)[source]¶

Fetch Scapy packet protocol chain.

Parameters:: packet (Packet) – Scapy packet.
Return type:: str
Returns:: Colon (:) separated list of protocol chain.
Raises:: ModuleNotFound – If Scapy is not installed.

pcapkit.toolkit.scapy.packet2dict(packet)[source]¶

Convert Scapy packet into dict.

Parameters:: packet (Packet) – Scapy packet.
Return type:: dict[str, Any]
Returns:: A dict mapping of packet data.
Raises:: ModuleNotFound – If Scapy is not installed.

DPKT Tools¶

pcapkit.toolkit.dpkt contains all you need for pcapkit handy usage with DPKT engine. All reforming functions returns with a flag to indicate if usable for its caller.

pcapkit.toolkit.dpkt.ipv4_reassembly(packet, timestamp, *, count=-1)[source]¶

Make data for IPv4 reassembly.

Parameters:

packet (Packet) – DPKT packet.
timestamp (float) – Capture timestamp of the packet, which drives the reassembly timeout. DPKT’s reader yields it beside the record’s octets rather than on the packet, so it is passed in – as tcp_traceflow() already does. A caller holding only a frame can read it back with packet2timestamp(), which is where DPKT leaves it.
count (int) – Packet index. If not provided, default to -1.

Return type:

Returns:

Data for IPv4 reassembly.

If the packet can be used for IPv4 reassembly. A packet can be reassembled if it contains IPv4 layer (dpkt.ip.IP) and the DF (dpkt.ip.IP.df) flag is False.
If the packet can be reassembled, then the dict mapping of data for IPv4 reassembly (reasm.ipv4.packet) will be returned; otherwise, returns None.

pcapkit.toolkit.dpkt.ipv6_reassembly(packet, timestamp, *, count=-1)[source]¶

Make data for IPv6 reassembly.

Parameters:

packet (Packet) – DPKT packet.
timestamp (float) – Capture timestamp of the packet, which drives the reassembly timeout; packet2timestamp() reads it back off a stored frame.
count (int) – Packet index. If not provided, default to -1.

Return type:

Returns:

Data for IPv6 reassembly.

If the packet can be used for IPv6 reassembly. A packet can be reassembled if it contains IPv6 layer (dpkt.ip6.IP6) and IPv6 Fragment header (RFC 2460 Section 4.5, i.e., dpkt.ip6.IP6FragmentHeader).
If the packet can be reassembled, then the dict mapping of data for IPv6 reassembly (reasm.ipv6.packet) will be returned; otherwise, returns None.

pcapkit.toolkit.dpkt.tcp_reassembly(packet, timestamp, *, count=-1)[source]¶

Make data for TCP reassembly.

Parameters:

packet (Packet) – DPKT packet.
timestamp (float) – Capture timestamp of the packet, which drives the reassembly timeout; packet2timestamp() reads it back off a stored frame.
count (int) – Packet index. If not provided, default to -1.

Return type:

pcapkit.foundation.reassembly.tcp.TCP

Returns:

Data for TCP reassembly.

If the packet can be used for TCP reassembly. A packet can be reassembled if it contains TCP layer (dpkt.tcp.TCP).
If the packet can be reassembled, then the dict mapping of data for TCP reassembly (reasm.tcp.packet) will be returned; otherwise, returns None.

See also

pcapkit.toolkit.dpkt.tcp_traceflow(packet, timestamp, *, data_link, count=-1)[source]¶

Trace packet flow for TCP.

Parameters:

packet (Packet) – DPKT packet.
timestamp (float) – Timestamp of the packet.
data_link (LinkType) – Data link layer protocol (from global header).
count (int) – Packet index. If not provided, default to -1.

Return type:

Returns:

Data for TCP reassembly.

If the packet can be used for TCP flow tracing. A packet can be reassembled if it contains TCP layer (dpkt.tcp.TCP).
If the packet can be reassembled, then the dict mapping of data for TCP flow tracing (trace.tcp.packet) will be returned; otherwise, returns None.

See also

Auxiliary Functions¶

pcapkit.toolkit.dpkt.ipv6_hdr_len(ipv6)[source]¶

Calculate length of headers before IPv6 Fragment header.

Parameters:: ipv6 (IP6) – DPKT IPv6 packet.
Return type:: int
Returns:: Length of headers before IPv6 Fragment header dpkt.ip6.IP6FragmentHeader (RFC 2460 Section 4.5).

As specified in RFC 2460 Section 4.1, such headers (before the IPv6 Fragment Header) includes Hop-by-Hop Options header dpkt.ip6.IP6HopOptsHeader (RFC 2460 Section 4.3), Destination Options header dpkt.ip6.IP6DstOptHeader (RFC 2460 Section 4.6) and Routing header dpkt.ip6.IP6RoutingHeader (RFC 2460 Section 4.4).

pcapkit.toolkit.dpkt.packet2chain(packet)[source]¶

Fetch DPKT packet protocol chain.

Parameters:: packet (Packet) – DPKT packet.
Return type:: str
Returns:: Colon (:) separated list of protocol chain.

pcapkit.toolkit.dpkt.packet2dict(packet, timestamp, *, data_link)[source]¶

Convert DPKT packet into dict.

Parameters:

packet (Packet) – Scapy packet.
timestamp (float) – Timestamp of packet.
data_link (LinkType) – Data link type.

Returns:

A dict mapping of packet data.

Return type:

PyShark Tools¶

pcapkit.toolkit.pyshark contains all you need for pcapkit handy usage with PyShark engine. All reforming functions returns with a flag to indicate if usable for its caller.

Note

Due to the lack of functionality of PyShark, some functions of pcapkit may not be available with the PyShark engine.

pcapkit.toolkit.pyshark.tcp_traceflow(packet)[source]¶

Trace packet flow for TCP.

Parameters:

packet (Packet) – Scapy packet.

Returns:

A tuple of data for TCP reassembly.

If the packet can be used for TCP flow tracing. A packet can be reassembled if it contains TCP layer.
If the packet can be reassembled, then the dict mapping of data for TCP flow tracing (trace.tcp.packet) will be returned; otherwise, returns None.

Return type:

See also

pcapkit.toolkit.pyshark.ENCAP_TYPE_TO_LINKTYPE: dict[int, LinkType] = {1: <LinkType.ETHERNET: 1>, 2: <LinkType.IEEE802_5: 6>, 3: <LinkType.SLIP: 8>, 4: <LinkType.PPP: 9>, 6: <LinkType.FDDI: 10>, 7: <LinkType.RAW: 101>, 8: <LinkType.ARCNET_BSD: 7>, 9: <LinkType.ARCNET_LINUX: 129>, 10: <LinkType.ATM_RFC1483: 100>, 11: <LinkType.ATM_CLIP: 106>, 13: <LinkType.SUNATM: 123>, 15: <LinkType.NULL: 0>, 18: <LinkType.IP_OVER_FC: 122>, 19: <LinkType.PPP_WITH_DIR: 204>, 20: <LinkType.IEEE802_11: 105>, 21: <LinkType.IEEE802_11_PRISM: 119>, 23: <LinkType.IEEE802_11_RADIOTAP: 127>, 24: <LinkType.IEEE802_11_AVS: 163>, 25: <LinkType.LINUX_SLL: 113>, 26: <LinkType.FRELAY: 107>, 28: <LinkType.C_HDLC: 104>, 29: <LinkType.CISCO_IOS: 118>, 30: <LinkType.LTALK: 114>, 33: <LinkType.DOCSIS: 143>, 36: <LinkType.SDLC: 268>, 37: <LinkType.TZSP: 128>, 38: <LinkType.ENC: 109>, 39: <LinkType.PFLOG: 117>, 41: <LinkType.BLUETOOTH_HCI_H4: 187>, 42: <LinkType.MTP2: 140>, 43: <LinkType.MTP3: 141>, 44: <LinkType.LINUX_IRDA: 144>, 45: <LinkType.USER0: 147>, 46: <LinkType.USER1: 148>, 47: <LinkType.USER2: 149>, 48: <LinkType.USER3: 150>, 49: <LinkType.USER4: 151>, 50: <LinkType.USER5: 152>, 51: <LinkType.USER6: 153>, 52: <LinkType.USER7: 154>, 53: <LinkType.USER8: 155>, 54: <LinkType.USER9: 156>, 55: <LinkType.USER10: 157>, 56: <LinkType.USER11: 158>, 57: <LinkType.USER12: 159>, 58: <LinkType.USER13: 160>, 59: <LinkType.USER14: 161>, 60: <LinkType.USER15: 162>, 61: <LinkType.SYMANTEC_FIREWALL: 99>, 62: <LinkType.APPLE_IP_OVER_IEEE1394: 138>, 63: <LinkType.BACNET_MS_TP: 165>, 66: <LinkType.GPRS_LLC: 169>, 67: <LinkType.JUNIPER_ATM1: 137>, 68: <LinkType.JUNIPER_ATM2: 135>, 69: <LinkType.REDBACK_SMARTEDGE: 32>, 75: <LinkType.MTP2_WITH_PHDR: 139>, 76: <LinkType.JUNIPER_PPPOE: 167>, 77: <LinkType.GCOM_T1E1: 172>, 78: <LinkType.GCOM_SERIAL: 173>, 81: <LinkType.JUNIPER_MLPPP: 130>, 82: <LinkType.JUNIPER_MLFR: 131>, 83: <LinkType.JUNIPER_ETHER: 178>, 84: <LinkType.JUNIPER_PPP: 179>, 85: <LinkType.JUNIPER_FRELAY: 180>, 86: <LinkType.JUNIPER_CHDLC: 181>, 87: <LinkType.JUNIPER_GGSN: 133>, 88: <LinkType.LINUX_LAPD: 177>, 91: <LinkType.JUNIPER_VP: 183>, 92: <LinkType.USB_FREEBSD: 186>, 93: <LinkType.IEEE802_16_MAC_CPS: 188>, 95: <LinkType.USB_LINUX: 189>, 97: <LinkType.PPI: 192>, 98: <LinkType.ERF: 197>, 99: <LinkType.BLUETOOTH_HCI_H4_WITH_PHDR: 201>, 100: <LinkType.SITA: 196>, 101: <LinkType.SCCP: 142>, 103: <LinkType.IPMB_KONTRON: 199>, 104: <LinkType.IEEE802_15_4_WITHFCS: 195>, 105: <LinkType.X2E_XORAYA: 214>, 106: <LinkType.FLEXRAY: 210>, 107: <LinkType.LIN: 212>, 108: <LinkType.MOST: 211>, 109: <LinkType.CAN20B: 190>, 111: <LinkType.X2E_SERIAL: 213>, 112: <LinkType.I2C_LINUX: 209>, 113: <LinkType.IEEE802_15_4_NONASK_PHY: 215>, 115: <LinkType.USB_LINUX_MMAPPED: 220>, 121: <LinkType.FC_2: 224>, 122: <LinkType.FC_2_WITH_FRAME_DELIMS: 225>, 124: <LinkType.IPNET: 226>, 125: <LinkType.CAN_SOCKETCAN: 227>, 127: <LinkType.IEEE802_15_4_NOFCS: 230>, 129: <LinkType.IPV4: 228>, 130: <LinkType.IPV6: 229>, 131: <LinkType.LAPD: 203>, 132: <LinkType.DVB_CI: 235>, 133: <LinkType.MUX27010: 236>, 135: <LinkType.NETANALYZER: 240>, 136: <LinkType.NETANALYZER_TRANSPARENT: 241>, 138: <LinkType.MPEG_2_TS: 243>, 139: <LinkType.PPP_ETHER: 51>, 140: <LinkType.NFC_LLCP: 245>, 141: <LinkType.NFLOG: 239>, 146: <LinkType.DBUS: 231>, 147: <LinkType.AX25_KISS: 202>, 148: <LinkType.AX25: 3>, 149: <LinkType.SCTP: 248>, 151: <LinkType.JUNIPER_SERVICES: 136>, 152: <LinkType.USBPCAP: 249>, 153: <LinkType.RTAC_SERIAL: 250>, 154: <LinkType.BLUETOOTH_LE_LL: 251>, 155: <LinkType.WIRESHARK_UPPER_PDU: 252>, 157: <LinkType.STANAG_5066_D_PDU: 237>, 158: <LinkType.NETLINK: 253>, 159: <LinkType.BLUETOOTH_LINUX_MONITOR: 254>, 160: <LinkType.BLUETOOTH_BREDR_BB: 255>, 161: <LinkType.BLUETOOTH_LE_LL_WITH_PHDR: 256>, 171: <LinkType.PKTAP: 258>, 172: <LinkType.EPON: 259>, 173: <LinkType.IPMI_HPM_2: 260>, 174: <LinkType.LOOP: 108>, 177: <LinkType.ISO_14443: 264>, 178: <LinkType.GPF_T: 170>, 179: <LinkType.GPF_F: 171>, 180: <LinkType.IPOIB: 242>, 181: <LinkType.A429: 184>, 182: <LinkType.USB_DARWIN: 266>, 183: <LinkType.LORATAP: 270>, 184: <LinkType.EXP_ETHERNET: 2>, 185: <LinkType.VSOCK: 271>, 186: <LinkType.NORDIC_BLE: 272>, 197: <LinkType.JUNIPER_ST: 200>, 198: <LinkType.ETHERNET_MPACKET: 274>, 199: <LinkType.DOCSIS31_XRA31: 273>, 200: <LinkType.DISPLAYPORT_AUX: 275>, 204: <LinkType.EBHSCR: 279>, 205: <LinkType.VPP_DISPATCH: 280>, 206: <LinkType.IEEE802_15_4_TAP: 283>, 208: <LinkType.USB_2_0: 288>, 210: <LinkType.LINUX_SLL2: 276>, 211: <LinkType.Z_WAVE_SERIAL: 287>, 212: <LinkType.ETW: 290>, 214: <LinkType.ZBOSS_NCP: 292>, 215: <LinkType.USB_2_0_LOW_SPEED: 293>, 216: <LinkType.USB_2_0_FULL_SPEED: 294>, 217: <LinkType.USB_2_0_HIGH_SPEED: 295>, 219: <LinkType.AUERSWALD_LOG: 296>, 220: <LinkType.ATSC_ALP: 289>, 221: <LinkType.FIRA_UCI: 299>, 222: <LinkType.SILABS_DEBUG_CHANNEL: 298>, 223: <LinkType.MDB: 300>, 225: <LinkType.DECT_NR: 301>}¶

frame.encap_type – Wireshark’s internal WTAP_ENCAP_* number, which pyshark exposes as packet.frame_info.encap_type – to the matching LinkType member. This is tcp_traceflow()’s primary link-type source; FILTER_NAME_TO_LINKTYPE below is only its fallback.

A WTAP_ENCAP_* number is not a DLT: it is 25 where the DLT is 113, 15 where it is 0, and 2 where it is 6, so it needs this table rather than a cast. What it does do is distinguish encapsulations that the PDML root layer’s filter name cannot, which is the whole reason this table exists: sll is both LINUX_SLL (113) and LINUX_SLL2 (276), null is both NULL (0) and LOOP (108), raw is RAW (101), IPV4 (228) and IPV6 (229), ppp is PPP (9) and PPP_WITH_DIR (204), lapd is LAPD (203) and LINUX_LAPD (177). frame.encap_type separates every one of those pairs.

Every entry was measured, not transcribed, with editcap/tshark 4.6.9:

editcap -F pcap -T <encap> examples/captures/in.pcap out.pcap
# value := the ``network`` field at offset 20 of out.pcap's pcap file header
# key   := the ``frame.encap_type`` that ``tshark -r out.pcap -c 1 -T pdml`` then reports

so each pair is one round trip through Wireshark’s own wiretap/pcap-common.c, in the read direction pyshark actually exercises. The trailing comment on each line names the editcap -T encapsulation that produced it.

What the sweep does not cover, since that bounds this table: of the 226 encapsulations editcap -T accepts, 157 could be written as pcap from the Ethernet source above and the other 69 refused the rewrite, so they are untested. Those 157 yielded 153 distinct frame.encap_type keys, with no key mapping to two DLTs and no DLT reading back as two keys. 152 of them are below; frame.encap_type 32 (editcap -T hhdlc, DLT 121) is left out because LinkType has no member for 121. An encapsulation absent from this table raises rather than resolving to a near-miss DLT.

pcapkit.toolkit.pyshark.FILTER_NAME_TO_LINKTYPE: dict[str, LinkType] = {'alp': <LinkType.ATSC_ALP: 289>, 'ap1394': <LinkType.APPLE_IP_OVER_IEEE1394: 138>, 'atm': <LinkType.SUNATM: 123>, 'ax25': <LinkType.AX25: 3>, 'ax25_kiss': <LinkType.AX25_KISS: 202>, 'can': <LinkType.CAN_SOCKETCAN: 227>, 'chdlc': <LinkType.C_HDLC: 104>, 'clip': <LinkType.ATM_CLIP: 106>, 'dbus': <LinkType.DBUS: 231>, 'dect_nr': <LinkType.DECT_NR: 301>, 'docsis': <LinkType.DOCSIS: 143>, 'dpauxmon': <LinkType.DISPLAYPORT_AUX: 275>, 'ebhscr': <LinkType.EBHSCR: 279>, 'enc': <LinkType.ENC: 109>, 'epon': <LinkType.EPON: 259>, 'erf': <LinkType.ERF: 197>, 'eth': <LinkType.ETHERNET: 1>, 'exported_pdu': <LinkType.WIRESHARK_UPPER_PDU: 252>, 'fc': <LinkType.FC_2: 224>, 'fcsof': <LinkType.FC_2_WITH_FRAME_DELIMS: 225>, 'fddi': <LinkType.FDDI: 10>, 'flexray': <LinkType.FLEXRAY: 210>, 'fpp': <LinkType.ETHERNET_MPACKET: 274>, 'fr': <LinkType.FRELAY: 107>, 'ipfc': <LinkType.IP_OVER_FC: 122>, 'ipmi.trace': <LinkType.IPMI_HPM_2: 260>, 'ipnet': <LinkType.IPNET: 226>, 'ipoib': <LinkType.IPOIB: 242>, 'irlap': <LinkType.LINUX_IRDA: 144>, 'lin': <LinkType.LIN: 212>, 'llap': <LinkType.LTALK: 114>, 'llc': <LinkType.ATM_RFC1483: 100>, 'llcgprs': <LinkType.GPRS_LLC: 169>, 'loratap': <LinkType.LORATAP: 270>, 'mstp': <LinkType.BACNET_MS_TP: 165>, 'mtp3': <LinkType.MTP3: 141>, 'mux27010': <LinkType.MUX27010: 236>, 'nflog': <LinkType.NFLOG: 239>, 'nordic_ble': <LinkType.NORDIC_BLE: 272>, 'pflog': <LinkType.PFLOG: 117>, 'pktap': <LinkType.PKTAP: 258>, 'ppi': <LinkType.PPI: 192>, 'pppoes': <LinkType.PPP_ETHER: 51>, 'radiotap': <LinkType.IEEE802_11_RADIOTAP: 127>, 'redback': <LinkType.REDBACK_SMARTEDGE: 32>, 'rtacser': <LinkType.RTAC_SERIAL: 250>, 'sccp': <LinkType.SCCP: 142>, 'sctp': <LinkType.SCTP: 248>, 'sdlc': <LinkType.SDLC: 268>, 'silabs-dch': <LinkType.SILABS_DEBUG_CHANNEL: 298>, 'sita': <LinkType.SITA: 196>, 'tr': <LinkType.IEEE802_5: 6>, 'tzsp': <LinkType.TZSP: 128>, 'uci': <LinkType.FIRA_UCI: 299>, 'vpp': <LinkType.VPP_DISPATCH: 280>, 'vsock': <LinkType.VSOCK: 271>, 'wpan-nonask-phy': <LinkType.IEEE802_15_4_NONASK_PHY: 215>, 'xra': <LinkType.DOCSIS31_XRA31: 273>}¶

Wireshark display-filter name -> LinkType member, used by tcp_traceflow() only when the frame layer carries no frame.encap_type field for ENCAP_TYPE_TO_LINKTYPE above to key on – every capture measured for that table did carry one, so this is a defensive path rather than the usual one. PyShark takes the name verbatim from the PDML <proto name=...> attribute, which is Wireshark’s own dissector filter name – the third argument to proto_register_protocol() in the relevant epan/dissectors/packet-*.c – and that vocabulary is not LinkType’s: Ethernet’s filter name is eth, never ETHERNET.

Both entries were checked two ways: against Wireshark’s dissector registrations (packet-eth.c against WTAP_ENCAP_ETHERNET, packet-tr.c against WTAP_ENCAP_TOKEN_RING), and live with editcap -T to confirm which PDML root each encapsulation produces.

Every entry comes from the same sweep as ENCAP_TYPE_TO_LINKTYPE above: the root <proto name=...> of tshark -r out.pcap -c 1 -T pdml against the DLT in out.pcap’s own file header. The trailing comment on each line names the editcap -T encapsulation that produced it, so an entry can be re-checked, or corrected when upstream moves, by rerunning that one rewrite. Names are listed even where they already spell their LinkType member (docsis, fddi, pflog, …): there is deliberately no fallback onto a like-named member, because upper-casing the name is exactly what answered 101 for a rawip6 capture and 0 for a DLT_LOOP one – valid DLTs, wrong ones, and silent (#843).

Three classes of name are absent, all three measured rather than assumed:

Ambiguous – one name, several DLTs, and the PDML node does not say which arrived. These cannot be mapped at any size: user_dlt (16 DLTs), bluetooth (6), usb (5), usbll (4), raw (3), and arcnet, gfp, i2c, lapd, mtp2, netanalyzer, null, ppp, sll, wlan, wpan (2 each).
Pseudo-protocols – fake-field-wrapper, which pyshark reports as data and which was the root for 29 of the swept encapsulations (no dissector), and _ws.malformed, the root for the one capture tshark could not parse. Neither names a link type.
Unswept – the 69 encapsulations editcap -T would not write as pcap from an Ethernet source. No evidence either way was gathered for them.

Two caveats on what “unambiguous” means here. It means unambiguous within the 157 swept encapsulations: one of the 69 unswept could still root at the same name (ether-nettl and tr-nettl are the obvious candidates, for eth and tr). And five of the entries name a payload dissector that happened to be the outermost PDML node for exactly one encapsulation – llc, sctp, pppoes, fpp and irlap – rather than a link-layer dissector registered against a WTAP_ENCAP_*. Both are why this table is the fallback and frame.encap_type is the primary key; eth and tr additionally check out against Wireshark’s own registrations (packet-eth.c on WTAP_ENCAP_ETHERNET, packet-tr.c on WTAP_ENCAP_TOKEN_RING).

Auxiliary Functions¶

pcapkit.toolkit.pyshark.packet2dict(packet)[source]¶

Convert PyShark packet into dict.

Parameters:: packet (Packet) – Scapy packet.
Return type:: dict[str, Any]
Returns:: A dict mapping of packet data.

PyPCAP Tools¶

pcapkit.toolkit.pypcap contains all you need for pcapkit handy usage with PyPCAP engine. All reforming functions returns with a flag to indicate if usable for its caller.

Note

PyPCAP performs no protocol dissection, so the reassembly and flow tracing adapters below cannot be implemented. They are defined all the same, so that reaching for one fails with an explanatory UnsupportedCall rather than an ImportError.

pcapkit.toolkit.pypcap.ipv4_reassembly(packet, *, count=-1)[source]¶

Make data for IPv4 reassembly.

Parameters:

packet (bytes) – Raw packet bytes.
count (int) – Packet index. If not provided, default to -1.

Raises:

UnsupportedCall – Always, as PyPCAP provides no IPv4 layer to read.

Return type:

pcapkit.toolkit.pypcap.ipv6_reassembly(packet, *, count=-1)[source]¶

Make data for IPv6 reassembly.

Parameters:

packet (bytes) – Raw packet bytes.
count (int) – Packet index. If not provided, default to -1.

Raises:

UnsupportedCall – Always, as PyPCAP provides no IPv6 layer to read.

Return type:

pcapkit.toolkit.pypcap.tcp_reassembly(packet, *, count=-1)[source]¶

Make data for TCP reassembly.

Parameters:

packet (bytes) – Raw packet bytes.
count (int) – Packet index. If not provided, default to -1.

Raises:

UnsupportedCall – Always, as PyPCAP provides no TCP layer to read.

Return type:

pcapkit.toolkit.pypcap.tcp_traceflow(packet, timestamp, *, data_link, count=-1)[source]¶

Trace packet flow for TCP.

Parameters:

packet (bytes) – Raw packet bytes.
timestamp (float) – Timestamp of the packet.
data_link (LinkType) – Data link layer protocol (from the capture handle).
count (int) – Packet index. If not provided, default to -1.

Raises:

UnsupportedCall – Always, as PyPCAP provides no TCP layer to read.

Return type:

Auxiliary Functions¶

pcapkit.toolkit.pypcap.packet2chain(packet, *, data_link)[source]¶

Fetch PyPCAP packet protocol chain.

Parameters:

packet (bytes) – Raw packet bytes, as returned by pcap.pcap iteration.
data_link (LinkType) – Data link type, from the capture handle.

Return type:

str

Returns:

Colon (:) separated list of protocol chain.

Note

As PyPCAP does not dissect the packet, the chain is only ever the link layer type followed by Raw, e.g. ETHERNET:Raw.

pcapkit.toolkit.pypcap.packet2dict(packet, timestamp, *, data_link)[source]¶

Convert PyPCAP packet into dict.

Parameters:

packet (bytes) – Raw packet bytes, as returned by pcap.pcap iteration.
timestamp (float) – Timestamp of packet, as returned by pcap.pcap iteration.
data_link (LinkType) – Data link type, from the capture handle.

Returns:

A dict mapping of packet data.

Return type:

Note

The mapping carries the captured bytes verbatim rather than a decoded protocol tree, since PyPCAP does not decode anything.

pcap-ct Tools¶

pcapkit.toolkit.pcap_ct contains all you need for pcapkit handy usage with pcap-ct engine. All reforming functions returns with a flag to indicate if usable for its caller.

Note

pcap-ct is an independent reimplementation of the PyPCAP interface, so this module is deliberately a sibling of pcapkit.toolkit.pypcap rather than an alias of it: each engine names its own adapter, so a change made for one cannot quietly alter the other.

Like PyPCAP it performs no protocol dissection, so the reassembly and flow tracing adapters below cannot be implemented. They are defined all the same, so that reaching for one fails with an explanatory UnsupportedCall rather than an ImportError.

pcapkit.toolkit.pcap_ct.ipv4_reassembly(packet, *, count=-1)[source]¶

Make data for IPv4 reassembly.

Parameters:

packet (bytes) – Raw packet bytes.
count (int) – Packet index. If not provided, default to -1.

Raises:

UnsupportedCall – Always, as pcap-ct provides no IPv4 layer to read.

Return type:

pcapkit.toolkit.pcap_ct.ipv6_reassembly(packet, *, count=-1)[source]¶

Make data for IPv6 reassembly.

Parameters:

packet (bytes) – Raw packet bytes.
count (int) – Packet index. If not provided, default to -1.

Raises:

UnsupportedCall – Always, as pcap-ct provides no IPv6 layer to read.

Return type:

pcapkit.toolkit.pcap_ct.tcp_reassembly(packet, *, count=-1)[source]¶

Make data for TCP reassembly.

Parameters:

packet (bytes) – Raw packet bytes.
count (int) – Packet index. If not provided, default to -1.

Raises:

UnsupportedCall – Always, as pcap-ct provides no TCP layer to read.

Return type:

pcapkit.toolkit.pcap_ct.tcp_traceflow(packet, timestamp, *, data_link, count=-1)[source]¶

Trace packet flow for TCP.

Parameters:

packet (bytes) – Raw packet bytes.
timestamp (float) – Timestamp of the packet.
data_link (LinkType) – Data link layer protocol (from the capture handle).
count (int) – Packet index. If not provided, default to -1.

Raises:

UnsupportedCall – Always, as pcap-ct provides no TCP layer to read.

Return type:

Auxiliary Functions¶

pcapkit.toolkit.pcap_ct.packet2chain(packet, *, data_link)[source]¶

Fetch pcap-ct packet protocol chain.

Parameters:

packet (bytes) – Raw packet bytes, as returned by pcap.pcap iteration.
data_link (LinkType) – Data link type, from the capture handle.

Return type:

str

Returns:

Colon (:) separated list of protocol chain.

Note

As pcap-ct does not dissect the packet, the chain is only ever the link layer type followed by Raw, e.g. ETHERNET:Raw.

pcapkit.toolkit.pcap_ct.packet2dict(packet, timestamp, *, data_link)[source]¶

Convert pcap-ct packet into dict.

Parameters:

packet (bytes) – Raw packet bytes, as returned by pcap.pcap iteration.
timestamp (float) – Timestamp of packet, as returned by pcap.pcap iteration.
data_link (LinkType) – Data link type, from the capture handle.

Returns:

A dict mapping of packet data.

Return type:

Note

The mapping carries the captured bytes verbatim rather than a decoded protocol tree, since pcap-ct does not decode anything.

PyPCAPFile Tools¶

pcapkit.toolkit.pypcapfile contains all you need for pcapkit handy usage with PyPCAPFile engine. All reforming functions returns with a flag to indicate if usable for its caller.

Note

PyPCAPFile has no IPv6 decoder, so ipv6_reassembly() raises UnsupportedCall rather than returning None – which would be indistinguishable from “this frame carries no IPv6 fragment”.

pcapkit.toolkit.pypcapfile.ipv4_reassembly(packet, *, count=-1)[source]¶

Make data for IPv4 reassembly.

Parameters:

packet (pcap_packet) – PyPCAPFile packet.
count (int) – Packet index. If not provided, default to -1.

Return type:

Returns:

Data for IPv4 reassembly.

If the packet can be used for IPv4 reassembly. A packet can be reassembled if it contains an IPv4 layer (pcapfile.protocols.network.ip.IP) and the DF flag is False.
If the packet can be reassembled, then the dict mapping of data for IPv4 reassembly (reasm.ipv4.packet) will be returned; otherwise, returns None.

Raises:

ProtocolError – If ipv4.src or ipv4.dst cannot be parsed as an IPv4 address.

pcapkit.toolkit.pypcapfile.ipv6_reassembly(packet, *, count=-1)[source]¶

Make data for IPv6 reassembly.

Parameters:

packet (pcap_packet) – PyPCAPFile packet.
count (int) – Packet index. If not provided, default to -1.

Raises:

UnsupportedCall – Always, as PyPCAPFile has no IPv6 decoder.

Return type:

pcapkit.toolkit.pypcapfile.tcp_reassembly(packet, *, count=-1)[source]¶

Make data for TCP reassembly.

Parameters:

packet (pcap_packet) – PyPCAPFile packet.
count (int) – Packet index. If not provided, default to -1.

Return type:

pcapkit.foundation.reassembly.tcp.TCP

Returns:

Data for TCP reassembly.

If the packet can be used for TCP reassembly. A packet can be reassembled if it contains an IPv4 layer carrying a TCP segment.
If the packet can be reassembled, then the dict mapping of data for TCP reassembly (reasm.tcp.packet) will be returned; otherwise, returns None.

Raises:

ProtocolError – If ipv4.src or ipv4.dst cannot be parsed as an IPv4 address.

See also

pcapkit.toolkit.pypcapfile.tcp_traceflow(packet, *, data_link, count=-1)[source]¶

Trace packet flow for TCP.

Parameters:

packet (pcap_packet) – PyPCAPFile packet.
data_link (LinkType) – Data link layer protocol (from the savefile header).
count (int) – Packet index. If not provided, default to -1.

Return type:

Returns:

Data for TCP flow tracing.

If the packet can be used for TCP flow tracing. A packet can be traced if it contains an IPv4 layer carrying a TCP segment.
If the packet can be traced, then the dict mapping of data for TCP flow tracing (trace.tcp.packet) will be returned; otherwise, returns None.

Raises:

ProtocolError – If ipv4.src or ipv4.dst cannot be parsed as an IPv4 address.

See also

Auxiliary Functions¶

pcapkit.toolkit.pypcapfile.packet2timestamp(packet)[source]¶

Calculate the timestamp of a PyPCAPFile packet.

Parameters:: packet (pcap_packet) – PyPCAPFile packet.
Return type:: float
Returns:: Timestamp of the packet, in seconds since the epoch.

Note

PyPCAPFile keeps the two halves of the per-packet timestamp apart, and the sub-second half is nanoseconds rather than microseconds when the savefile carries the nanosecond magic number – which is recorded on the savefile header as ns_resolution.

pcapkit.toolkit.pypcapfile.ipv4_header(ipv4)[source]¶

Rebuild the raw header bytes of a PyPCAPFile IPv4 packet.

Parameters:: ipv4 (IP) – PyPCAPFile IPv4 packet.
Return type:: bytes
Returns:: Raw IPv4 header bytes, options included.

Note

PyPCAPFile discards the header bytes once decoded, but it retains every IPv4 header field plus the options blob, so this reconstruction is byte-exact rather than approximate.

Raises:: ProtocolError – If ipv4.src or ipv4.dst cannot be parsed as an IPv4 address.

pcapkit.toolkit.pypcapfile.packet2chain(packet, *, data_link)[source]¶

Fetch PyPCAPFile packet protocol chain.

Parameters:

packet (pcap_packet) – PyPCAPFile packet.
data_link (LinkType) – Data link type, from the savefile header.

Return type:

str

Returns:

Colon (:) separated list of protocol chain.

Note

The chain reports what PyPCAPFile actually decoded and no more, so it ends in Raw – the transport segment is left undecoded on purpose, see the module notes.

pcapkit.toolkit.pypcapfile.packet2dict(packet, *, data_link)[source]¶

Convert PyPCAPFile packet into dict.

Parameters:

packet (pcap_packet) – PyPCAPFile packet.
data_link (LinkType) – Data link type, from the savefile header.

Returns:

A dict mapping of packet data.

Return type: