diff --git a/docs/source/pcapkit/foundation/engines/3rdparty.rst b/docs/source/pcapkit/foundation/engines/3rdparty.rst index 0c03be41df..982ba14753 100644 --- a/docs/source/pcapkit/foundation/engines/3rdparty.rst +++ b/docs/source/pcapkit/foundation/engines/3rdparty.rst @@ -64,6 +64,25 @@ support, as is used by :class:`pcapkit.foundation.extraction.Extractor`. .. _DPKT: https://dpkt.readthedocs.io +.. important:: + + On PCAP-NG, `DPKT`_ yields **Enhanced Packet Blocks and (obsolete) Packet + Blocks only**. ``dpkt.pcapng.Reader.__iter__`` skips every other block type + without a warning (``# just ignore other blocks``, as of ``dpkt`` 1.9.8), and + that includes the **Simple Packet Block**, which carries a packet just as an + Enhanced Packet Block does. Such packets are silently missing from this + engine's output, and the frames after them are numbered as if they had never + been captured. + + Reading :file:`examples/captures/test.pcapng` -- four Enhanced Packet Blocks + and one Simple Packet Block, across two sections -- this engine gives four + frames where the default engine and + :class:`~pcapkit.foundation.engines.scapy.Scapy` give five; the missing one is + frame 4, the Simple Packet Block. The second Section Header Block is not the + cause: the Enhanced Packet Block after it is read. This is a limitation of + `DPKT`_, not of :mod:`pcapkit`, so read a capture that may contain Simple + Packet Blocks with the default engine instead. + .. autoclass:: pcapkit.foundation.engines.dpkt.DPKT :no-members: :show-inheritance: diff --git a/pcapkit/foundation/engines/dpkt.py b/pcapkit/foundation/engines/dpkt.py index bbbd12076e..d7474dca28 100644 --- a/pcapkit/foundation/engines/dpkt.py +++ b/pcapkit/foundation/engines/dpkt.py @@ -39,6 +39,13 @@ class DPKT(EngineBase['DPKTPacket']): """DPKT engine support. + On PCAP-NG, `DPKT`_'s reader yields Enhanced Packet Blocks and (obsolete) + Packet Blocks only, and skips every other block without a warning -- the + Simple Packet Block included. A packet carried in a Simple Packet Block is + therefore missing from this engine's output; the default engine reads it. + + .. _DPKT: https://dpkt.readthedocs.io + Args: extractor: :class:`~pcapkit.foundation.extraction.Extractor` instance.