PCAP-NG File Format

Removed in version 1.6.0: pcapkit.protocols.misc.pcapng.PacketDirection, pcapkit.protocols.misc.pcapng.PacketReception and pcapkit.protocols.misc.pcapng.WireGuardKeyLabel, with no alias: they are in this module, and pcapkit.protocols.misc.pcapng exports the protocol class alone (#2534). pcapkit.protocols.misc.pcapng.PAT_EUI_ADDR and pcapkit.protocols.misc.pcapng.PAT_MAC_ADDR, with no alias: _read_mac_addr() and _make_mac_addr() read and make the address (#2614).

pcapkit.protocols.misc.pcapng.protocol contains PCAPNG, which implements an extractor for PCAP-NG file format [*], and the PacketDirection, PacketReception and WireGuardKeyLabel enumerations.

Changed in version 1.5.0: A block rebuilds as it was parsed, byte for byte: its lengths, padding, byte order, flag bits and repeated options are kept, and so is a block that is unknown, malformed, shorter than its fixed fields or cut short (#1272, #1273, #1276, #1277, #1278, #1279, #1280, #1281, #1282, #1283, #1284, #1382, #1383, #1384, #1405, #1413, #1414, #1422, #1470). A packet block keeps the octets it captured (#646); an option running past its block’s option area leaves the whole area kept as captured in options_raw, with a ProtocolWarning, where it was read as zeros (#594, #1325); a truncated capture does not raise ValueError (#678); and timestamp_epoch is not shifted by the host’s timezone (#361).

class pcapkit.protocols.misc.pcapng.protocol.PCAPNG(file=None, length=None, **kwargs)[source]

Bases: ProtocolBase[PCAPNG, PCAPNG]

PCAP-NG file block extractor.

The class supports parsing of the following protocols, which are registered in the self.__proto__ attribute:

Index

Protocol

pcapkit.const.reg.linktype.LinkType.NULL

pcapkit.protocols.link.loopback.protocol.Loopback

pcapkit.const.reg.linktype.LinkType.ETHERNET

pcapkit.protocols.link.ethernet.protocol.Ethernet

pcapkit.const.reg.linktype.LinkType.IEEE802_11

pcapkit.protocols.link.ieee802_11.protocol.IEEE802_11

pcapkit.const.reg.linktype.LinkType.FRELAY

pcapkit.protocols.link.frad.protocol.FRAD

pcapkit.const.reg.linktype.LinkType.LOOP

pcapkit.protocols.link.loopback.protocol.Loopback

pcapkit.const.reg.linktype.LinkType.LINUX_SLL

pcapkit.protocols.link.linux_sll1.protocol.LinuxSLL1

pcapkit.const.reg.linktype.LinkType.IEEE802_11_RADIOTAP

pcapkit.protocols.link.radiotap.protocol.Radiotap

pcapkit.const.reg.linktype.LinkType.IPV4

pcapkit.protocols.internet.ipv4.protocol.IPv4

pcapkit.const.reg.linktype.LinkType.IPV6

pcapkit.protocols.internet.ipv6.protocol.IPv6

pcapkit.const.reg.linktype.LinkType.LINUX_SLL2

pcapkit.protocols.link.linux_sll2.protocol.LinuxSLL2

pcapkit.const.reg.linktype.LinkType.RAW has no entry of its own: its data is dispatched as IPV4 or IPV6 by the version nibble of its first octet, see _dispatch_linktype().

The class supports parsing of the following block types, which are registered in the self.__block__ attribute:

Block Type

Block Parser

Block Constructor

Section_Header_Block

_read_block_shb()

_make_block_shb()

Interface_Description_Block

_read_block_idb()

_make_block_idb()

Enhanced_Packet_Block

_read_block_epb()

_make_block_epb()

Simple_Packet_Block

_read_block_spb()

_make_block_spb()

Name_Resolution_Block

_read_block_nrb()

_make_block_nrb()

Interface_Statistics_Block

_read_block_isb()

_make_block_isb()

systemd_Journal_Export_Block

_read_block_systemd()

_make_block_systemd()

Decryption_Secrets_Block

_read_block_dsb()

_make_block_dsb()

Custom_Block_that_rewriters_can_copy_into_new_files

_read_block_cb()

_make_block_cb()

Custom_Block_that_rewriters_should_not_copy_into_new_files

_read_block_cb()

_make_block_cb()

Packet_Block

_read_block_packet()

_make_block_packet()

The class supports parsing of the following option types, which are registered in the self.__option__ attribute:

Option Type

Option Parser

Option Constructor

opt_endofopt

_read_option_endofopt()

_make_option_endofopt()

opt_comment

_read_option_comment()

_make_option_comment()

opt_custom_2988, opt_custom_2989, opt_custom_19372, opt_custom_19373

_read_option_custom()

_make_option_custom()

if_name

_read_option_if_name()

_make_option_if_name()

if_description

_read_option_if_description()

_make_option_if_description()

if_IPv4addr

_read_option_if_ipv4()

_make_option_if_ipv4()

if_IPv6addr

_read_option_if_ipv6()

_make_option_if_ipv6()

if_MACaddr

_read_option_if_mac()

_make_option_if_mac()

if_EUIaddr

_read_option_if_eui()

_make_option_if_eui()

if_speed

_read_option_if_speed()

_make_option_if_speed()

if_tsresol

_read_option_if_tsresol()

_make_option_if_tsresol()

if_tzone

_read_option_if_tzone()

_make_option_if_tzone()

if_filter

_read_option_if_filter()

_make_option_if_filter()

if_os

_read_option_if_os()

_make_option_if_os()

if_fcslen

_read_option_if_fcslen()

_make_option_if_fcslen()

if_tsoffset

_read_option_if_tsoffset()

_make_option_if_tsoffset()

if_hardware

_read_option_if_hardware()

_make_option_if_hardware()

if_txspeed

_read_option_if_txspeed()

_make_option_if_txspeed()

if_rxspeed

_read_option_if_rxspeed()

_make_option_if_rxspeed()

epb_flags

_read_option_epb_flags()

_make_option_epb_flags()

epb_hash

_read_option_epb_hash()

_make_option_epb_hash()

epb_dropcount

_read_option_epb_dropcount()

_make_option_epb_dropcount()

epb_packetid

_read_option_epb_packetid()

_make_option_epb_packetid()

epb_queue

_read_option_epb_queue()

_make_option_epb_queue()

epb_verdict

_read_option_epb_verdict()

_make_option_epb_verdict()

ns_dnsname

_read_option_ns_dnsname()

_make_option_ns_dnsname()

ns_dnsIP4addr

_read_option_ns_dnsipv4()

_make_option_ns_dnsipv4()

ns_dnsIP6addr

_read_option_ns_dnsipv6()

_make_option_ns_dnsipv6()

isb_starttime

_read_option_isb_starttime()

_make_option_isb_starttime()

isb_endtime

_read_option_isb_endtime()

_make_option_isb_endtime()

isb_ifrecv

_read_option_isb_ifrecv()

_make_option_isb_ifrecv()

isb_ifdrop

_read_option_isb_ifdrop()

_make_option_isb_ifdrop()

isb_filteraccept

_read_option_isb_filteraccept()

_make_option_isb_filteraccept()

isb_osdrop

_read_option_isb_osdrop()

_make_option_isb_osdrop()

isb_usrdeliv

_read_option_isb_usrdeliv()

_make_option_isb_usrdeliv()

pack_flags

_read_option_pack_flags()

_make_option_pack_flags()

pack_hash

_read_option_pack_hash()

_make_option_pack_hash()

The class supports parsing of the following name resolution record types, which are registered in the self.__record__ attribute:

Record Type

Record Parser

Record Constructor

nrb_record_end

_read_record_end()

_make_record_end()

nrb_record_ipv4

_read_record_ipv4()

_make_record_ipv4()

nrb_record_ipv6

_read_record_ipv6()

_make_record_ipv6()

The class supports parsing of the following decryption secrets types, which are registered in the self.__secrets__ attribute:

Secrets Type

Secrets Parser

Secrets Constructor

TLS_Key_Log

_read_secrets_tls()

_make_secrets_tls()

WireGuard_Key_Log

_read_secrets_wireguard()

_make_secrets_wireguard()

ZigBee_NWK_Key

_read_secrets_zigbee_nwk()

_make_secrets_zigbee_nwk()

ZigBee_APS_Key

_read_secrets_zigbee_aps()

_make_secrets_zigbee_aps()

Changed in version 1.5.0: context returns the caller supplied ContextRegistry inherited from ProtocolBase, on every block. The block’s section Context, which context returned through 1.4.x, is section_context (#2172).

Changed in version 1.6.0:

  • Each enumeration field of make() and of the block and option makers, and the code of each option and the type of each name resolution record given to a block maker, takes a member or an int code, resolved with the enumeration’s get, an option code in the block’s namespace; a name, a bool for a field wider than one bit, or a code the field cannot carry raises ProtocolError, rather than resolving against an enumeration inferred from the caller’s frame, writing a different value or raising another exception (#2594).

  • An option or a name resolution record given to a block maker as raw octets too short to hold its 16-bit code raises ProtocolError, rather than reading empty octets as code 0 and writing an end-of-options or end-of-records marker for them (#2723).

Removed in version 1.6.0: The type_default, type_namespace and type_reversed arguments of make(), and the _default, _namespace and _reversed arguments that went with each enumeration field of the block and option makers – linktype, secrets_type, filter, direction, reception, algorithm and verdict; resolve a name with resolve_index() first (#2594).

PACKET_TYPES = (<BlockType.Enhanced_Packet_Block: 6>, <BlockType.Simple_Packet_Block: 3>, <BlockType.Packet_Block: 2>)

Blocks that carry a captured packet.

SHORT_HEADER_TYPES = {<BlockType.Interface_Description_Block: 1>: 20, <BlockType.Section_Header_Block: 168627466>: 28}

Header blocks mapped to the octets their fixed fields span, so that a shorter Block Total Length is kept as captured (see _read_block_short_header()). The lengths are read from their one home, pcapkit.protocols.misc.pcapng.schema.BLOCK_MINIMUM (#1739).

__proto__: DefaultDict[int | LinkType, ModuleDescriptor[ProtocolBase] | Type[ProtocolBase]]

Protocol index mapping for decoding the next layer; see self._decode_next_layer and self._import_next_layer. Each value is a ModuleDescriptor naming the module and class, or a ProtocolBase subclass.

__proto_key__: ClassVar[tuple[Type[EnumRegistry], bool]]

What __proto__ is keyed by – the enum a key must be a member of, and whether a bare int is a valid key too. Declared by the class owning the registry, so register_protocol_code() checks a code= key as register_pcapng() does; Frame, whose registry is keyed by the same enum, declares its own (#2268).

__block__: DefaultDict[BlockType | int, str | tuple[Callable[[BlockType, PCAPNG], PCAPNG], Callable[[PCAPNG | None, Any], BlockType]]]

Block type to method mapping. A str value names the _read_block_${name} and _make_block_${name} methods, which fall back to _read_block_unknown and _make_block_unknown when not defined, as an unregistered code does; any other value is a (parser, constructor) pair of callables.

__option__: DefaultDict[OptionType | Tuple[str, int], str | tuple[Callable[[Option, OrderedMultiDict[OptionType, Option]], Option], Callable[[OptionType, Option | None, Any], Option]]]

Block option type to method mapping. A str value names the _read_option_${name} and _make_option_${name} methods, which fall back to _read_option_unknown and _make_option_unknown when not defined, as an unregistered code does; any other value is a (parser, constructor) pair of callables.

__record__: DefaultDict[RecordType | int, str | tuple[Callable[[NameResolutionRecord, OrderedMultiDict[RecordType, NameResolutionRecord]], NameResolutionRecord], Callable[[RecordType, NameResolutionRecord | None, Any], NameResolutionRecord]]]

Name Resolution Block record type to method mapping. A str value names the _read_record_${name} and _make_record_${name} methods, which fall back to _read_record_unknown and _make_record_unknown when not defined, as an unregistered code does; any other value is a (parser, constructor) pair of callables.

__secrets__: DefaultDict[SecretsType | int, str | tuple[Callable[[DSBSecrets, DecryptionSecretsBlock], DSBSecrets], Callable[[SecretsType, DSBSecrets | None, Any], DSBSecrets]]]

Decryption secrets type to method mapping. A str value names the _read_secrets_${name} and _make_secrets_${name} methods, which fall back to _read_secrets_unknown and _make_secrets_unknown when not defined, as an unregistered code does; any other value is a (parser, constructor) pair of callables.

property name: str

Name of corresponding protocol.

property length: int

Block total length of corresponding protocol.

Note

This is the wire’s Block Total Length – the whole block, trailing length field included – and not a header length. The two are the same thing for a protocol whose payload runs to the end of its buffer, which is why Protocol.length does not distinguish them, but a PCAP-NG block carries a trailer. self.packet is overridden accordingly.

property packet: Packet

Header and payload octets of the current block.

A PCAP-NG block is not a header followed by a payload. The captured octets sit in the middle of a packet block, ahead of the option list and the trailing Block Total Length, so no single split point expresses the shape and the inherited Protocol.packet – which reads self.length octets of header and takes everything after as payload – cannot produce it. Since self.length is the Block Total Length, that split would put the entire block in the header and leave the payload empty, so packet would be b'' while captured_len declared the octets.

The payload is therefore the block schema’s __payload__ field, which is where the schema layer put the captured octets, and the header is the block octets ahead of it. The block types that carry captured octets – PACKET_TYPES, i.e. the Enhanced Packet Block, the Simple Packet Block and the obsolete Packet Block – each place the payload at a different offset, so the offset is summed from the octets the schema actually unpacked rather than hard-coded per block type. A block declaring no payload field is all header and no payload.

property section_context: Context

Section context of current PCAP-NG block.

Raises:

UnsupportedCall – If the block holds no section context: a block given ctx=None, or a Section Header Block, which starts a section rather than reading one, unless the PCAPNG engine read it and assigned it the section it opens.

Added in version 1.5.0: Renamed from context, with no alias. context is the one inherited from ProtocolBase, the caller supplied parsing context of pcapkit.corekit.context (#2172).

property byteorder: Literal['big', 'little']

Byte order of the current block.

property nanosecond: bool

Whether the timestamp resolution is finer than microseconds.

property ts_resolution: int

Timestamp resolution of the current block, in units per second.

property ts_offset: int

Timestamp offset of the current block, in seconds.

property ts_timezone: timezone

Timezone of the current block.

Defaults to UTC when the capture names no if_tzone, for the reason given in self._get_timezone.

property linktype: LinkType

Data link layer protocol type.

Raises:

UnsupportedCall – If current block is not a valid packet block, i.e., EPB, SPB or obsolete Packet Block.

property block: BlockType

PCAP-NG block type.

classmethod register(code, protocol)[source]

Register a new protocol class.

Notes

The fully qualified class name of the new protocol class should be {protocol.module}.{protocol.name}.

Parameters:
Raises:

pcapkit.utilities.exceptions.RegistryError – If protocol is not a class, or not a ProtocolBase subclass.

Warns:

pcapkit.utilities.warnings.RegistryWarning – If this link type is already registered against PCAP-NG blocks, naming the displaced entry and its replacement so a caller can tell what was lost. Fires only when the incumbent differs from the replacement, and an unresolved module descriptor counts as different from the class it names; handing back the stored entry, or a descriptor equal to it, is a silent no-op that keeps it. This registry is separate from the PCAP one, so register_linktype() writing to both cannot make either warn about the other. See Protocol.register for the shipped descriptor a restore puts back (#1504).

classmethod register_block(code, meth)[source]

Register a block parser.

Parameters:
Warns:

RegistryWarning – If a different entry is already registered for code; it is overwritten. Handing back the entry already stored, or one equal to it, is a silent no-op. The entry code shipped with is accepted like any other, so an override can be undone (#1362, #1363).

classmethod register_option(code, meth)[source]

Register an option parser.

Parameters:
Warns:

RegistryWarning – If a different entry is already registered for code; it is overwritten. Handing back the entry already stored, or one equal to it, is a silent no-op. The entry code shipped with is accepted like any other, so an override can be undone (#1362, #1363).

classmethod register_record(code, meth)[source]

Register a name resolution record parser.

Parameters:
Warns:

RegistryWarning – If a different entry is already registered for code; it is overwritten. Handing back the entry already stored, or one equal to it, is a silent no-op. The entry code shipped with is accepted like any other, so an override can be undone (#1362, #1363).

classmethod register_secrets(code, meth)[source]

Register a decryption secrets parser.

Parameters:
Warns:

RegistryWarning – If a different entry is already registered for code; it is overwritten. Handing back the entry already stored, or one equal to it, is a silent no-op. The entry code shipped with is accepted like any other, so an override can be undone (#1362, #1363).

index(name)[source]

Call ProtoChain.index.

Parameters:

name (str | ProtocolBase | Type[ProtocolBase]) – name to be searched

Return type:

int

Returns:

First index of name.

Raises:

IndexNotFound – if name is not present

pack(**kwargs)[source]

Pack (construct) packet data.

Parameters:

**kwargs (Any) – Arbitrary keyword arguments.

Return type:

bytes

Returns:

Constructed packet data.

Notes

The special keyword argument __packet__ passes the global packet data to underlying methods, for when the current instance does not have it.

As in Protocol.pack, the header is made on a copy outside construction, so the instance keeps its own header, block type, byte order and option counts (#1769).

unpack(length=None, **kwargs)[source]

Unpack (parse) packet data.

Parameters:

  • length (int | None) – Length of packet data.

  • **kwargs (Any) – Arbitrary keyword arguments.

Return type:

PCAPNG

Returns:

Parsed packet data.

Notes

The special keyword argument __packet__ passes the global packet data to underlying methods, for when the current instance does not have it.

A block handed to make() as raw bytes is written back verbatim past the Block Type, so the schema make() returns holds the octets rather than the block’s fields. Those octets are parsed here, off the buffer pack() has just filled, which is what a reader of the file would do with them (#2354).

read(length=None, *, _read=True, _seek_set=0, **kwargs)[source]

Read PCAP-NG file blocks.

Structure of PCAP-NG file blocks:

                       1                   2                   3
   0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
  +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
0 |                          Block Type                           |
  +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
4 |                      Block Total Length                       |
  +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
8 /                          Block Body                           /
  /              variable length, padded to 32 bits               /
  +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
  |                      Block Total Length                       |
  +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
Parameters:

  • length (int | None) – Length of data to be read.

  • _read – If the class is called in a parsing scenario.

  • _seek_set – File offset before reading.

  • **kwargs (Any) – Arbitrary keyword arguments.

Return type:

PCAPNG

Returns:

Parsed packet data.

make(type=BlockType.Simple_Packet_Block, block=b'', **kwargs)[source]

Make PCAP-NG block data.

Parameters:
Return type:

PCAPNG

Returns:

Constructed packet data.

Raises:

ProtocolError – If type is a name, a bool, or a member or code the 32-bit Block Type field cannot carry; or if block is none of the forms this maker reads – raw bytes, a dict of block arguments, a PCAPNG data model or a Schema.

__post_init__(file=None, length=None, *, num, sct, ctx, **kwargs)[source]

Initialisation.

Overloads:
Parameters:

  • file (IO[bytes] | bytes | None) – Source packet stream.

  • length (int | None) – Length of packet data.

  • num (int) – Frame index number.

  • sct (int) – Section index number.

  • ctx (Context) – Section context of the PCAP-NG file.

  • **kwargs (Any) – Arbitrary keyword arguments.

Notes

The first block has num 0 and ctx None, marking it as the section header block.

See also

For construction arguments, please refer to make().

__length_hint__()[source]

Return an estimated length for the object.

Return type:

Literal[12]

__index__()[source]

Index of the block.

Parameters:

self (PCAPNG | None) – PCAPNG object or None.

Return type:

int

Returns:

If the object is initialised, i.e. self._fnum exists, and is of a packet block (EPB, SPB or Packet), returns the block index number of itself; else raises UnsupportedCall.

Raises:

UnsupportedCall – If called on the class, or on a block that is not a packet block.

classmethod _make_data(data)[source]

Create key-value pairs from data for protocol construction.

Parameters:

data (PCAPNG) – protocol data

Return type:

dict[str, Any]

Returns:

Key-value pairs for protocol construction.

_read_block_short(schema, *, header)[source]

Read a PCAP-NG EPB or packet block (obsolete) shorter than its fixed fields.

The fixed fields of either block span 32 octets, so a smaller Block Total Length cannot hold them.

Parameters:
Return type:

EnhancedPacketBlock | PacketBlock

Returns:

Parsed packet data, with the fixed fields the block holds and zero for those it does not, no packet data and no options. The block body is kept as block_raw, which the block’s make writes back verbatim, so the block rebuilds at the length it declared (#1414).

_make_block_short(block)[source]

Make a PCAP-NG EPB, packet block (obsolete), SHB or IDB kept as captured.

Parameters:

block (EnhancedPacketBlock | PacketBlock | SectionHeaderBlock | InterfaceDescriptionBlock) – Block data model, whose block_raw holds the body of a block shorter than its fixed fields (see _read_block_short() and _read_block_short_header()).

Return type:

UnknownBlock

Returns:

Constructed block schema, the body written back verbatim.

_read_block_short_header(schema, *, header)[source]

Read a PCAP-NG SHB or IDB shorter than its fixed fields.

The fixed fields of a Section Header Block span 28 octets and those of an Interface Description Block 20 (see SHORT_HEADER_TYPES), so a smaller Block Total Length cannot hold them.

Parameters:
Return type:

SectionHeaderBlock | InterfaceDescriptionBlock

Returns:

Parsed packet data, with the fixed fields the block holds and zero for those it does not, and no options. The block body is kept as block_raw, which the block’s make writes back verbatim, so the block rebuilds at the length it declared (#1422).

A section header keeps the byte order its Byte-Order Magic declares. One of 12 octets has no room for the magic, and takes the byte order in which its Block Total Length reads as 12 (see SectionHeaderBlock).

_read_block_unknown(schema, *, header)[source]

Read unknown PCAP-NG block.

Parameters:

  • schema (UnknownBlock) – Parsed block schema.

  • header (PCAPNG) – Parsed PCAP-NG header schema.

Return type:

UnknownBlock

Returns:

Parsed packet data.

_read_block_idb(schema, *, header)[source]

Read PCAP-NG interface description block (IDB).

Structure of Interface Description Block:

                        1                   2                   3
    0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 0 |                    Block Type = 0x00000001                    |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 4 |                      Block Total Length                       |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 8 |           LinkType            |           Reserved            |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
12 |                            SnapLen                            |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
16 /                                                               /
   /                      Options (variable)                       /
   /                                                               /
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |                      Block Total Length                       |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
Parameters:
Return type:

InterfaceDescriptionBlock

Returns:

Parsed packet data.

_read_block_packet(schema, *, header)[source]

Read PCAP-NG packet block (obsolete).

Structure of Packet Block:

                        1                   2                   3
    0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 0 |                    Block Type = 0x00000002                    |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 4 |                      Block Total Length                       |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 8 |         Interface ID          |          Drops Count          |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
12 |                        Timestamp (High)                       |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
16 |                        Timestamp (Low)                        |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
20 |                    Captured Packet Length                     |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
24 |                    Original Packet Length                     |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
28 /                                                               /
   /                          Packet Data                          /
   /              variable length, padded to 32 bits               /
   /                                                               /
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   /                                                               /
   /                      Options (variable)                       /
   /                                                               /
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |                      Block Total Length                       |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
Parameters:

  • schema (PacketBlock) – Parsed block schema.

  • header (PCAPNG) – Parsed PCAP-NG header schema.

Return type:

PacketBlock

Returns:

Parsed packet data.

_read_block_spb(schema, *, header)[source]

Read PCAP-NG simple packet block (SPB).

Structure of Simple Packet Block:

                        1                   2                   3
    0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 0 |                    Block Type = 0x00000003                    |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 4 |                      Block Total Length                       |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 8 |                    Original Packet Length                     |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
12 /                                                               /
   /                          Packet Data                          /
   /              variable length, padded to 32 bits               /
   /                                                               /
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |                      Block Total Length                       |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
Parameters:
Return type:

SimplePacketBlock

Returns:

Parsed packet data.

_read_block_nrb(schema, *, header)[source]

Read PCAP-NG name resolution block (NRB).

Structure of Name Resolution Block:

                        1                   2                   3
    0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 0 |                    Block Type = 0x00000004                    |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 4 |                      Block Total Length                       |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 8 |      Record Type              |      Record Value Length      |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
12 /                       Record Value                            /
   /              variable length, padded to 32 bits               /
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   .                                                               .
   .                  . . . other records . . .                    .
   .                                                               .
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |  Record Type = nrb_record_end |   Record Value Length = 0     |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   /                                                               /
   /                      Options (variable)                       /
   /                                                               /
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |                      Block Total Length                       |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
Parameters:
Return type:

NameResolutionBlock

Returns:

Parsed packet data.

_read_block_isb(schema, *, header)[source]

Read PCAP-NG interface statistics block (ISB).

Structure of Interface Statistics Block:

                        1                   2                   3
    0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 0 |                   Block Type = 0x00000005                     |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 4 |                      Block Total Length                       |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 8 |                         Interface ID                          |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
12 |                        Timestamp (High)                       |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
16 |                        Timestamp (Low)                        |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
20 /                                                               /
   /                      Options (variable)                       /
   /                                                               /
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |                      Block Total Length                       |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
Parameters:
Return type:

InterfaceStatisticsBlock

Returns:

Parsed packet data.

_read_block_epb(schema, *, header)[source]

Read PCAP-NG enhanced packet block (EPB).

Structure of Enhanced Packet Block:

                        1                   2                   3
    0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 0 |                    Block Type = 0x00000006                    |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 4 |                      Block Total Length                       |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 8 |                         Interface ID                          |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
12 |                        Timestamp (High)                       |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
16 |                        Timestamp (Low)                        |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
20 |                    Captured Packet Length                     |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
24 |                    Original Packet Length                     |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
28 /                                                               /
   /                          Packet Data                          /
   /              variable length, padded to 32 bits               /
   /                                                               /
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   /                                                               /
   /                      Options (variable)                       /
   /                                                               /
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |                      Block Total Length                       |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
Parameters:
Return type:

EnhancedPacketBlock

Returns:

Parsed packet data.

_read_block_systemd(schema, *, header)[source]

Read PCAP-NG systemd(1) journal export block.

Structure of systemd(1) Journal Export Block:

                       1                   2                   3
   0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
  +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
0 |                    Block Type = 0x00000009                    |
  +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
4 |                      Block Total Length                       |
  +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
8 /                                                               /
  /                         Journal Entry                         /
  /              variable length, padded to 32 bits               /
  /                                                               /
  +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
  |                      Block Total Length                       |
  +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
Parameters:
Return type:

SystemdJournalExportBlock

Returns:

Parsed packet data.

_read_block_dsb(schema, *, header)[source]

Read PCAP-NG decryption secrets block (DSB).

Structure of Decryption Secrets Block:

                        1                   2                   3
    0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 0 |                   Block Type = 0x0000000A                     |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 4 |                      Block Total Length                       |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 8 |                          Secrets Type                         |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
12 |                         Secrets Length                        |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
16 /                                                               /
   /                          Secrets Data                         /
   /              (variable length, padded to 32 bits)             /
   /                                                               /
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   /                                                               /
   /                       Options (variable)                      /
   /                                                               /
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   /                       Block Total Length                      /
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
Parameters:
Return type:

DecryptionSecretsBlock

Returns:

Parsed packet data.

_read_block_cb(schema, *, header)[source]

Read PCAP-NG custom block (CB).

Structure of Custom Block:

                        1                   2                   3
    0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 0 |             Block Type = 0x00000BAD or 0x40000BAD             |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 4 |                      Block Total Length                       |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 8 |                Private Enterprise Number (PEN)                |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
12 /                                                               /
   /                          Custom Data                          /
   /              variable length, padded to 32 bits               /
   /                                                               /
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   /                                                               /
   /                      Options (variable)                       /
   /                                                               /
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |                      Block Total Length                       |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
Parameters:

  • schema (CustomBlock) – Parsed block schema.

  • header (PCAPNG) – Parsed PCAP-NG header schema.

Return type:

CustomBlock

Returns:

Parsed packet data.

_read_block_shb(schema, *, header)[source]

Read PCAP-NG section header block (SHB).

Structure of Section Header Block:

    0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 0 |                   Block Type = 0x0A0D0D0A                     |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 4 |                      Block Total Length                       |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 8 |                      Byte-Order Magic                         |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
12 |          Major Version        |         Minor Version         |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
16 |                                                               |
   |                          Section Length                       |
   |                                                               |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
24 /                                                               /
   /                      Options (variable)                       /
   /                                                               /
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |                      Block Total Length                       |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
Parameters:
Return type:

SectionHeaderBlock

Returns:

Parsed packet data.

_read_option_unknown(schema, *, options)[source]

Read unknown PCAP-NG option.

Parameters:
Return type:

UnknownOption

Returns:

Parsed option data.

_read_option_endofopt(schema, *, options)[source]

Read PCAP-NG opt_endofopt option.

Parameters:
Return type:

EndOfOption

Returns:

Parsed option data.

_read_option_comment(schema, *, options)[source]

Read PCAP-NG opt_comment option.

Parameters:
Return type:

CommentOption

Returns:

Parsed option data.

_read_option_custom(schema, *, options)[source]

Read PCAP-NG opt_custom option.

Structure of PCAP-NG opt_custom option:

                     1                   2                   3
 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|     Custom Option Code        |         Option Length         |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|                Private Enterprise Number (PEN)                |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
/                        Custom Data                            /
/              variable length, padded to 32 bits               /
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
Parameters:
Return type:

CustomOption

Returns:

Parsed option data.

Raises:

ProtocolError – If the option is shorter than its 4-octet private enterprise number, which Option Length includes.

_read_option_if_name(schema, *, options)[source]

Read PCAP-NG if_name option.

Parameters:
Return type:

IF_NameOption

Returns:

Parsed option data.

_read_option_if_description(schema, *, options)[source]

Read PCAP-NG if_description option.

Parameters:
Return type:

IF_DescriptionOption

Returns:

Parsed option data.

_read_option_if_ipv4(schema, *, options)[source]

Read PCAP-NG if_IPv4addr option.

Parameters:
Return type:

IF_IPv4AddrOption

Returns:

Parsed option data.

_read_option_if_ipv6(schema, *, options)[source]

Read PCAP-NG if_IPv6addr option.

Parameters:
Return type:

IF_IPv6AddrOption

Returns:

Parsed option data.

_read_option_if_mac(schema, *, options)[source]

Read PCAP-NG if_MACaddr option.

Parameters:
Return type:

IF_MACAddrOption

Returns:

Parsed option data.

_read_option_if_eui(schema, *, options)[source]

Read PCAP-NG if_EUIaddr option.

Parameters:
Return type:

IF_EUIAddrOption

Returns:

Parsed option data.

_read_option_if_speed(schema, *, options)[source]

Read PCAP-NG if_speed option.

Parameters:
Return type:

IF_SpeedOption

Returns:

Parsed option data.

_read_option_if_tsresol(schema, *, options)[source]

Read PCAP-NG if_tsresol option.

Parameters:
Return type:

IF_TSResolOption

Returns:

Parsed option data.

_read_option_if_tzone(schema, *, options)[source]

Read PCAP-NG if_tzone option.

Parameters:
Return type:

IF_TZoneOption

Returns:

Parsed option data.

_read_option_if_filter(schema, *, options)[source]

Read PCAP-NG if_filter option.

Parameters:
Return type:

IF_FilterOption

Returns:

Parsed option data.

_read_option_if_os(schema, *, options)[source]

Read PCAP-NG if_os option.

Parameters:
Return type:

IF_OSOption

Returns:

Parsed option data.

_read_option_if_fcslen(schema, *, options)[source]

Read PCAP-NG if_fcslen option.

Parameters:
Return type:

IF_FCSLenOption

Returns:

Parsed option data.

_read_option_if_tsoffset(schema, *, options)[source]

Read PCAP-NG if_tsoffset option.

Parameters:
Return type:

IF_TSOffsetOption

Returns:

Parsed option data.

_read_option_if_hardware(schema, *, options)[source]

Read PCAP-NG if_hardware option.

Parameters:
Return type:

IF_HardwareOption

Returns:

Parsed option data.

_read_option_if_txspeed(schema, *, options)[source]

Read PCAP-NG if_txspeed option.

Parameters:
Return type:

IF_TxSpeedOption

Returns:

Parsed option data.

_read_option_if_rxspeed(schema, *, options)[source]

Read PCAP-NG if_rxspeed option.

Parameters:
Return type:

IF_RxSpeedOption

Returns:

Parsed option data.

_read_option_epb_flags(schema, *, options)[source]

Read PCAP-NG epb_flags option.

Parameters:
Return type:

EPB_FlagsOption

Returns:

Parsed option data.

_read_option_epb_hash(schema, *, options)[source]

Read PCAP-NG epb_hash option.

Parameters:
Return type:

EPB_HashOption

Returns:

Parsed option data.

_read_option_epb_dropcount(schema, *, options)[source]

Read PCAP-NG epb_dropcount option.

Parameters:
Return type:

EPB_DropCountOption

Returns:

Parsed option data.

_read_option_epb_packetid(schema, *, options)[source]

Read PCAP-NG epb_packetid option.

Parameters:
Return type:

EPB_PacketIDOption

Returns:

Parsed option data.

_read_option_epb_queue(schema, *, options)[source]

Read PCAP-NG epb_queue option.

Parameters:
Return type:

EPB_QueueOption

Returns:

Parsed option data.

_read_option_epb_verdict(schema, *, options)[source]

Read PCAP-NG epb_verdict option.

Parameters:
Return type:

EPB_VerdictOption

Returns:

Parsed option data.

_read_option_ns_dnsname(schema, *, options)[source]

Read PCAP-NG ns_dnsname option.

Parameters:
Return type:

NS_DNSNameOption

Returns:

Parsed option data.

_read_option_ns_dnsipv4(schema, *, options)[source]

Read PCAP-NG ns_dnsIP4addr option.

Parameters:
Return type:

NS_DNSIP4AddrOption

Returns:

Parsed option data.

_read_option_ns_dnsipv6(schema, *, options)[source]

Read PCAP-NG ns_dnsIP6addr option.

Parameters:
Return type:

NS_DNSIP6AddrOption

Returns:

Parsed option data.

_read_option_isb_starttime(schema, *, options)[source]

Read PCAP-NG isb_starttime option.

Parameters:
Return type:

ISB_StartTimeOption

Returns:

Parsed option data.

_read_option_isb_endtime(schema, *, options)[source]

Read PCAP-NG isb_endtime option.

Parameters:
Return type:

ISB_EndTimeOption

Returns:

Parsed option data.

_read_option_isb_ifrecv(schema, *, options)[source]

Read PCAP-NG isb_ifrecv option.

Parameters:
Return type:

ISB_IFRecvOption

Returns:

Parsed option data.

_read_option_isb_ifdrop(schema, *, options)[source]

Read PCAP-NG isb_ifdrop option.

Parameters:
Return type:

ISB_IFDropOption

Returns:

Parsed option data.

_read_option_isb_filteraccept(schema, *, options)[source]

Read PCAP-NG isb_filteraccept option.

Parameters:
Return type:

ISB_FilterAcceptOption

Returns:

Parsed option data.

_read_option_isb_osdrop(schema, *, options)[source]

Read PCAP-NG isb_osdrop option.

Parameters:
Return type:

ISB_OSDropOption

Returns:

Parsed option data.

_read_option_isb_usrdeliv(schema, *, options)[source]

Read PCAP-NG isb_usrdeliv option.

Parameters:
Return type:

ISB_UsrDelivOption

Returns:

Parsed option data.

_read_option_pack_flags(schema, *, options)[source]

Read PCAP-NG pack_flags option.

Parameters:
Return type:

PACK_FlagsOption

Returns:

Parsed option data.

_read_option_pack_hash(schema, *, options)[source]

Read PCAP-NG pack_hash option.

Parameters:
Return type:

PACK_HashOption

Returns:

Parsed option data.

_read_record_unknown(schema, *, records)[source]

Read PCAP-NG unknown name resolution records.

Parameters:
Return type:

UnknownRecord

Returns:

Parsed name resolution record data.

_read_record_end(schema, *, records)[source]

Read PCAP-NG nrb_record_end name resolution records.

Parameters:
Return type:

EndRecord

Returns:

Parsed name resolution record data.

_read_record_ipv4(schema, *, records)[source]

Read PCAP-NG nrb_record_ipv4 name resolution records.

Parameters:
Return type:

IPv4Record

Returns:

Parsed name resolution record data.

_read_record_ipv6(schema, *, records)[source]

Read PCAP-NG nrb_record_ipv6 name resolution records.

Parameters:
Return type:

IPv6Record

Returns:

Parsed name resolution record data.

_read_secrets_unknown(schema, *, block)[source]

Read PCAP-NG unknown secrets.

Parameters:
Return type:

UnknownSecrets

Returns:

Parsed decryption secrets data.

_read_secrets_tls(schema, *, block)[source]

Read PCAP-NG TLS key log secrets.

Parameters:
Return type:

TLSKeyLog

Returns:

Parsed decryption secrets data.

_read_secrets_wireguard(schema, *, block)[source]

Read PCAP-NG WireGuard key log secrets.

Parameters:
Return type:

WireGuardKeyLog

Returns:

Parsed decryption secrets data.

_read_secrets_zigbee_aps(schema, *, block)[source]

Read PCAP-NG ZigBee APS Key secrets.

Structure of ZigBee APS Key secrets:

   0                   1                   2                   3
   0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
   +---------------------------------------------------------------+
 0 |                   Block Type = 0x0000000A                     |
   +---------------------------------------------------------------+
 4 |                      Block Total Length                       |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 8 |                  Secrets Type = 0x5a415053                    |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
12 |                         Secrets Length                        |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
16 |                            AES-128                            |
   |                            APS Key                            |
   |                          (16 octets)                          |
   |                           (128 bits)                          |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
32 |           PAN ID              |     Low Node Short Address    |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
36 |    High Node Short Address    |         padding (0)           |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
40 /                                                               /
   /                       Options (variable)                      /
   /                                                               /
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   /                       Block Total Length                      /
   +---------------------------------------------------------------+
Parameters:
Return type:

ZigBeeAPSKey

Returns:

Parsed decryption secrets data.

_read_secrets_zigbee_nwk(schema, *, block)[source]

Read PCAP-NG ZigBee NWK Key secrets.

Structure of ZigBee NWK Key secrets:

   0                   1                   2                   3
   0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
   +---------------------------------------------------------------+
 0 |                   Block Type = 0x0000000A                     |
   +---------------------------------------------------------------+
 4 |                      Block Total Length                       |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 8 |                  Secrets Type = 0x5a4e574b                    |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
12 |                         Secrets Length                        |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
16 |                            AES-128                            |
   |                            NWK Key                            |
   |                          (16 octets)                          |
   |                           (128 bits)                          |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
32 |          PAN ID               |           padding (0)         |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
36 /                                                               /
   /                       Options (variable)                      /
   /                                                               /
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   /                       Block Total Length                      /
   +---------------------------------------------------------------+
Parameters:
Return type:

ZigBeeNWKKey

Returns:

Parsed decryption secrets data.

_make_block_unknown(block=None, *, data=b'', **kwargs)[source]

Make unknown PCAP-NG block.

Parameters:

  • block (UnknownBlock | None) – Block data model.

  • data (bytes) – Unspecified block data.

  • **kwargs (Any) – Arbitrary keyword arguments.

Return type:

UnknownBlock

Returns:

Constructed block schema.

_make_block_idb(block=None, *, linktype=LinkType.NULL, snaplen=0, options=None, **kwargs)[source]

Make PCAP-NG interface description block (IDB).

Parameters:
Return type:

InterfaceDescriptionBlock

Returns:

Constructed block schema.

Raises:

ProtocolError – If linktype is a name, a bool, or a member or code the 16-bit LinkType field cannot carry; or if snaplen is not an int (a bool included), or is outside 0 to 0xFFFFFFFF, which the 32-bit SnapLen field would truncate (#2278).

Changed in version 1.5.0: snaplen’s default changed from 0xFFFF_FFFF_FFFF_FFFF – which the 32-bit field silently truncated to 0xFFFFFFFF – to 0, and a value outside the field’s range now raises instead of being truncated (#2278).

Changed in version 1.6.0: snaplen is checked by _make_uint(), so a bool or a non-integer raises ProtocolError too (#2614).

_make_block_packet(block=None, *, interface_id=0, drop_count=0, timestamp=None, captured_len=None, original_len=None, packet_data=b'', options=None, **kwargs)[source]

Make PCAP-NG packet block (obsolete).

Parameters:
Return type:

PacketBlock

Returns:

Constructed block schema.

Raises:

ProtocolError – If drop_count is not an int (a bool included), or is outside 0 to 0xFFFF.

Changed in version 1.6.0: drop_count is checked by _make_uint(), so a value the 16-bit field cannot hold, -1 included, or a bool raises ProtocolError rather than being written masked (#2614).

_make_block_spb(block=None, *, original_len=None, packet_data=b'', **kwargs)[source]

Make PCAP-NG simple packet block (SPB).

Parameters:
Return type:

SimplePacketBlock

Returns:

Constructed block schema.

_make_block_nrb(block=None, *, records=None, options=None, **kwargs)[source]

Make PCAP-NG name resolution block (NRB).

Parameters:
Return type:

NameResolutionBlock

Returns:

Constructed block schema.

_make_block_isb(block=None, *, interface_id=0, timestamp=None, options=None, **kwargs)[source]

Make PCAP-NG interface statistics block (ISB).

Parameters:
Return type:

InterfaceStatisticsBlock

Returns:

Constructed block schema.

_make_block_epb(block=None, *, interface_id=0, timestamp=None, captured_len=None, original_len=None, packet_data=b'', options=None, **kwargs)[source]

Make PCAP-NG enhanced packet block (EPB).

Parameters:
Return type:

EnhancedPacketBlock

Returns:

Constructed block schema.

_make_block_systemd(block=None, *, entries=None, **kwargs)[source]

Make PCAP-NG systemd(1) journal export block.

Parameters:
Return type:

SystemdJournalExportBlock

Returns:

Constructed block schema.

_make_block_dsb(block=None, *, secrets_type=SecretsType.TLS_Key_Log, secrets_data=b'', options=None, **kwargs)[source]

Make PCAP-NG decryption secrets block (DSB).

Parameters:
Return type:

DecryptionSecretsBlock

Returns:

Constructed block schema.

Raises:

ProtocolError – If secrets_type is a name, a bool, or a member or code the 32-bit Secrets Type field cannot carry; or if secrets_data is none of the forms this maker reads – raw bytes, a dict of secrets arguments, a DSBSecrets data model or a Schema.

_make_block_cb(block=None, *, pen=0, data=b'', options=None, **kwargs)[source]

Make PCAP-NG custom block (CB).

Parameters:
Return type:

CustomBlock

Returns:

Constructed block schema.

_make_block_shb(block=None, *, version=(1, 0), major_version=None, minor_version=None, section_length=-1, options=None, byteorder=sys.byteorder, **kwargs)[source]

Make PCAP-NG section header block (SHB).

Parameters:
Return type:

SectionHeaderBlock

Returns:

Constructed block schema.

Raises:

ProtocolError – If section_length is not an int (a bool included), or is outside -2 ** 63 to 2 ** 64 - 1.

Changed in version 1.6.0: section_length is checked by _make_sint(), so a value outside the 64-bit field in either spelling, a bool or a non-integer raises ProtocolError rather than being written masked or failing to pack; -1 and 0xFFFFFFFFFFFFFFFF still write the same octets (#2614).

_make_option_unknown(type, option=None, *, data=b'', **kwargs)[source]

Make unknown PCAP-NG option.

Parameters:

  • type (OptionType) – Option type.

  • option (UnknownOption | None) – Option data model.

  • data (bytes) – Unspecified option data.

  • **kwargs (Any) – Arbitrary keyword arguments.

Return type:

UnknownOption

Returns:

Constructed option schema.

_make_option_endofopt(type, option=None, **kwargs)[source]

Make PCAP-NG opt_endofopt option.

Parameters:
Return type:

EndOfOption

Returns:

Constructed option schema.

_make_option_comment(type, option=None, *, comment='', **kwargs)[source]

Make PCAP-NG opt_comment option.

Parameters:

  • type (OptionType) – Option type.

  • option (CommentOption | None) – Option data model.

  • comment (str) – Comment text.

  • **kwargs (Any) – Arbitrary keyword arguments.

Return type:

CommentOption

Returns:

Constructed option schema.

_make_option_custom(type, option=None, *, pen=0xFFFFFFFF, data=b'', **kwargs)[source]

Make PCAP-NG opt_custom option.

Parameters:

  • type (OptionType) – Option type.

  • option (CustomOption | None) – Option data model.

  • pen (int) – Private enterprise number.

  • data (bytes) – Custom data.

  • **kwargs (Any) – Arbitrary keyword arguments.

Return type:

CustomOption

Returns:

Constructed option schema.

_make_option_if_name(type, option=None, *, name='', **kwargs)[source]

Make PCAP-NG if_name option.

Parameters:

  • type (OptionType) – Option type.

  • option (IF_NameOption | None) – Option data model.

  • name (str) – Interface name.

  • **kwargs (Any) – Arbitrary keyword arguments.

Return type:

IF_NameOption

Returns:

Constructed option schema.

_make_option_if_description(type, option=None, *, description='', **kwargs)[source]

Make PCAP-NG if_description option.

Parameters:
Return type:

IF_DescriptionOption

Returns:

Constructed option schema.

_make_option_if_ipv4(type, option=None, *, interface='192.168.1.1/255.255.255.0', **kwargs)[source]

Make PCAP-NG if_IPv4addr option.

Parameters:
Return type:

IF_IPv4AddrOption

Returns:

Constructed option schema.

_make_option_if_ipv6(type, option=None, *, interface='2001:0db8:85a3:08d3:1319:8a2e:0370:7344/64', **kwargs)[source]

Make PCAP-NG if_IPv6addr option.

Parameters:
Return type:

IF_IPv6AddrOption

Returns:

Constructed option schema.

_make_option_if_mac(type, option=None, *, interface='00:01:02:03:04:05', **kwargs)[source]

Make PCAP-NG if_MACaddr option.

Parameters:
Return type:

IF_MACAddrOption

Returns:

Constructed option schema.

_make_option_if_eui(type, option=None, *, interface='02:34:56:FF:FE:78:9A:BC', **kwargs)[source]

Make PCAP-NG if_EUIaddr option.

Parameters:
Return type:

IF_EUIAddrOption

Returns:

Constructed option schema.

_make_option_if_speed(type, option=None, *, speed=100000000, **kwargs)[source]

Make PCAP-NG if_speed option.

Parameters:

  • type (OptionType) – Option type.

  • option (IF_SpeedOption | None) – Option data model.

  • speed (int) – Interface speed, in bits per second.

  • **kwargs (Any) – Arbitrary keyword arguments.

Return type:

IF_SpeedOption

Returns:

Constructed option schema.

_make_option_if_tsresol(type, option=None, *, resolution=DEFAULT_RESOLUTION, **kwargs)[source]

Make PCAP-NG if_tsresol option.

Parameters:

  • type (OptionType) – Option type.

  • option (IF_TSResolOption | None) – Option data model.

  • resolution (int) – Resolution of timestamps, in units per second.

  • **kwargs (Any) – Arbitrary keyword arguments.

Return type:

IF_TSResolOption

Returns:

Constructed option schema.

_make_option_if_tzone(type, option=None, *, tzone=0, **kwargs)[source]

Make PCAP-NG if_tzone option.

Parameters:
Return type:

IF_TZoneOption

Returns:

Constructed option schema.

Raises:

ProtocolError – If tzone is none of those types, or is a bool, or its seconds do not fit the signed 32-bit field.

Changed in version 1.6.0: An offset the signed 32-bit field cannot hold, or a bool, raises ProtocolError rather than being written truncated (#2614).

_make_option_if_filter(type, option=None, *, filter=FilterType(0), expression=b'', **kwargs)[source]

Make PCAP-NG if_filter option.

Parameters:
Return type:

IF_FilterOption

Returns:

Constructed option schema.

Raises:

ProtocolError – If filter is a name, a bool, or a member or code the 8-bit filter type field cannot carry.

_make_option_if_os(type, option=None, *, os=platform.platform(), **kwargs)[source]

Make PCAP-NG if_os option.

Parameters:

  • type (OptionType) – Option type.

  • option (IF_OSOption | None) – Option data model.

  • os (str) – Operating system name.

  • **kwargs (Any) – Arbitrary keyword arguments.

Return type:

IF_OSOption

Returns:

Constructed option schema.

_make_option_if_fcslen(type, option=None, *, fcs_length=4, **kwargs)[source]

Make PCAP-NG if_fcslen option.

Parameters:

  • type (OptionType) – Option type.

  • option (IF_FCSLenOption | None) – Option data model.

  • fcs_length (int) – FCS length, in bytes.

  • **kwargs (Any) – Arbitrary keyword arguments.

Return type:

IF_FCSLenOption

Returns:

Constructed option schema.

_make_option_if_tsoffset(type, option=None, *, offset=0, **kwargs)[source]

Make PCAP-NG if_tsoffset option.

Parameters:

  • type (OptionType) – Option type.

  • option (IF_TSOffsetOption | None) – Option data model.

  • offset (int) – Timestamp offset in seconds.

  • **kwargs (Any) – Arbitrary keyword arguments.

Return type:

IF_TSOffsetOption

Returns:

Constructed option schema.

Raises:

ProtocolError – If offset is not an int, is a bool, or does not fit the signed 64-bit field.

Changed in version 1.6.0: An offset the signed 64-bit field cannot hold, a bool or a non-integer raises ProtocolError rather than being written truncated, written as zero (None) or failing to pack (#2614).

_make_option_if_hardware(type, option=None, *, hardware=platform.processor(), **kwargs)[source]

Make PCAP-NG if_hardware option.

Parameters:
Return type:

IF_HardwareOption

Returns:

Constructed option schema.

_make_option_if_txspeed(type, option=None, *, speed=100000000, **kwargs)[source]

Make PCAP-NG if_txspeed option.

Parameters:

  • type (OptionType) – Option type.

  • option (IF_TxSpeedOption | None) – Option data model.

  • speed (int) – Interface transmit speed, in bits per second.

  • **kwargs (Any) – Arbitrary keyword arguments.

Return type:

IF_TxSpeedOption

Returns:

Constructed option schema.

_make_option_if_rxspeed(type, option=None, *, speed=100000000, **kwargs)[source]

Make PCAP-NG if_rxspeed option.

Parameters:

  • type (OptionType) – Option type.

  • option (IF_RxSpeedOption | None) – Option data model.

  • speed (int) – Interface receive speed, in bits per second.

  • **kwargs (Any) – Arbitrary keyword arguments.

Return type:

IF_RxSpeedOption

Returns:

Constructed option schema.

_make_option_epb_flags(type, option=None, *, direction=PacketDirection.UNKNOWN, reception=PacketReception.UNKNOWN, fcs_len=0, checksum_not_ready=False, checksum_valid=False, tcp_segmentation_offloaded=False, reserved=0, crc_error=False, too_long=False, too_short=False, gap_error=False, unaligned_error=False, delimiter_error=False, preamble_error=False, symbol_error=False, **kwargs)[source]

Make PCAP-NG epb_flags option.

Parameters:

  • type (OptionType) – Option type.

  • option (EPB_FlagsOption | None) – Option data model.

  • direction (PacketDirection | int) – Packet direction.

  • reception (PacketReception | int) – Packet reception.

  • fcs_len (int) – Length of FCS field, in bytes.

  • checksum_not_ready (bool) – Whether the checksum is not ready.

  • checksum_valid (bool) – Whether the checksum is valid.

  • tcp_segmentation_offloaded (bool) – Whether TCP segmentation was offloaded.

  • reserved (int) – Bits 12 to 23 of the flags word, verbatim.

  • crc_error (bool) – Whether CRC error occurred.

  • too_long (bool) – Whether packet is too long.

  • too_short (bool) – Whether packet is too short.

  • gap_error (bool) – Whether gap error occurred.

  • unaligned_error (bool) – Whether unaligned error occurred.

  • delimiter_error (bool) – Whether delimiter error occurred.

  • preamble_error (bool) – Whether preamble error occurred.

  • symbol_error (bool) – Whether symbol error occurred.

  • **kwargs (Any) – Arbitrary keyword arguments.

Return type:

EPB_FlagsOption

Returns:

Constructed option schema.

Raises:

ProtocolError – If direction or reception is a name, a bool, or a member or code its 2-bit or 3-bit sub-field cannot carry.

_make_option_epb_hash(type, option=None, *, algorithm=HashAlgorithm.two_s_complement, hash=b'', **kwargs)[source]

Make PCAP-NG epb_hash option.

Parameters:
Return type:

EPB_HashOption

Returns:

Constructed option schema.

Raises:

ProtocolError – If algorithm is a name, a bool, or a member or code the 8-bit hash algorithm field cannot carry.

_make_option_epb_dropcount(type, option=None, *, drop_count=0, **kwargs)[source]

Make PCAP-NG epb_dropcount option.

Parameters:
Return type:

EPB_DropCountOption

Returns:

Constructed option schema.

_make_option_epb_packetid(type, option=None, *, packet_id=0, **kwargs)[source]

Make PCAP-NG epb_packetid option.

Parameters:
Return type:

EPB_PacketIDOption

Returns:

Constructed option schema.

_make_option_epb_queue(type, option=None, *, queue_id=0, **kwargs)[source]

Make PCAP-NG epb_queue option.

Parameters:
Return type:

EPB_QueueOption

Returns:

Constructed option schema.

_make_option_epb_verdict(type, option=None, *, verdict=VerdictType.Hardware, value=b'', **kwargs)[source]

Make PCAP-NG epb_verdict option.

Parameters:
Return type:

EPB_VerdictOption

Returns:

Constructed option schema.

Raises:

ProtocolError – If verdict is a name, a bool, or a member or code the 8-bit verdict type field cannot carry.

_make_option_ns_dnsname(type, option=None, *, name='', **kwargs)[source]

Make PCAP-NG ns_dnsname option.

Parameters:
Return type:

NS_DNSNameOption

Returns:

Constructed option schema.

_make_option_ns_dnsipv4(type, option=None, *, ip='8.8.8.8', **kwargs)[source]

Make PCAP-NG ns_dnsIP4addr option.

Parameters:
Return type:

NS_DNSIP4AddrOption

Returns:

Constructed option schema.

_make_option_ns_dnsipv6(type, option=None, *, ip='2001:4860:4860::8888', **kwargs)[source]

Make PCAP-NG ns_dnsIP6addr option.

Parameters:
Return type:

NS_DNSIP6AddrOption

Returns:

Constructed option schema.

_make_option_isb_starttime(type, option=None, *, timestamp=None, **kwargs)[source]

Make PCAP-NG isb_starttime option.

Parameters:
Return type:

ISB_StartTimeOption

Returns:

Constructed option schema.

_make_option_isb_endtime(type, option=None, *, timestamp=None, **kwargs)[source]

Make PCAP-NG isb_endtime option.

Parameters:
Return type:

ISB_EndTimeOption

Returns:

Constructed option schema.

_make_option_isb_ifrecv(type, option=None, *, packets=0, **kwargs)[source]

Make PCAP-NG isb_ifrecv option.

Parameters:

  • type (OptionType) – Option type.

  • option (ISB_IFRecvOption | None) – Option data model.

  • packets (int) – Number of received packets.

  • **kwargs (Any) – Arbitrary keyword arguments.

Return type:

ISB_IFRecvOption

Returns:

Constructed option schema.

_make_option_isb_ifdrop(type, option=None, *, packets=0, **kwargs)[source]

Make PCAP-NG isb_ifdrop option.

Parameters:

  • type (OptionType) – Option type.

  • option (ISB_IFDropOption | None) – Option data model.

  • packets (int) – Number of dropped packets.

  • **kwargs (Any) – Arbitrary keyword arguments.

Return type:

ISB_IFDropOption

Returns:

Constructed option schema.

_make_option_isb_filteraccept(type, option=None, *, packets=0, **kwargs)[source]

Make PCAP-NG isb_filteraccept option.

Parameters:
Return type:

ISB_FilterAcceptOption

Returns:

Constructed option schema.

_make_option_isb_osdrop(type, option=None, *, packets=0, **kwargs)[source]

Make PCAP-NG isb_osdrop option.

Parameters:

  • type (OptionType) – Option type.

  • option (ISB_OSDropOption | None) – Option data model.

  • packets (int) – Number of packets dropped by the OS.

  • **kwargs (Any) – Arbitrary keyword arguments.

Return type:

ISB_OSDropOption

Returns:

Constructed option schema.

_make_option_isb_usrdeliv(type, option=None, *, packets=0, **kwargs)[source]

Make PCAP-NG isb_usrdeliv option.

Parameters:

  • type (OptionType) – Option type.

  • option (ISB_UsrDelivOption | None) – Option data model.

  • packets (int) – Number of packets delivered to the user.

  • **kwargs (Any) – Arbitrary keyword arguments.

Return type:

ISB_UsrDelivOption

Returns:

Constructed option schema.

_make_option_pack_flags(type, option=None, *, direction=PacketDirection.UNKNOWN, reception=PacketReception.UNKNOWN, fcs_len=0, checksum_not_ready=False, checksum_valid=False, tcp_segmentation_offloaded=False, reserved=0, crc_error=False, too_long=False, too_short=False, gap_error=False, unaligned_error=False, delimiter_error=False, preamble_error=False, symbol_error=False, **kwargs)[source]

Make PCAP-NG pack_flags option.

Parameters:

  • type (OptionType) – Option type.

  • option (PACK_FlagsOption | None) – Option data model.

  • direction (PacketDirection | int) – Packet direction.

  • reception (PacketReception | int) – Packet reception.

  • fcs_len (int) – Length of FCS field, in bytes.

  • checksum_not_ready (bool) – Whether the checksum is not ready.

  • checksum_valid (bool) – Whether the checksum is valid.

  • tcp_segmentation_offloaded (bool) – Whether TCP segmentation was offloaded.

  • reserved (int) – Bits 12 to 23 of the flags word, verbatim.

  • crc_error (bool) – Whether CRC error occurred.

  • too_long (bool) – Whether packet is too long.

  • too_short (bool) – Whether packet is too short.

  • gap_error (bool) – Whether gap error occurred.

  • unaligned_error (bool) – Whether unaligned error occurred.

  • delimiter_error (bool) – Whether delimiter error occurred.

  • preamble_error (bool) – Whether preamble error occurred.

  • symbol_error (bool) – Whether symbol error occurred.

  • **kwargs (Any) – Arbitrary keyword arguments.

Return type:

PACK_FlagsOption

Returns:

Constructed option schema.

Raises:

ProtocolError – If direction or reception is a name, a bool, or a member or code its 2-bit or 3-bit sub-field cannot carry.

_make_option_pack_hash(type, option=None, *, algorithm=HashAlgorithm.two_s_complement, hash=b'', **kwargs)[source]

Make PCAP-NG pack_hash option.

Parameters:
Return type:

PACK_HashOption

Returns:

Constructed option schema.

Raises:

ProtocolError – If algorithm is a name, a bool, or a member or code the 8-bit hash algorithm field cannot carry.

_make_record_unknown(type, record=None, *, data=b'', **kwargs)[source]

Make PCAP-NG unknown name resolution record.

Parameters:
Return type:

UnknownRecord

Returns:

Constructed record schema.

_make_record_end(type, record=None, **kwargs)[source]

Make PCAP-NG nrb_record_end name resolution record.

Parameters:

  • type (RecordType) – Record type.

  • record (EndRecord | None) – Record data model.

  • **kwargs (Any) – Arbitrary keyword arguments.

Return type:

EndRecord

Returns:

Constructed record schema.

_make_record_ipv4(type, record=None, *, ip='127.0.0.1', names=None, **kwargs)[source]

Make PCAP-NG nrb_record_ipv4 name resolution record.

Parameters:
Return type:

IPv4Record

Returns:

Constructed record schema.

_make_record_ipv6(type, record=None, *, ip='::1', names=None, **kwargs)[source]

Make PCAP-NG nrb_record_ipv6 name resolution record.

Parameters:
Return type:

IPv6Record

Returns:

Constructed record schema.

_make_secrets_unknown(type, secrets=None, *, data=b'', **kwargs)[source]

Make PCAP-NG unknown secrets.

Parameters:
Return type:

UnknownSecrets

Returns:

Constructed secrets schema.

_make_secrets_tls(type, secrets=None, *, entries=None, data=None, **kwargs)[source]

Make PCAP-NG TLS Key Log secrets.

Parameters:

  • type (SecretsType) – Secrets type.

  • secrets (TLSKeyLog | None) – Secrets data model. The key log text it was parsed from, if any, is written back verbatim; otherwise its entries are. On a parsed model the text wins, so an edit to its entries alone is silently ignored.

  • entries (Mapping[TLSKeyLabel, OrderedMultiDict[bytes, bytes]] | None) – TLS Key Log entries.

  • data (str | None) – TLS key log text, written back verbatim in place of entries, as the text of secrets is.

  • **kwargs (Any) – Arbitrary keyword arguments.

Return type:

TLSKeyLog

Returns:

Constructed secrets schema.

Changed in version 1.6.0: Takes the key log text as data, so that the dict of a parsed model rebuilds the log as captured, as the model itself does, rather than as its entries under a generated comment (#2698).

_make_secrets_wireguard(type, secrets=None, *, entries=None, data=None, **kwargs)[source]

Make PCAP-NG WireGuard secrets.

Parameters:

  • type (SecretsType) – Secrets type.

  • secrets (WireGuardKeyLog | None) – Secrets data model. The key log text it was parsed from, if any, is written back verbatim; otherwise its entries are. On a parsed model the text wins, so an edit to its entries alone is silently ignored.

  • entries (OrderedMultiDict[WireGuardKeyLabel, bytes] | None) – WireGuard Key Log entries.

  • data (str | None) – WireGuard key log text, written back verbatim in place of entries, as the text of secrets is.

  • **kwargs (Any) – Arbitrary keyword arguments.

Return type:

WireGuardKeyLog

Returns:

Constructed secrets schema.

Changed in version 1.6.0: Takes the key log text as data, as _make_secrets_tls() does (#2698).

_make_secrets_zigbee_aps(type, secrets=None, *, aps_key=bytes(16), pan_id=0, short_address=0, data=None, **kwargs)[source]

Make PCAP-NG ZigBee APS Key secrets.

Parameters:

  • type (SecretsType) – Secrets type.

  • secrets (ZigBeeAPSKey | None) – Secrets data model. The Secrets Data octets it was parsed from, if any, are written back verbatim, as for _make_secrets_zigbee_nwk(); otherwise its fields are.

  • aps_key (bytes) – APS key, 16 octets.

  • pan_id (int) – PAN ID.

  • short_address (int) – Short address.

  • data (bytes | None) – Secrets Data octets, written back verbatim in place of the fields, as the octets of secrets are.

  • **kwargs (Any) – Arbitrary keyword arguments.

Return type:

ZigBeeAPSKey

Returns:

Constructed secrets schema.

Raises:

ProtocolError – If aps_key is not 16 octets.

Changed in version 1.6.0:

  • Takes the Secrets Data octets as data, as _make_secrets_zigbee_nwk() does (#2698).

  • aps_key of any other width, empty included, raises ProtocolError rather than being padded or cut to the 16-octet key, and defaults to 16 zero octets where it defaulted to empty (#2676).

_make_secrets_zigbee_nwk(type, secrets=None, *, nwk_key=bytes(16), pan_id=0, data=None, **kwargs)[source]

Make PCAP-NG ZigBee NWK Key secrets.

Parameters:

  • type (SecretsType) – Secrets type.

  • secrets (ZigBeeNWKKey | None) – Secrets data model. The Secrets Data octets it was parsed from, if any, are written back verbatim, so that a key shorter or longer than its fixed width rebuilds as captured (#1986); otherwise its fields are. On a parsed model the octets win, so an edit to its fields alone is silently ignored.

  • nwk_key (bytes) – NWK key, 16 octets.

  • pan_id (int) – PAN ID.

  • data (bytes | None) – Secrets Data octets, written back verbatim in place of nwk_key and pan_id, as the octets of secrets are.

  • **kwargs (Any) – Arbitrary keyword arguments.

Return type:

ZigBeeNWKKey

Returns:

Constructed secrets schema.

Raises:

ProtocolError – If nwk_key is not 16 octets.

Changed in version 1.6.0:

  • Takes the Secrets Data octets as data, so that the dict of a parsed model rebuilds the key as captured, as the model itself does, rather than as its zero-filled fields (#2698).

  • nwk_key of any other width, empty included, raises ProtocolError rather than being padded or cut to the 16-octet key, and defaults to 16 zero octets where it defaulted to empty (#2676).

_check_block_floor(length)[source]

Reject a tail too short to hold any block at all.

Parameters:

length (int | None) – Length of packet data, as the caller declared it, or None to measure what is left in self._file.

Raises:

StreamEOFError – If fewer than twelve octets are left to read.

A PCAP-NG block is twelve octets at its smallest – Block Type, Block Total Length and the trailing copy of it, over an empty body – which is what __length_hint__() reports. A tail shorter than that is not a block, so parsing one out of it can only invent fields from FieldBase.unpack’s zero padding, and once the four octets of PCAPNG.type have been padded out of nothing __length__ is negative – which pcapng_block_selector() hands to SchemaField, where io.RawIOBase.read() raises the bare ValueError of #678.

Reporting the end of the stream instead is what keeps the #431 accommodation: StreamEOFError is an EOFError, which Extractor.record_frames already catches to stop with the frames read so far, so – unlike a refusal inside FieldBase.unpack, which has no catch point above it and would abort the whole extraction – this costs no frame that was actually in the file. It is the same signal prepare() raises for a derived remainder of exactly zero; a remainder of one, two or three octets passes that check and is caught here instead.

Note

This runs on both of unpack()’s paths. On the parsing path the tail is what the file has left to read; on the construction path it is the octets of a block handed to make() as raw bytes, which unpack() parses off the buffer pack() has just filled (#2354) – a caller’s octets are no more trustworthy than a file’s. Octets too short for this floor are therefore refused here rather than by read()’s own Block Total Length check, which sees only what gets past the floor and so names an impossible declared length, never a tail too short to declare one.

Measuring an undeclared length needs the stream to seek, and nothing guards that here because __post_init__() has already called tell() on it to record _seek_set: a stream that could not seek never reaches this method.

_get_payload()[source]

Get payload of self.__header__.

Return type:

bytes

Returns:

Payload of self.__header__ as bytes.

See also

This is a wrapper function for pcapkit.protocols.schema.Schema.get_payload().

Note

A packet block kept as captured has no payload (see _read_block_short()).

_get_timezone(interface_id=0)[source]

Timezone of the current block.

Parameters:

interface_id (int) – Interface ID that the current block associates with.

Return type:

timezone

Returns:

Timezone of the current block.

_make_mac_addr(addr, *, size=6, name='MAC address', alias=None)[source]

Make a MAC address, or an EUI-64 one with size=8.

Parameters:
Return type:

bytes

Returns:

The address packed as size octets, 6 by default.

Raises:

ProtocolError – If addr is not a str, bytes or bytearray (a bool included), or is not a :- or --separated hex encoded address of size octets.

_decode_next_layer(dict_, proto=None, length=None, *, packet=None)[source]

Decode next layer protocol.

Parameters:
Return type:

PCAPNG

Returns:

Current protocol with packet extracted.

Notes

dict_ gains __next_type__ and __next_name__, the next layer’s protocol type and name, which Info.to_dict carries and the dumpers leave out, and protocols, the protocol chain of the current packet (frame).

proto is dispatched as _dispatch_linktype() says, so LINKTYPE_RAW data is read as IPv4 or IPv6 (#1502).

_dispatch_linktype(proto, length=None)[source]

Link type a packet block’s data is dispatched under.

Parameters:

  • proto (int | None) – link type of the interface the block was captured on

  • length (int | None) – valid (non-padding) length

Return type:

int | None

Returns:

For LinkType.RAW data whose first octet carries IP version 4 or 6, LinkType.IPV4 or LinkType.IPV6; otherwise proto.

Note

As Frame._dispatch_linktype does for PCAP: LINKTYPE_RAW (101) data is IPv4 or IPv6 by its version nibble, an entry registered under RAW itself is used as it stands, and data of any other version is kept as Raw (#1502).

_read_pcapng_options(options_schema)[source]

Read PCAP-NG options.

Structure of PCAP-NG option:

                     1                   2                   3
 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|      Option Code              |         Option Length         |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
/                       Option Value                            /
/              variable length, padded to 32 bits               /
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
/                                                               /
/                 . . . other options . . .                     /
/                                                               /
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|   Option Code == opt_endofopt |   Option Length == 0          |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
Parameters:

options_schema (list[Option]) – Parsed PCAP-NG options.

Return type:

OrderedMultiDict[OptionType, Option]

Returns:

Parsed PCAP-NG options data.

_read_nrb_records(records_schema)[source]

Read PCAP-NG name resolution records.

Parameters:

records_schema (list[NameResolutionRecord]) – Parsed name resolution records.

Return type:

OrderedMultiDict[RecordType, NameResolutionRecord]

Returns:

Parsed PCAP-NG name resolution records data.

_make_pcapng_options(options, namespace)[source]

Make options for PCAP-NG.

Parameters:
Return type:

tuple[list[Option | bytes], int]

Returns:

Tuple of options and total length of options.

Raises:

ProtocolError – If an option’s code is a name, a bool, or a code the 16-bit option code field cannot carry (#2594), or if an option given as raw octets is shorter than that field (#2723).

_make_nrb_records(records)[source]

Make name resolution records for PCAP-NG.

Parameters:

records (OrderedMultiDict[RecordType, NameResolutionRecord] | list[NameResolutionRecord | tuple[RecordType | int, dict[str, Any]] | bytes] | bytes) – PCAP-NG name resolution records.

Return type:

tuple[list[NameResolutionRecord | bytes], int]

Returns:

Tuple of name resolution records and total length of the records.

Raises:

ProtocolError – If a record’s type is a name, a bool, or a code the 16-bit record type field cannot carry (#2594), or if a record given as raw octets is shorter than that field (#2723).

Auxiliary Data

class pcapkit.protocols.misc.pcapng.protocol.PacketDirection(*values)[source]

Bases: EnumLookup, IntEnum

Packet direction for epb_flags options.

Shares the EnumLookup lookup contract that every non-registry enumeration follows (#877). Its _missing_ resolves the one value the specification leaves undefined, 0b11, to an unassigned member, so a capture carrying it still parses and rebuilds (#1382).

UNKNOWN = 0

Information not available.

INBOUND = 1

Inbound packet.

OUTBOUND = 2

Outbound packet.

classmethod _missing_(value)[source]

Lookup function used when value is not found.

Parameters:

value (object) – Value to get enum item.

Return type:

PacketDirection

Returns:

An unassigned member, absent from the lookup tables.

Raises:

EnumValueError – If value does not fit the 2-bit sub-field.

class pcapkit.protocols.misc.pcapng.protocol.PacketReception(*values)[source]

Bases: EnumLookup, IntEnum

Reception type for epb_flags options.

Shares the EnumLookup lookup contract that every non-registry enumeration follows (#877). Its _missing_ resolves the values the specification leaves undefined, 0b101 to 0b111, to an unassigned member, so a capture carrying one still parses and rebuilds (#1382).

UNKNOWN = 0

Not specified.

UNICAST = 1

Unicast.

MULTICAST = 2

Multicast.

BROADCAST = 3

Broadcast.

PROMISCUOUS = 4

Promiscuous.

classmethod _missing_(value)[source]

Lookup function used when value is not found.

Parameters:

value (object) – Value to get enum item.

Return type:

PacketReception

Returns:

An unassigned member, absent from the lookup tables.

Raises:

EnumValueError – If value does not fit the 3-bit sub-field.

TLSKeyLabel is defined in pcapkit.const.pcapng.tls_key_label, generated like its pcapkit.const.pcapng siblings because RFC 9850 Section 4.2 makes it an IANA registry.

Removed in version 1.5.0: pcapkit.protocols.misc.pcapng.TLSKeyLabel, with no alias; use pcapkit.const.pcapng.tls_key_label.TLSKeyLabel instead (#886, #1744).

class pcapkit.protocols.misc.pcapng.protocol.WireGuardKeyLabel(*values)[source]

Bases: EnumLookup, StrEnum

WireGuard key log label.

Shares the EnumLookup lookup contract that every non-registry enumeration follows (#877); it defines neither get nor _missing_ of its own.

LOCAL_STATIC_PRIVATE_KEY = 'LOCAL_STATIC_PRIVATE_KEY'
REMOTE_STATIC_PUBLIC_KEY = 'REMOTE_STATIC_PUBLIC_KEY'
LOCAL_EPHEMERAL_PRIVATE_KEY = 'LOCAL_EPHEMERAL_PRIVATE_KEY'
PRESHARED_KEY = 'PRESHARED_KEY'

Header Schemas

Removed in version 1.6.0: pcapkit.protocols.schema.misc.pcapng, with no alias: the module moved here (#2534).

pcapkit.protocols.misc.pcapng.schema.BYTE_ORDER_MAGIC = 439041101

Byte-Order Magic of a Section Header Block, read in the byte order of the section that wrote it. The one home of this value (#1739); the format fixes it, so it is never configurable.

Added in version 1.5.0.

pcapkit.protocols.misc.pcapng.schema.GENERIC_BLOCK_MINIMUM = 12

The octets every block’s fixed fields span – Block Type and both copies of Block Total Length – and so the shortest Block Total Length of any block, and the whole of it for a block not in BLOCK_MINIMUM. The one home of this value (#1739); the format fixes it, so it is never configurable.

Added in version 1.5.0.

pcapkit.protocols.misc.pcapng.schema.BLOCK_MINIMUM: Dict[int, int]

Block types mapped to the octets their fixed fields span, Block Type and both copies of Block Total Length included; any other block spans GENERIC_BLOCK_MINIMUM. The one home of these values (#1739); the format fixes them, so they are never configurable.

Added in version 1.5.0.

pcapkit.protocols.misc.pcapng.schema.DEFAULT_RESOLUTION = 1000000

Units per second of a timestamp on an interface that carries no if_tsresol option: microseconds, the default the format gives that option. The one home of this value (#1739); the format fixes it, so it is never configurable.

Added in version 1.5.0.

pcapkit.protocols.misc.pcapng.schema.PACKET_FLAGS: dict[str, tuple[int, int]]

Sub-fields of the epb_flags and pack_flags words. reserved keeps bits 12 to 23 verbatim – the reserved bits 12-15 and the link-layer-dependent error bits 16-23 that the data model does not name.

class pcapkit.protocols.misc.pcapng.schema.PCAPNG(type=NO_VALUE, block=NO_VALUE, *, __packet__=None, **kwargs)[source]

Bases: Schema

Header schema for a PCAP-NG file block: its type, then its body.

type: BlockType = <EnumField type>

Block type.

block: BlockType = <SwitchField block>

Block specific data.

class pcapkit.protocols.misc.pcapng.schema.BlockType(*args, **kwargs)[source]

Bases: EnumSchema[BlockType]

Base header schema for the body of each PCAP-NG block type.

post_process(packet)[source]

Revise schema data after unpacking process.

This method compares the two block lengths and issues a ProtocolWarning if they are not equal.

Parameters:

packet (dict[str, Any]) – Unpacked data.

Return type:

Schema

Returns:

Revised schema.

class pcapkit.protocols.misc.pcapng.schema.UnknownBlock(length=NO_VALUE, body=NO_VALUE, length2=NO_VALUE, *, __packet__=None, **kwargs)[source]

Bases: BlockType

Header schema for unknown PCAP-NG file blocks.

length: int = <UInt32Field length>

Block total length.

body: bytes = <BytesField body>

Block body (including padding).

length2: int = <UInt32Field length2>

Block total length.

class pcapkit.protocols.misc.pcapng.schema.SectionHeaderBlock(match=NO_VALUE, length=NO_VALUE, magic=NO_VALUE, major=NO_VALUE, minor=NO_VALUE, section_length=NO_VALUE, options=NO_VALUE, padding=NO_VALUE, length2=NO_VALUE, *, __packet__=None, **kwargs)[source]

Bases: BlockType

Header schema for PCAP-NG Section Header Block (SHB).

match: ByteorderTest = <ForwardMatchField match>

Fast-forward field to test the byte order.

length: int = <UInt32Field length>

Block total length.

magic: Literal[439041101] = <UInt32Field magic>

Byte order magic number.

major: int = <UInt16Field major>

Major version number.

minor: int = <UInt16Field minor>

Minor version number.

section_length: int = <Int64Field section_length>

Section length.

options: list[Option] = <OptionAreaField options>

Options.

padding: bytes = <PaddingField padding>

Padding, sized from the __option_padding__ key that OptionField generates.

length2: int = <UInt32Field length2>

Block total length.

pre_pack(packet)[source]

Prepare packet data for packing process.

Parameters:

packet (dict[str, Any]) – packet data

Note

This method is expected to directly modify any data stored in the packet and thus no return is required.

shb_byteorder_callback() takes the byte order from the Byte-Order Magic as match reads it, and a constructed block has no match to read – a forward match packs no octets – nor can magic stand in, since it holds the same constant in either byte order. So match is seeded here from the byte order the packet data asks for, and from the host byte order when it asks for none; a match already in packet is kept.

post_process(packet)[source]

Revise schema data after unpacking process.

This method calculates the byte order value based on the parsed schema.

Parameters:

packet (dict[str, Any]) – Unpacked data.

Return type:

SectionHeaderBlock

Returns:

Revised schema.

A Block Total Length below the 28 octets of the fixed fields reads the trailing copy past the block, so the two are not compared here; PCAPNG._read_block_short_header keeps the block as captured and compares them itself (#1422). A block of 12 octets has no Byte-Order Magic and takes its byte order from its Block Total Length (see shb_byteorder_callback()).

byteorder: Literal['big', 'little']

Byte order.

class pcapkit.protocols.misc.pcapng.schema.InterfaceDescriptionBlock(length=NO_VALUE, linktype=NO_VALUE, reserved=NO_VALUE, snaplen=NO_VALUE, options=NO_VALUE, padding=NO_VALUE, length2=NO_VALUE, *, __packet__=None, **kwargs)[source]

Bases: BlockType

Header schema for PCAP-NG Interface Description Block (IDB).

length: int = <UInt32Field length>

Block total length.

linktype: LinkType = <EnumField linktype>

Link type.

reserved: bytes = <PaddingField reserved>

Reserved.

snaplen: int = <UInt32Field snaplen>

Snap length.

options: list[Option] = <OptionAreaField options>

Options.

padding: bytes = <PaddingField padding>

Padding, sized from the __option_padding__ key that OptionField generates.

length2: int = <UInt32Field length2>

Block total length.

post_process(packet)[source]

Revise schema data after unpacking process.

Parameters:

packet (dict[str, Any]) – Unpacked data.

Return type:

Schema

Returns:

Revised schema.

A Block Total Length below the 20 octets of the fixed fields reads the trailing copy past the block, so the two are not compared here; PCAPNG._read_block_short_header keeps the block as captured and compares them itself (#1422).

class pcapkit.protocols.misc.pcapng.schema.EnhancedPacketBlock(length=NO_VALUE, interface_id=NO_VALUE, timestamp_high=NO_VALUE, timestamp_low=NO_VALUE, captured_len=NO_VALUE, original_len=NO_VALUE, packet_data=NO_VALUE, padding_data=NO_VALUE, options=NO_VALUE, padding_opts=NO_VALUE, length2=NO_VALUE, *, __packet__=None, **kwargs)[source]

Bases: BlockType

Header schema for PCAP-NG Enhanced Packet Block (EPB).

length: int = <UInt32Field length>

Block total length.

interface_id: int = <UInt32Field interface_id>

Interface ID.

timestamp_high: int = <UInt32Field timestamp_high>

Timestamp (higher 32 bits).

timestamp_low: int = <UInt32Field timestamp_low>

Timestamp (lower 32 bits).

captured_len: int = <UInt32Field captured_len>

Captured packet length.

original_len: int = <UInt32Field original_len>

Original packet length.

packet_data: bytes = <PayloadField packet_data>

Packet data, bounded by the block (see captured_area()).

padding_data: bytes = <PaddingField padding_data>

Padding.

options: list[Option] = <OptionAreaField options>

Options.

padding_opts: bytes = <PaddingField padding_opts>

Padding, sized from the __option_padding__ key that OptionField generates.

length2: int = <UInt32Field length2>

Block total length.

post_process(packet)[source]

Revise schema data after unpacking process.

Parameters:

packet (dict[str, Any]) – Unpacked data.

Return type:

Schema

Returns:

Revised schema.

A Block Total Length below the 32 octets of the fixed fields reads the trailing copy past the block, so the two are not compared here; PCAPNG._read_block_short keeps the block as captured and compares them itself (#1414).

class pcapkit.protocols.misc.pcapng.schema.SimplePacketBlock(length=NO_VALUE, original_len=NO_VALUE, packet_data=NO_VALUE, padding=NO_VALUE, length2=NO_VALUE, *, __packet__=None, **kwargs)[source]

Bases: BlockType

Header schema for PCAP-NG Simple Packet Block (SPB).

length: int = <UInt32Field length>

Block total length.

original_len: int = <UInt32Field original_len>

Original packet length.

packet_data: bytes = <PayloadField packet_data>

Packet data, min(original_len, snaplen) octets, bounded by what the block holds; see _spb_data_length().

padding: bytes = <PaddingField padding>

Padding.

length2: int = <UInt32Field length2>

Block total length.

class pcapkit.protocols.misc.pcapng.schema.NameResolutionBlock(length=NO_VALUE, records=NO_VALUE, options=NO_VALUE, padding=NO_VALUE, length2=NO_VALUE, *, __packet__=None, **kwargs)[source]

Bases: BlockType

Header schema for PCAP-NG Name Resolution Block (NRB).

length: int = <UInt32Field length>

Block total length.

records: list[NameResolutionRecord] = <OptionAreaField records>

Name resolution records.

options: list[Option] = <OptionAreaField options>

Options.

padding: bytes = <PaddingField padding>

Padding, sized from the __option_padding__ key that OptionField generates.

length2: int = <UInt32Field length2>

Block total length.

post_process(packet)[source]

Revise schema data after unpacking process.

Parameters:

packet (dict[str, Any]) – Unpacked data.

Return type:

Self

Returns:

Revised schema.

mapping: MultiDict[IPv4Address | IPv6Address, str]

Name resolution mapping (IP address -> name).

reverse_mapping: MultiDict[str, IPv4Address | IPv6Address]

Name resolution mapping (name -> IP address).

class pcapkit.protocols.misc.pcapng.schema.InterfaceStatisticsBlock(length=NO_VALUE, interface_id=NO_VALUE, timestamp_high=NO_VALUE, timestamp_low=NO_VALUE, options=NO_VALUE, padding=NO_VALUE, length2=NO_VALUE, *, __packet__=None, **kwargs)[source]

Bases: BlockType

Header schema for PCAP-NG Interface Statistics Block (ISB).

length: int = <UInt32Field length>

Block total length.

interface_id: int = <UInt32Field interface_id>

Interface ID.

timestamp_high: int = <UInt32Field timestamp_high>

Timestamp (higher 32 bits).

timestamp_low: int = <UInt32Field timestamp_low>

Timestamp (lower 32 bits).

options: list[Option] = <OptionAreaField options>

Options.

padding: bytes = <PaddingField padding>

Padding, sized from the __option_padding__ key that OptionField generates.

length2: int = <UInt32Field length2>

Block total length.

class pcapkit.protocols.misc.pcapng.schema.SystemdJournalExportBlock(length=NO_VALUE, entry=NO_VALUE, length2=NO_VALUE, *, __packet__=None, **kwargs)[source]

Bases: BlockType

Header schema for PCAP-NG systemd(1) Journal Export Block.

length: int = <UInt32Field length>

Block total length.

entry: bytes = <BytesField entry>

Journal entry.

length2: int = <UInt32Field length2>

Block total length.

post_process(packet)[source]

Revise schema data after unpacking process.

Parameters:

packet (dict[str, Any]) – Unpacked data.

Return type:

Self

Returns:

Revised schema.

Note

The entry is walked once, end to end, rather than split apart with self.entry.split(b'\n\n'): that delimits a length-prefixed format by content, which a binary field’s own bytes need no escaping to defeat (struct.pack('<Q', 2570) == b'\n\n\x00\x00\x00\x00\x00\x00' puts the separator inside the length prefix itself). A binary field’s value is counted out by its prefix and never inspected; a blank line – found by reading – starts the next entry, even an empty one behind a trailing separator. A line of nothing but NUL octets at the end of the entry is the block’s own 32-bit padding and ends it.

The walk is strict (#1406, #1413, and #1325, under which OptionAreaField applies to option areas). Any of the following raises ProtocolError, and the whole entry is then kept as the octets captured, as the one bytes item of data, which the block’s make writes back verbatim:

  • a line, text field or binary field name, with no terminating newline, e.g. a bare KEY at the end of the entry;

  • a binary field whose 64-bit length prefix is cut short, or declares more octets than the entry has left – at 2**63 and above io.BytesIO.read() would refuse it with a bare OverflowError;

  • a binary field’s value not followed by the newline that terminates it, including one that ends the entry;

  • any other entry that the parsed fields would not rebuild octet for octet, e.g. a field that is not UTF-8.

A struct.error, OverflowError or UnicodeDecodeError is neither one of pcapkit.utilities.exceptions nor an EOFError, so any of them would abort the whole extraction rather than this one entry. Field names, keys and values are therefore decoded with errors='replace' and reported, which the rebuild check then catches, rather than strictly.

static dump_entries(entries)[source]

Serialise journal entries, without the block’s 32-bit padding.

Parameters:

entries (list[OrderedMultiDict[str, str | bytes]]) – The journal entries.

Return type:

bytes

Returns:

Each field as KEY=value\n, or for a binary value as the name, a newline, its 64-bit little-endian length, the value and a newline, with one blank line between entries.

data: list[OrderedMultiDict[str, str | bytes] | bytes]

Journal entry (decoded), or the entry as captured, as one bytes item, if it is malformed.

_read_entries()[source]

Walk entry into its journal entries, as post_process() describes.

Return type:

list[OrderedMultiDict[str, str | bytes]]

Returns:

The journal entries.

Raises:

ProtocolError – If the entry is malformed, as post_process() lists.

static _decode_text(octets)[source]

Decode a journal field name, key or value, reporting what did not decode.

Parameters:

octets (bytes) – Field name, key or value, as it came off the wire.

Return type:

str

Returns:

The decoded text, with any octet that is not UTF-8 replaced.

See post_process() for why this replaces rather than raising.

class pcapkit.protocols.misc.pcapng.schema.DecryptionSecretsBlock(length=NO_VALUE, secrets_type=NO_VALUE, secrets_length=NO_VALUE, secrets_data=NO_VALUE, padding_data=NO_VALUE, options=NO_VALUE, padding_opts=NO_VALUE, length2=NO_VALUE, *, __packet__=None, **kwargs)[source]

Bases: BlockType

Header schema for PCAP-NG Decryption Secrets Block (DSB).

length: int = <UInt32Field length>

Block total length.

secrets_type: SecretsType = <EnumField secrets_type>

Secrets type.

secrets_length: int = <UInt32Field secrets_length>

Secrets length.

secrets_data: DSBSecrets = <SwitchField secrets_data>

Secrets data, bounded by the block (see secrets_area()).

padding_data: bytes = <PaddingField padding_data>

Padding.

options: list[Option] = <OptionAreaField options>

Options.

padding_opts: bytes = <PaddingField padding_opts>

Padding, sized from the __option_padding__ key that OptionField generates.

length2: int = <UInt32Field length2>

Block total length.

post_process(packet)[source]

Revise schema data after unpacking process.

Parameters:

packet (dict[str, Any]) – Unpacked data.

Return type:

Schema

Returns:

Revised schema.

A secrets_length running past the block is kept as declared, and the secrets are the octets the block holds (see secrets_area()), so this reports the overrun as a ProtocolWarning and carries on to the next block (#1980).

The report is made on the unpacking path only, where __length__ is what is left of the stream. Schema.pack seeds it as -1, and rebuilding a block already reported is no new overrun. The lengths are read from the schema rather than from packet, since packing the option area rebinds packet['length'] to each option’s own length.

class pcapkit.protocols.misc.pcapng.schema.CustomBlock(length=NO_VALUE, pen=NO_VALUE, data=NO_VALUE, length2=NO_VALUE, *, __packet__=None, **kwargs)[source]

Bases: BlockType

Header schema for PCAP-NG Custom Block (CB).

Note

The block carries no length for its custom data, so where the custom data ends and the block options begin is known only to the owner of the private enterprise number. data therefore spans the whole region between pen and the trailing block total length, i.e. the custom data, its padding to a 32-bit boundary, and any options.

length: int = <UInt32Field length>

Block total length.

pen: int = <UInt32Field pen>

Private enterprise number.

data: bytes = <BytesField data>

Custom data (incl. padding and options).

length2: int = <UInt32Field length2>

Block total length.

class pcapkit.protocols.misc.pcapng.schema.PacketBlock(length=NO_VALUE, interface_id=NO_VALUE, drop_count=NO_VALUE, timestamp_high=NO_VALUE, timestamp_low=NO_VALUE, captured_length=NO_VALUE, original_length=NO_VALUE, packet_data=NO_VALUE, padding_data=NO_VALUE, options=NO_VALUE, padding_opts=NO_VALUE, length2=NO_VALUE, *, __packet__=None, **kwargs)[source]

Bases: BlockType

Header schema for PCAP-NG Packet Block (obsolete).

length: int = <UInt32Field length>

Block total length.

interface_id: int = <UInt16Field interface_id>

Interface ID.

drop_count: int = <UInt16Field drop_count>

Drops count.

timestamp_high: int = <UInt32Field timestamp_high>

Timestamp (high).

timestamp_low: int = <UInt32Field timestamp_low>

Timestamp (low).

captured_length: int = <UInt32Field captured_length>

Captured packet length.

original_length: int = <UInt32Field original_length>

Original packet length.

packet_data: bytes = <PayloadField packet_data>

Packet data, bounded by the block (see captured_area()).

padding_data: bytes = <PaddingField padding_data>

Padding.

options: list[Option] = <OptionAreaField options>

Options.

padding_opts: bytes = <PaddingField padding_opts>

Padding, sized from the __option_padding__ key that OptionField generates.

length2: int = <UInt32Field length2>

Block total length.

post_process(packet)[source]

Revise schema data after unpacking process.

Parameters:

packet (dict[str, Any]) – Unpacked data.

Return type:

Schema

Returns:

Revised schema.

A Block Total Length below the 32 octets of the fixed fields reads the trailing copy past the block, so the two are not compared here; PCAPNG._read_block_short keeps the block as captured and compares them itself (#1414).

class pcapkit.protocols.misc.pcapng.schema.Option(*args, **kwargs)[source]

Bases: EnumSchema[OptionType]

Header schema for PCAP-NG file options.

__enum__: DefaultDict[str, DefaultDict[OptionType, Type[Option]]] = {'dsb': {<OptionType.opt_endofopt: 0>: <class 'pcapkit.protocols.misc.pcapng.schema.EndOfOption'>, <OptionType.opt_comment: 1>: <class 'pcapkit.protocols.misc.pcapng.schema.CommentOption'>, <OptionType.opt_custom: 2988>: <class 'pcapkit.protocols.misc.pcapng.schema.CustomOption'>, <OptionType.opt_custom: 2989>: <class 'pcapkit.protocols.misc.pcapng.schema.CustomOption'>, <OptionType.opt_custom: 19372>: <class 'pcapkit.protocols.misc.pcapng.schema.CustomOption'>, <OptionType.opt_custom: 19373>: <class 'pcapkit.protocols.misc.pcapng.schema.CustomOption'>}, 'epb': {<OptionType.opt_endofopt: 0>: <class 'pcapkit.protocols.misc.pcapng.schema.EndOfOption'>, <OptionType.opt_comment: 1>: <class 'pcapkit.protocols.misc.pcapng.schema.CommentOption'>, <OptionType.epb_flags: 2>: <class 'pcapkit.protocols.misc.pcapng.schema.EPB_FlagsOption'>, <OptionType.epb_hash: 3>: <class 'pcapkit.protocols.misc.pcapng.schema.EPB_HashOption'>, <OptionType.epb_dropcount: 4>: <class 'pcapkit.protocols.misc.pcapng.schema.EPB_DropCountOption'>, <OptionType.epb_packetid: 5>: <class 'pcapkit.protocols.misc.pcapng.schema.EPB_PacketIDOption'>, <OptionType.epb_queue: 6>: <class 'pcapkit.protocols.misc.pcapng.schema.EPB_QueueOption'>, <OptionType.epb_verdict: 7>: <class 'pcapkit.protocols.misc.pcapng.schema.EPB_VerdictOption'>, <OptionType.opt_custom: 2988>: <class 'pcapkit.protocols.misc.pcapng.schema.CustomOption'>, <OptionType.opt_custom: 2989>: <class 'pcapkit.protocols.misc.pcapng.schema.CustomOption'>, <OptionType.opt_custom: 19372>: <class 'pcapkit.protocols.misc.pcapng.schema.CustomOption'>, <OptionType.opt_custom: 19373>: <class 'pcapkit.protocols.misc.pcapng.schema.CustomOption'>}, 'if': {<OptionType.opt_endofopt: 0>: <class 'pcapkit.protocols.misc.pcapng.schema.EndOfOption'>, <OptionType.opt_comment: 1>: <class 'pcapkit.protocols.misc.pcapng.schema.CommentOption'>, <OptionType.if_name: 2>: <class 'pcapkit.protocols.misc.pcapng.schema.IF_NameOption'>, <OptionType.if_description: 3>: <class 'pcapkit.protocols.misc.pcapng.schema.IF_DescriptionOption'>, <OptionType.if_IPv4addr: 4>: <class 'pcapkit.protocols.misc.pcapng.schema.IF_IPv4AddrOption'>, <OptionType.if_IPv6addr: 5>: <class 'pcapkit.protocols.misc.pcapng.schema.IF_IPv6AddrOption'>, <OptionType.if_MACaddr: 6>: <class 'pcapkit.protocols.misc.pcapng.schema.IF_MACAddrOption'>, <OptionType.if_EUIaddr: 7>: <class 'pcapkit.protocols.misc.pcapng.schema.IF_EUIAddrOption'>, <OptionType.if_speed: 8>: <class 'pcapkit.protocols.misc.pcapng.schema.IF_SpeedOption'>, <OptionType.if_tsresol: 9>: <class 'pcapkit.protocols.misc.pcapng.schema.IF_TSResolOption'>, <OptionType.if_tzone: 10>: <class 'pcapkit.protocols.misc.pcapng.schema.IF_TZoneOption'>, <OptionType.if_filter: 11>: <class 'pcapkit.protocols.misc.pcapng.schema.IF_FilterOption'>, <OptionType.if_os: 12>: <class 'pcapkit.protocols.misc.pcapng.schema.IF_OSOption'>, <OptionType.if_fcslen: 13>: <class 'pcapkit.protocols.misc.pcapng.schema.IF_FCSLenOption'>, <OptionType.if_tsoffset: 14>: <class 'pcapkit.protocols.misc.pcapng.schema.IF_TSOffsetOption'>, <OptionType.if_hardware: 15>: <class 'pcapkit.protocols.misc.pcapng.schema.IF_HardwareOption'>, <OptionType.if_txspeed: 16>: <class 'pcapkit.protocols.misc.pcapng.schema.IF_TxSpeedOption'>, <OptionType.if_rxspeed: 17>: <class 'pcapkit.protocols.misc.pcapng.schema.IF_RxSpeedOption'>, <OptionType.opt_custom: 2988>: <class 'pcapkit.protocols.misc.pcapng.schema.CustomOption'>, <OptionType.opt_custom: 2989>: <class 'pcapkit.protocols.misc.pcapng.schema.CustomOption'>, <OptionType.opt_custom: 19372>: <class 'pcapkit.protocols.misc.pcapng.schema.CustomOption'>, <OptionType.opt_custom: 19373>: <class 'pcapkit.protocols.misc.pcapng.schema.CustomOption'>}, 'isb': {<OptionType.opt_endofopt: 0>: <class 'pcapkit.protocols.misc.pcapng.schema.EndOfOption'>, <OptionType.opt_comment: 1>: <class 'pcapkit.protocols.misc.pcapng.schema.CommentOption'>, <OptionType.isb_starttime: 2>: <class 'pcapkit.protocols.misc.pcapng.schema.ISB_StartTimeOption'>, <OptionType.isb_endtime: 3>: <class 'pcapkit.protocols.misc.pcapng.schema.ISB_EndTimeOption'>, <OptionType.isb_ifrecv: 4>: <class 'pcapkit.protocols.misc.pcapng.schema.ISB_IFRecvOption'>, <OptionType.isb_ifdrop: 5>: <class 'pcapkit.protocols.misc.pcapng.schema.ISB_IFDropOption'>, <OptionType.isb_filteraccept: 6>: <class 'pcapkit.protocols.misc.pcapng.schema.ISB_FilterAcceptOption'>, <OptionType.isb_osdrop: 7>: <class 'pcapkit.protocols.misc.pcapng.schema.ISB_OSDropOption'>, <OptionType.isb_usrdeliv: 8>: <class 'pcapkit.protocols.misc.pcapng.schema.ISB_UsrDelivOption'>, <OptionType.opt_custom: 2988>: <class 'pcapkit.protocols.misc.pcapng.schema.CustomOption'>, <OptionType.opt_custom: 2989>: <class 'pcapkit.protocols.misc.pcapng.schema.CustomOption'>, <OptionType.opt_custom: 19372>: <class 'pcapkit.protocols.misc.pcapng.schema.CustomOption'>, <OptionType.opt_custom: 19373>: <class 'pcapkit.protocols.misc.pcapng.schema.CustomOption'>}, 'ns': {<OptionType.opt_endofopt: 0>: <class 'pcapkit.protocols.misc.pcapng.schema.EndOfOption'>, <OptionType.opt_comment: 1>: <class 'pcapkit.protocols.misc.pcapng.schema.CommentOption'>, <OptionType.ns_dnsname: 2>: <class 'pcapkit.protocols.misc.pcapng.schema.NS_DNSNameOption'>, <OptionType.ns_dnsIP4addr: 3>: <class 'pcapkit.protocols.misc.pcapng.schema.NS_DNSIP4AddrOption'>, <OptionType.ns_dnsIP6addr: 4>: <class 'pcapkit.protocols.misc.pcapng.schema.NS_DNSIP6AddrOption'>, <OptionType.opt_custom: 2988>: <class 'pcapkit.protocols.misc.pcapng.schema.CustomOption'>, <OptionType.opt_custom: 2989>: <class 'pcapkit.protocols.misc.pcapng.schema.CustomOption'>, <OptionType.opt_custom: 19372>: <class 'pcapkit.protocols.misc.pcapng.schema.CustomOption'>, <OptionType.opt_custom: 19373>: <class 'pcapkit.protocols.misc.pcapng.schema.CustomOption'>}, 'opt': {<OptionType.opt_endofopt: 0>: <class 'pcapkit.protocols.misc.pcapng.schema.EndOfOption'>, <OptionType.opt_comment: 1>: <class 'pcapkit.protocols.misc.pcapng.schema.CommentOption'>, <OptionType.opt_custom: 2988>: <class 'pcapkit.protocols.misc.pcapng.schema.CustomOption'>, <OptionType.opt_custom: 2989>: <class 'pcapkit.protocols.misc.pcapng.schema.CustomOption'>, <OptionType.opt_custom: 19372>: <class 'pcapkit.protocols.misc.pcapng.schema.CustomOption'>, <OptionType.opt_custom: 19373>: <class 'pcapkit.protocols.misc.pcapng.schema.CustomOption'>}, 'pack': {<OptionType.opt_endofopt: 0>: <class 'pcapkit.protocols.misc.pcapng.schema.EndOfOption'>, <OptionType.opt_comment: 1>: <class 'pcapkit.protocols.misc.pcapng.schema.CommentOption'>, <OptionType.pack_flags: 2>: <class 'pcapkit.protocols.misc.pcapng.schema.PACK_FlagsOption'>, <OptionType.pack_hash: 3>: <class 'pcapkit.protocols.misc.pcapng.schema.PACK_HashOption'>, <OptionType.opt_custom: 2988>: <class 'pcapkit.protocols.misc.pcapng.schema.CustomOption'>, <OptionType.opt_custom: 2989>: <class 'pcapkit.protocols.misc.pcapng.schema.CustomOption'>, <OptionType.opt_custom: 19372>: <class 'pcapkit.protocols.misc.pcapng.schema.CustomOption'>, <OptionType.opt_custom: 19373>: <class 'pcapkit.protocols.misc.pcapng.schema.CustomOption'>}}

Mapping of PCAP-NG option type numbers to schemas.

static register(code, cls, ns=None)[source]

Register option type to __enum__ mapping.

Parameters:

  • code (OptionType) – Option type code.

  • cls (Type[Option]) – Option type schema.

  • ns (str | None) – Namespace of option type enumeration, inferred from the option type code if not given.

Return type:

None

A registration that displaces another schema for the same code is reported as a RegistryWarning, as every other registry in the package does – the lookup that follows cannot tell a deliberate replacement from an accidental one, so an unreported overwrite is a parser silently swapped out for another.

The guard is identity-based: it fires only when the incumbent differs from cls, so re-registering the exact same class under the same code is a silent no-op – in every namespace targets reaches – rather than a warning about nothing displaced. That is what keeps __init_subclass__() honest: it loops over a code list with no deduplication, so a repeated or aliased entry reaches this method twice with the same class, and the second call finds itself already the incumbent.

Note

ns='opt' fans one registration out across every namespace, so the collision is reported once for the registration and names the namespaces it displaced something in, sorted, rather than once per namespace.

A namespace created by this call starts as a copy of opt’s defaults, so nothing in it is a prior registration and it is exempt: registering an opt-namespace code into a brand-new namespace is exactly what that copy is for.

Membership is tested with .get(), never by subscripting. The per-namespace registries are collections.defaultdicts – only the outer one is the miss-safe _EnumRegistry – so reading Option.registry[key][code] to see whether it is there would insert UnknownOption for a code nobody registered.

Changed in version 1.6.0: The warning names the namespaces sorted, rather than in the order of __enum__ (#2772).

classmethod __init_subclass__(code=None, ns=None, *args, **kwargs)[source]

Register option type to __enum__ mapping.

Parameters:

  • code (OptionType | Iterable[OptionType] | None) – Option type code. It can be either a single option type enumeration or a list of option type enumerations.

  • ns (str | None) – Namespace of option type enumeration, inferred from the option type code if not given. Not namespace: before Python 3.11, abc.ABCMeta.__new__() takes its own parameter of that name by keyword too, so a class keyword so named binds it twice.

  • *args (Any) – Arbitrary positional arguments.

  • **kwargs (Any) – Arbitrary keyword arguments.

Return type:

None

Given code, the subclass is registered under it in the __enum__ mapping; otherwise it is not registered.

Examples

from pcapkit.const.pcapng.option_type import OptionType as Enum_OptionType
from pcapkit.protocols.misc.pcapng.schema import Option

class NewOption(Option, ns='opt', code=Enum_OptionType.opt_new):
    ...

See also

Changed in version 1.5.0: The class keyword namespace is renamed ns, with no alias (#439).

type: OptionType

Option type.

length: int

Option data length.

class pcapkit.protocols.misc.pcapng.schema._OPT_Option(*args, **kwargs)[source]

Bases: Option

Header schema for opt_* options.

type: OptionType = <OptionEnumField type>

Option type.

length: int = <UInt16Field length>

Option data length.

class pcapkit.protocols.misc.pcapng.schema.UnknownOption(type=NO_VALUE, length=NO_VALUE, data=NO_VALUE, padding=NO_VALUE, *, __packet__=None, **kwargs)[source]

Bases: _OPT_Option

Header schema for unknown PCAP-NG file options.

data: bytes = <BytesField data>

Option value.

padding: bytes = <PaddingField padding>

Padding.

class pcapkit.protocols.misc.pcapng.schema.EndOfOption(type=NO_VALUE, length=NO_VALUE, *, __packet__=None, **kwargs)[source]

Bases: _OPT_Option

Header schema for PCAP-NG file opt_endofopt options.

class pcapkit.protocols.misc.pcapng.schema.CommentOption(type=NO_VALUE, length=NO_VALUE, comment=NO_VALUE, padding=NO_VALUE, *, __packet__=None, **kwargs)[source]

Bases: _OPT_Option

Header schema for PCAP-NG file opt_comment options.

comment: str = <StringField comment>

Comment text.

padding: bytes = <PaddingField padding>

Padding.

class pcapkit.protocols.misc.pcapng.schema.CustomOption(type=NO_VALUE, length=NO_VALUE, pen=NO_VALUE, data=NO_VALUE, padding=NO_VALUE, *, __packet__=None, **kwargs)[source]

Bases: _OPT_Option

Header schema for PCAP-NG file opt_custom options.

pen: int = <UInt32Field pen>

Private enterprise number (PEN).

data: bytes = <BytesField data>

Custom data.

padding: bytes = <PaddingField padding>

Padding.

class pcapkit.protocols.misc.pcapng.schema._IF_Option(*args, **kwargs)[source]

Bases: Option

Header schema for if_* options.

type: OptionType = <OptionEnumField type>

Option type.

length: int = <UInt16Field length>

Option data length.

class pcapkit.protocols.misc.pcapng.schema.IF_NameOption(type=NO_VALUE, length=NO_VALUE, name=NO_VALUE, padding=NO_VALUE, *, __packet__=None, **kwargs)[source]

Bases: _IF_Option

Header schema for PCAP-NG file if_name options.

name: str = <StringField name>

Interface name.

padding: bytes = <PaddingField padding>

Padding.

class pcapkit.protocols.misc.pcapng.schema.IF_DescriptionOption(type=NO_VALUE, length=NO_VALUE, description=NO_VALUE, padding=NO_VALUE, *, __packet__=None, **kwargs)[source]

Bases: _IF_Option

Header schema for PCAP-NG file if_description options.

description: str = <StringField description>

Interface description.

padding: bytes = <PaddingField padding>

Padding.

class pcapkit.protocols.misc.pcapng.schema.IF_IPv4AddrOption(type=NO_VALUE, length=NO_VALUE, interface=NO_VALUE, padding=NO_VALUE, *, __packet__=None, **kwargs)[source]

Bases: _IF_Option

Header schema for PCAP-NG file if_IPv4addr options.

interface: IPv4Interface = <IPv4InterfaceField interface>

IPv4 interface.

padding: bytes = <PaddingField padding>

Padding.

class pcapkit.protocols.misc.pcapng.schema.IF_IPv6AddrOption(type=NO_VALUE, length=NO_VALUE, interface=NO_VALUE, padding=NO_VALUE, *, __packet__=None, **kwargs)[source]

Bases: _IF_Option

Header schema for PCAP-NG file if_IPv6addr options.

interface: IPv6Interface = <IPv6InterfaceField interface>

IPv6 interface.

padding: bytes = <PaddingField padding>

Padding.

class pcapkit.protocols.misc.pcapng.schema.IF_MACAddrOption(type=NO_VALUE, length=NO_VALUE, interface=NO_VALUE, padding=NO_VALUE, *, __packet__=None, **kwargs)[source]

Bases: _IF_Option

Header schema for PCAP-NG file if_MACaddr options.

interface: bytes = <BytesField interface>

MAC interface.

padding: bytes = <PaddingField padding>

Padding.

class pcapkit.protocols.misc.pcapng.schema.IF_EUIAddrOption(type=NO_VALUE, length=NO_VALUE, interface=NO_VALUE, padding=NO_VALUE, *, __packet__=None, **kwargs)[source]

Bases: _IF_Option

Header schema for PCAP-NG file if_EUIaddr options.

interface: bytes = <BytesField interface>

EUI interface.

padding: bytes = <PaddingField padding>

Padding.

class pcapkit.protocols.misc.pcapng.schema.IF_SpeedOption(type=NO_VALUE, length=NO_VALUE, speed=NO_VALUE, padding=NO_VALUE, *, __packet__=None, **kwargs)[source]

Bases: _IF_Option

Header schema for PCAP-NG file if_speed options.

speed: int = <UInt64Field speed>

Interface speed, in bits per second.

padding: bytes = <PaddingField padding>

Padding.

class pcapkit.protocols.misc.pcapng.schema.IF_TSResolOption(type=NO_VALUE, length=NO_VALUE, tsresol=NO_VALUE, padding=NO_VALUE, *, __packet__=None, **kwargs)[source]

Bases: _IF_Option

Header schema for PCAP-NG file if_tsresol options.

tsresol: ResolutionData = <BitField tsresol>

Interface timestamp resolution, as the option encodes it – the base flag and the exponent, from which resolution is computed.

padding: bytes = <PaddingField padding>

Padding.

post_process(packet)[source]

Revise schema data after unpacking process.

Parameters:

packet (dict[str, Any]) – Unpacked data.

Return type:

IF_TSResolOption

Returns:

Revised schema.

resolution: int

Interface timestamp resolution, in units per second.

class pcapkit.protocols.misc.pcapng.schema.IF_TZoneOption(type=NO_VALUE, length=NO_VALUE, tzone=NO_VALUE, padding=NO_VALUE, *, __packet__=None, **kwargs)[source]

Bases: _IF_Option

Header schema for PCAP-NG file if_tzone options.

tzone: int = <Int32Field tzone>

Interface time zone (as in seconds difference from GMT).

padding: bytes = <PaddingField padding>

Padding.

class pcapkit.protocols.misc.pcapng.schema.IF_FilterOption(type=NO_VALUE, length=NO_VALUE, code=NO_VALUE, filter=NO_VALUE, padding=NO_VALUE, *, __packet__=None, **kwargs)[source]

Bases: _IF_Option

Header schema for PCAP-NG file if_filter options.

code: FilterType = <EnumField code>

Filter code.

filter: bytes = <BytesField filter>

Capture filter.

padding: bytes = <PaddingField padding>

Padding.

class pcapkit.protocols.misc.pcapng.schema.IF_OSOption(type=NO_VALUE, length=NO_VALUE, os=NO_VALUE, padding=NO_VALUE, *, __packet__=None, **kwargs)[source]

Bases: _IF_Option

Header schema for PCAP-NG file if_os options.

os: str = <StringField os>

OS information.

padding: bytes = <PaddingField padding>

Padding.

class pcapkit.protocols.misc.pcapng.schema.IF_FCSLenOption(type=NO_VALUE, length=NO_VALUE, fcslen=NO_VALUE, padding=NO_VALUE, *, __packet__=None, **kwargs)[source]

Bases: _IF_Option

Header schema for PCAP-NG file if_fcslen options.

fcslen: int = <UInt8Field fcslen>

FCS length.

padding: bytes = <PaddingField padding>

Padding.

class pcapkit.protocols.misc.pcapng.schema.IF_TSOffsetOption(type=NO_VALUE, length=NO_VALUE, tsoffset=NO_VALUE, padding=NO_VALUE, *, __packet__=None, **kwargs)[source]

Bases: _IF_Option

Header schema for PCAP-NG file if_tsoffset options.

tsoffset: int = <Int64Field tsoffset>

Timestamp offset (in seconds).

padding: bytes = <PaddingField padding>

Padding.

class pcapkit.protocols.misc.pcapng.schema.IF_HardwareOption(type=NO_VALUE, length=NO_VALUE, hardware=NO_VALUE, padding=NO_VALUE, *, __packet__=None, **kwargs)[source]

Bases: _IF_Option

Header schema for PCAP-NG file if_hardware options.

hardware: str = <StringField hardware>

Hardware information.

padding: bytes = <PaddingField padding>

Padding.

class pcapkit.protocols.misc.pcapng.schema.IF_TxSpeedOption(type=NO_VALUE, length=NO_VALUE, tx_speed=NO_VALUE, padding=NO_VALUE, *, __packet__=None, **kwargs)[source]

Bases: _IF_Option

Header schema for PCAP-NG file if_txspeed options.

tx_speed: int = <UInt64Field tx_speed>

Interface transmit speed, in bits per second.

padding: bytes = <PaddingField padding>

Padding.

class pcapkit.protocols.misc.pcapng.schema.IF_RxSpeedOption(type=NO_VALUE, length=NO_VALUE, rx_speed=NO_VALUE, padding=NO_VALUE, *, __packet__=None, **kwargs)[source]

Bases: _IF_Option

Header schema for PCAP-NG file if_rxspeed options.

rx_speed: int = <UInt64Field rx_speed>

Interface receive speed, in bits per second.

padding: bytes = <PaddingField padding>

Padding.

class pcapkit.protocols.misc.pcapng.schema._EPB_Option(*args, **kwargs)[source]

Bases: Option

Header schema for epb_* options.

type: OptionType = <OptionEnumField type>

Option type.

length: int = <UInt16Field length>

Option data length.

class pcapkit.protocols.misc.pcapng.schema.EPB_FlagsOption(type=NO_VALUE, length=NO_VALUE, flags=NO_VALUE, padding=NO_VALUE, *, __packet__=None, **kwargs)[source]

Bases: _EPB_Option

Header schema for PCAP-NG epb_flags options.

flags: EPBFlags = <FlagsField flags>

Flags.

padding: bytes = <PaddingField padding>

Padding.

class pcapkit.protocols.misc.pcapng.schema.EPB_HashOption(type=NO_VALUE, length=NO_VALUE, func=NO_VALUE, data=NO_VALUE, padding=NO_VALUE, *, __packet__=None, **kwargs)[source]

Bases: _EPB_Option

Header schema for PCAP-NG epb_hash options.

func: HashAlgorithm = <EnumField func>

Hash algorithm.

data: bytes = <BytesField data>

Hash value.

padding: bytes = <PaddingField padding>

Padding.

class pcapkit.protocols.misc.pcapng.schema.EPB_DropCountOption(type=NO_VALUE, length=NO_VALUE, drop_count=NO_VALUE, padding=NO_VALUE, *, __packet__=None, **kwargs)[source]

Bases: _EPB_Option

Header schema for PCAP-NG epb_dropcount options.

drop_count: int = <UInt64Field drop_count>

Number of packets dropped by the interface.

padding: bytes = <PaddingField padding>

Padding.

class pcapkit.protocols.misc.pcapng.schema.EPB_PacketIDOption(type=NO_VALUE, length=NO_VALUE, packet_id=NO_VALUE, padding=NO_VALUE, *, __packet__=None, **kwargs)[source]

Bases: _EPB_Option

Header schema for PCAP-NG epb_packetid options.

packet_id: int = <UInt64Field packet_id>

Packet ID.

padding: bytes = <PaddingField padding>

Padding.

class pcapkit.protocols.misc.pcapng.schema.EPB_QueueOption(type=NO_VALUE, length=NO_VALUE, queue_id=NO_VALUE, padding=NO_VALUE, *, __packet__=None, **kwargs)[source]

Bases: _EPB_Option

Header schema for PCAP-NG epb_queue options.

queue_id: int = <UInt32Field queue_id>

Queue ID.

padding: bytes = <PaddingField padding>

Padding.

class pcapkit.protocols.misc.pcapng.schema.EPB_VerdictOption(type=NO_VALUE, length=NO_VALUE, verdict=NO_VALUE, value=NO_VALUE, padding=NO_VALUE, *, __packet__=None, **kwargs)[source]

Bases: _EPB_Option

Header schema for PCAP-NG epb_verdict options.

verdict: VerdictType = <EnumField verdict>

Verdict type.

value: bytes = <BytesField value>

Verdict value.

padding: bytes = <PaddingField padding>

Padding.

class pcapkit.protocols.misc.pcapng.schema._NS_Option(*args, **kwargs)[source]

Bases: Option

Header schema for ns_* options.

type: OptionType = <OptionEnumField type>

Option type.

length: int = <UInt16Field length>

Option data length.

class pcapkit.protocols.misc.pcapng.schema.NS_DNSNameOption(type=NO_VALUE, length=NO_VALUE, name=NO_VALUE, padding=NO_VALUE, *, __packet__=None, **kwargs)[source]

Bases: _NS_Option

Header schema for PCAP-NG ns_dnsname option.

name: str = <StringField name>

DNS name.

padding: bytes = <PaddingField padding>

Padding.

class pcapkit.protocols.misc.pcapng.schema.NS_DNSIP4AddrOption(type=NO_VALUE, length=NO_VALUE, ip=NO_VALUE, *, __packet__=None, **kwargs)[source]

Bases: _NS_Option

Header schema for PCAP-NG ns_dnsIP4addr option.

ip: IPv4Address = <IPv4AddressField ip>

IPv4 address.

class pcapkit.protocols.misc.pcapng.schema.NS_DNSIP6AddrOption(type=NO_VALUE, length=NO_VALUE, ip=NO_VALUE, *, __packet__=None, **kwargs)[source]

Bases: _NS_Option

Header schema for PCAP-NG ns_dnsIP6addr option.

ip: IPv6Address = <IPv6AddressField ip>

IPv6 address.

class pcapkit.protocols.misc.pcapng.schema._ISB_Option(*args, **kwargs)[source]

Bases: Option

Header schema for isb_* options.

type: OptionType = <OptionEnumField type>

Option type.

length: int = <UInt16Field length>

Option data length.

class pcapkit.protocols.misc.pcapng.schema.ISB_StartTimeOption(type=NO_VALUE, length=NO_VALUE, timestamp_high=NO_VALUE, timestamp_low=NO_VALUE, *, __packet__=None, **kwargs)[source]

Bases: _ISB_Option

Header schema for PCAP-NG isb_starttime option.

timestamp_high: int = <UInt32Field timestamp_high>

Timestamp (higher 32 bits).

timestamp_low: int = <UInt32Field timestamp_low>

Timestamp (lower 32 bits).

class pcapkit.protocols.misc.pcapng.schema.ISB_EndTimeOption(type=NO_VALUE, length=NO_VALUE, timestamp_high=NO_VALUE, timestamp_low=NO_VALUE, *, __packet__=None, **kwargs)[source]

Bases: _ISB_Option

Header schema for PCAP-NG isb_endtime option.

timestamp_high: int = <UInt32Field timestamp_high>

Timestamp (higher 32 bits).

timestamp_low: int = <UInt32Field timestamp_low>

Timestamp (lower 32 bits).

class pcapkit.protocols.misc.pcapng.schema.ISB_IFRecvOption(type=NO_VALUE, length=NO_VALUE, packets=NO_VALUE, *, __packet__=None, **kwargs)[source]

Bases: _ISB_Option

Header schema for PCAP-NG isb_ifrecv option.

packets: int = <UInt64Field packets>

Number of packets received.

class pcapkit.protocols.misc.pcapng.schema.ISB_IFDropOption(type=NO_VALUE, length=NO_VALUE, packets=NO_VALUE, *, __packet__=None, **kwargs)[source]

Bases: _ISB_Option

Header schema for PCAP-NG isb_ifdrop option.

packets: int = <UInt64Field packets>

Number of packets dropped.

class pcapkit.protocols.misc.pcapng.schema.ISB_FilterAcceptOption(type=NO_VALUE, length=NO_VALUE, packets=NO_VALUE, *, __packet__=None, **kwargs)[source]

Bases: _ISB_Option

Header schema for PCAP-NG isb_filteraccept option.

packets: int = <UInt64Field packets>

Number of packets accepted by filter.

class pcapkit.protocols.misc.pcapng.schema.ISB_OSDropOption(type=NO_VALUE, length=NO_VALUE, packets=NO_VALUE, *, __packet__=None, **kwargs)[source]

Bases: _ISB_Option

Header schema for PCAP-NG isb_osdrop option.

packets: int = <UInt64Field packets>

Number of packets dropped by OS.

class pcapkit.protocols.misc.pcapng.schema.ISB_UsrDelivOption(type=NO_VALUE, length=NO_VALUE, packets=NO_VALUE, *, __packet__=None, **kwargs)[source]

Bases: _ISB_Option

Header schema for PCAP-NG isb_usrdeliv option.

packets: int = <UInt64Field packets>

Number of packets delivered to user.

class pcapkit.protocols.misc.pcapng.schema._PACK_Option(*args, **kwargs)[source]

Bases: Option

Header schema for pack_* options.

type: OptionType = <OptionEnumField type>

Option type.

length: int = <UInt16Field length>

Option data length.

class pcapkit.protocols.misc.pcapng.schema.PACK_FlagsOption(type=NO_VALUE, length=NO_VALUE, flags=NO_VALUE, padding=NO_VALUE, *, __packet__=None, **kwargs)[source]

Bases: _PACK_Option

Header schema for PCAP-NG pack_flags options.

flags: PACKFlags = <FlagsField flags>

Flags.

padding: bytes = <PaddingField padding>

Padding.

class pcapkit.protocols.misc.pcapng.schema.PACK_HashOption(type=NO_VALUE, length=NO_VALUE, func=NO_VALUE, data=NO_VALUE, padding=NO_VALUE, *, __packet__=None, **kwargs)[source]

Bases: _PACK_Option

Header schema for PCAP-NG pack_hash options.

func: HashAlgorithm = <EnumField func>

Hash algorithm.

data: bytes = <BytesField data>

Hash value.

padding: bytes = <PaddingField padding>

Padding.

class pcapkit.protocols.misc.pcapng.schema.NameResolutionRecord(*args, **kwargs)[source]

Bases: EnumSchema[RecordType]

Header schema for PCAP-NG NRB records.

type: RecordType = <EnumField type>

Record type.

length: int = <UInt16Field length>

Record value length.

class pcapkit.protocols.misc.pcapng.schema.UnknownRecord(type=NO_VALUE, length=NO_VALUE, data=NO_VALUE, padding=NO_VALUE, *, __packet__=None, **kwargs)[source]

Bases: NameResolutionRecord

Header schema for PCAP-NG NRB unknown records.

data: bytes = <BytesField data>

Unknown record data.

padding: bytes = <PaddingField padding>

Padding.

class pcapkit.protocols.misc.pcapng.schema.EndRecord(type=NO_VALUE, length=NO_VALUE, *, __packet__=None, **kwargs)[source]

Bases: NameResolutionRecord

Header schema for PCAP-NG nrb_record_end records.

class pcapkit.protocols.misc.pcapng.schema.IPv4Record(type=NO_VALUE, length=NO_VALUE, ip=NO_VALUE, resol=NO_VALUE, padding=NO_VALUE, *, __packet__=None, **kwargs)[source]

Bases: NameResolutionRecord

Header schema for PCAP-NG NRB nrb_record_ipv4 records.

ip: IPv4Address = <IPv4AddressField ip>

IPv4 address.

resol: str = <StringField resol>

Name resolution data.

padding: bytes = <PaddingField padding>

Padding.

post_process(packet)[source]

Revise schema data after unpacking process.

Parameters:

packet (dict[str, Any]) – Unpacked data.

Return type:

Schema

Returns:

Revised schema.

names: list[str]

Name resolution records.

class pcapkit.protocols.misc.pcapng.schema.IPv6Record(type=NO_VALUE, length=NO_VALUE, ip=NO_VALUE, resol=NO_VALUE, padding=NO_VALUE, *, __packet__=None, **kwargs)[source]

Bases: NameResolutionRecord

Header schema for PCAP-NG NRB nrb_record_ipv6 records.

ip: IPv6Address = <IPv6AddressField ip>

IPv6 address.

resol: str = <StringField resol>

Name resolution data.

padding: bytes = <PaddingField padding>

Padding.

post_process(packet)[source]

Revise schema data after unpacking process.

Parameters:

packet (dict[str, Any]) – Unpacked data.

Return type:

Schema

Returns:

Revised schema.

names: list[str]

Name resolution records.

class pcapkit.protocols.misc.pcapng.schema.DSBSecrets(*args, **kwargs)[source]

Bases: EnumSchema[SecretsType]

Header schema for DSB secrets data.

class pcapkit.protocols.misc.pcapng.schema.UnknownSecrets(data=NO_VALUE, *, __packet__=None, **kwargs)[source]

Bases: DSBSecrets

Header schema for unknown DSB secrets data.

data: bytes = <BytesField data>

Secrets data.

class pcapkit.protocols.misc.pcapng.schema.TLSKeyLog(data=NO_VALUE, *, __packet__=None, **kwargs)[source]

Bases: DSBSecrets

Header schema for TLS Key Log secrets data.

data: str = <StringField data>

TLS key log data.

post_process(packet)[source]

Revise schema data after unpacking process.

Parameters:

packet (dict[str, Any]) – Unpacked data.

Return type:

Schema

Returns:

Revised schema.

A line that does not parse – an unknown label, a field that is not hexadecimal, a wrong number of fields, or the first octets of an entry cut inside the block’s padding – is left out of entries and reported as a ProtocolWarning that names its label and elides its values (see _malformed_line_message()), wherever it sits in the log (#1985). Refusing it would abort the whole extraction rather than this one line, as nonnegative() explains, and data keeps the log text verbatim, so the line is still kept as captured and the block rebuilds octet for octet. A last line the capture or the block cut is left out silently (see _cut_last_line()), since the cut is reported already.

entries: dict[TLSKeyLabel, OrderedMultiDict[bytes, bytes]]

TLS Key Log entries.

class pcapkit.protocols.misc.pcapng.schema.WireGuardKeyLog(data=NO_VALUE, *, __packet__=None, **kwargs)[source]

Bases: DSBSecrets

Header schema for WireGuard Key Log secrets data.

data: str = <StringField data>

WireGuard key log data.

post_process(packet)[source]

Revise schema data after unpacking process.

Parameters:

packet (dict[str, Any]) – Unpacked data.

Return type:

Schema

Returns:

Revised schema.

A line that does not parse is left out of entries, reported and kept as captured in data, as TLSKeyLog.post_process() describes (#1985).

entries: OrderedMultiDict[WireGuardKeyLabel, bytes]

WireGuard Key Log entries.

class pcapkit.protocols.misc.pcapng.schema.ZigBeeNWKKey(key=NO_VALUE, panid=NO_VALUE, trailing=NO_VALUE, *, __packet__=None, **kwargs)[source]

Bases: DSBSecrets

Header schema for ZigBee NWK Key and ZigBee PANID secrets data.

key: bytes = <BytesField key>

AES-128 NWK key.

panid: int = <UInt16Field panid>

ZigBee PANID.

trailing: bytes | None = <ConditionalField trailing>

Octets past the PAN ID, if Secrets Length declares any (see zigbee_key_trailing()).

class pcapkit.protocols.misc.pcapng.schema.ZigBeeAPSKey(key=NO_VALUE, panid=NO_VALUE, addr_low=NO_VALUE, addr_high=NO_VALUE, trailing=NO_VALUE, *, __packet__=None, **kwargs)[source]

Bases: DSBSecrets

Header schema for ZigBee APS Key secrets data.

key: bytes = <BytesField key>

AES-128 APS key.

panid: int = <UInt16Field panid>

ZigBee PANID.

addr_low: int = <UInt16Field addr_low>

Low node short address.

addr_high: int = <UInt16Field addr_high>

High node short address.

trailing: bytes | None = <ConditionalField trailing>

Octets past the high node short address, if Secrets Length declares any (see zigbee_key_trailing()).

class pcapkit.protocols.misc.pcapng.schema.FlagsField(namespace, callback=lambda *_: ...)[source]

Bases: UInt32Field

32-bit flags word for protocol fields, with sub-fields numbered from the least-significant bit, as the epb_flags and pack_flags options number them.

Unlike BitField, which numbers bits from the most-significant bit of the raw octets and ignores byte order, the word is read as an integer in the section’s byte order first.

Parameters:
pre_process(value, packet)[source]

Process field value before construction (packing).

Parameters:
Return type:

int | bytes

Returns:

Processed field value.

Raises:

FieldValueError – If a sub-field value does not fit its bits.

post_process(value, packet)[source]

Process field value after parsing (unpacked).

Parameters:
Return type:

dict[str, int]

Returns:

Processed field value.

class pcapkit.protocols.misc.pcapng.schema.OptionEnumField(length, default=OptionType.opt_endofopt, signed=False, byteorder='big', bit_length=None, namespace='opt', callback=lambda *_: ...)[source]

Bases: EnumField

Enumerated value for protocol fields.

Parameters:

  • length (int | Callable[[dict[str, Any]], int]) – Field size (in bytes); if a callable is given, it should return an integer value and accept the current packet as its only argument.

  • default (OptionType) – Field default value, if any.

  • signed (bool) – Whether the field is signed.

  • byteorder (Literal['little', 'big']) – Field byte order.

  • bit_length (int | None) – Field bit length.

  • namespace (str) – Option namespace, i.e., namespace of the enum item.

  • callback (Callable[[Self, dict[str, Any]], None]) – Callback function to be called upon self.__call__.

Important

This class is specifically designed for OptionType as it is actually an aenum.StrEnum class.

pre_process(value, packet)[source]

Process field value before construction (packing).

Parameters:
Return type:

int | bytes

Returns:

Processed field value.

post_process(value, packet)[source]

Process field value after parsing (unpacked).

Parameters:
Return type:

OptionType

Returns:

Processed field value – the registry member declared for the option code in this namespace (or in the shared opt namespace), or an unregistered member of the same registry, carrying the code itself, when neither declares one.

Notes

This replicates the read-only membership test get() itself runs first, and calls it only once that test finds the code declared. An undeclared option type gets EnumField._unregistered_member instead of get()’s own miss path, for pickle-safety: that method carries its own __reduce_ex__, so a member built this way round-trips through pickle – see its own docstring – which the override of _unregistered_member(), the miss path, does not. The override’s _value_ is the formatted display string ('opt_unknown [8888]', not 8888), so pickle.dumps on one succeeds but pickle.loads of the result raises ValueError: the default reduction reconstructs through cls(self._value_), and _missing_’s own int-only guard rejects that formatted string outright.

The base _unregistered_member() that override replaces fails earlier, on repr() itself, since opt_name/ opt_value are never set – which is why the override exists, choosing to render correctly over round-tripping correctly. EnumField._unregistered_member is the only one of these that gets both right. copy.deepcopy() is not the difference: it succeeds on both kinds, since the standard library’s enum.Enum (which aenum.Enum subclasses) defines __copy__/__deepcopy__ to return self outright, so deep-copying any member never reaches __reduce_ex__.

class pcapkit.protocols.misc.pcapng.schema.OptionAreaField(length=lambda _: ..., base_schema=None, type_name='type', registry=None, eool=None, callback=lambda *_: ...)[source]

Bases: OptionField

Option list that keeps a malformed option area as the octets captured.

An option in the area that runs past it, or past the data, raises ProtocolError from OptionField.unpack or bounded_option(). A block has no catch point above its fields, so raising would abort the whole extraction. This field instead returns the area as a single bytes item, which packs back verbatim, and reports no padding after it (#1325).

unpack(buffer, packet)[source]

Unpack field value from bytes.

Parameters:
Return type:

list[Any]

Returns:

Unpacked field value, or the whole area as one bytes item if an option in it is malformed.

_accepts_cut(option)[source]

Whether an option the data ends inside, inside its area, may stand.

Parameters:

option (Schema) – Option just unpacked, which read short.

Returns:

a block keeps an area the data ends inside as the octets captured, as it keeps one an option runs past (#1325), rather than read its missing octets as zeros.

Return type:

bool

Type Stubs

class pcapkit.protocols.misc.pcapng.schema.ByteorderTest[source]

Bases: TypedDict

Test for byte order.

byteorder: int

Byte-order magic number.

class pcapkit.protocols.misc.pcapng.schema.ResolutionData[source]

Bases: TypedDict

Data for resolution.

flag: int

Resolution type flag (0 for 10-based, 1 for 2-based).

resolution: int

Resolution value.

class pcapkit.protocols.misc.pcapng.schema.EPBFlags[source]

Bases: TypedDict

EPB flags.

direction: int

Inbound / Outbound packet (00 = information not available, 01 = inbound, 10 = outbound)

reception: int

Reception type (000 = not specified, 001 = unicast, 010 = multicast, 011 = broadcast, 100 = promiscuous).

fcs_len: int

FCS length, in octets (0000 if this information is not available). This value overrides the if_fcslen option of the Interface Description Block, and is used with those link layers (e.g. PPP) where the length of the FCS can change during time.

checksum_not_ready: int

Checksum not ready (bit 9).

checksum_valid: int

Checksum valid (bit 10).

tcp_segmentation_offloaded: int

TCP segmentation offloaded (bit 11).

reserved: int

Bits 12 to 23, kept verbatim (reserved bits and unnamed link-layer-dependent errors).

crc_error: int

Link-layer-dependent error - CRC error (bit 24).

too_long: int

Link-layer-dependent error - packet too long error (bit 25).

too_short: int

Link-layer-dependent error - packet too short error (bit 26).

gap_error: int

Link-layer-dependent error - wrong Inter Frame Gap error (bit 27).

unaligned_error: int

Link-layer-dependent error - unaligned frame error (bit 28).

delimiter_error: int

Link-layer-dependent error - Start Frame Delimiter error (bit 29).

preamble_error: int

Link-layer-dependent error - preamble error (bit 30).

symbol_error: int

Link-layer-dependent error - symbol error (bit 31).

class pcapkit.protocols.misc.pcapng.schema.PACKFlags[source]

Bases: TypedDict

PACK flags.

direction: int

Inbound / Outbound packet (00 = information not available, 01 = inbound, 10 = outbound)

reception: int

Reception type (000 = not specified, 001 = unicast, 010 = multicast, 011 = broadcast, 100 = promiscuous).

fcs_len: int

FCS length, in octets (0000 if this information is not available). This value overrides the if_fcslen option of the Interface Description Block, and is used with those link layers (e.g. PPP) where the length of the FCS can change during time.

checksum_not_ready: int

Checksum not ready (bit 9).

checksum_valid: int

Checksum valid (bit 10).

tcp_segmentation_offloaded: int

TCP segmentation offloaded (bit 11).

reserved: int

Bits 12 to 23, kept verbatim (reserved bits and unnamed link-layer-dependent errors).

crc_error: int

Link-layer-dependent error - CRC error (bit 24).

too_long: int

Link-layer-dependent error - packet too long error (bit 25).

too_short: int

Link-layer-dependent error - packet too short error (bit 26).

gap_error: int

Link-layer-dependent error - wrong Inter Frame Gap error (bit 27).

unaligned_error: int

Link-layer-dependent error - unaligned frame error (bit 28).

delimiter_error: int

Link-layer-dependent error - Start Frame Delimiter error (bit 29).

preamble_error: int

Link-layer-dependent error - preamble error (bit 30).

symbol_error: int

Link-layer-dependent error - symbol error (bit 31).

Auxiliary Functions

The byte order of every block but the Section Header Block is read by byteorder_callback(), which is shared with the PCAP frame header and documented in pcapkit.corekit.schema.byteorder.

pcapkit.protocols.misc.pcapng.schema.shb_byteorder_callback(field, packet)[source]

Update byte order of PCAP-NG file for SHB.

A Section Header Block declares the byte order of its own section through its Byte-Order Magic, so it cannot take one from the enclosing packet data: the first SHB of a file has no section context by construction, and a later one would otherwise inherit the previous section’s byte order. The magic is therefore also written back as packet['byteorder'], which is what the SHB’s own options – read by byteorder_callback(), after this field – resolve their byte order from.

A Section Header Block of 12 octets has no room for the magic, and its place holds the trailing Block Total Length instead. That length is 12 in exactly one byte order, which is the one taken; SectionHeaderBlock.post_process() then rejects any block that matched this way with a length other than 12 (#1422).

Parameters:
pcapkit.protocols.misc.pcapng.schema.pcapng_block_selector(packet)[source]

Selector function for PCAPNG.block field.

Parameters:

packet (dict[str, Any]) – Packet data.

Return type:

FieldBase

Returns:

A SchemaField wrapped BlockType subclass instance.

See also

Note

__length__ is what is left of the stream, not what the block declares, and it is decremented by four for PCAPNG.type whether or not those four octets were there to read – FieldBase.unpack zero-pads a short read rather than refusing it. A tail of one, two or three octets therefore arrives here negative, which SchemaField.unpack would read as no declared length, sizing the block by whatever is left of the stream. The floor is a backstop: PCAPNG._check_block_floor reports that tail as end-of-stream before it gets here, and on the packing path Schema.pack seeds __length__ as -1 for “unknown”, which SchemaField.pack does not read at all.

pcapkit.protocols.misc.pcapng.schema.dsb_secrets_selector(packet)[source]

Selector function for DecryptionSecretsBlock.secrets_data field.

Parameters:

packet (dict[str, Any]) – Packet data.

Return type:

FieldBase

Returns:

A SchemaField wrapped instance of the DSBSecrets subclass registered for secrets_type, or of UnknownSecrets if none is, spanning the octets of secrets_length that the block holds (see secrets_area()).

See also

pcapkit.protocols.misc.pcapng.schema.nonnegative(length)[source]

Floor a computed field length at zero.

Parameters:

length (Callable[[dict[str, Any]], int]) – Callback computing a field’s length from the framing a block, option or record declares.

Return type:

Callable[[dict[str, Any]], int]

Returns:

A callback returning that length, never below zero.

Every span in this module is a subtraction – a block’s own Block Total Length less its fixed fields, an option’s declared length less the part of itself it describes, an option area’s leftover – and every operand of those subtractions is a wire field that a malformed or truncated capture is free to set to anything. Nothing else makes the difference non-negative, and the field layer does not either: _TextField.__call__ builds its struct template as f'{length}s' unconditionally, so a negative length becomes the format '-8s' and struct.calcsize() raises a bare struct.error. That is not one of pcapkit.utilities.exceptions, so a caller cannot tell it from a bug in its own code, and it is not an EOFError, so the frame loop does not catch it – one malformed block would therefore cost the whole extraction. A negative SchemaField length fails silently instead: SchemaField.unpack reads it as no declared length, and sizes the nested schema by whatever is left of the stream.

Two shapes reach here. A Block Total Length below the block’s own fixed-field floor – 28 octets for a Section Header Block, 20 for an Interface Description Block, 16 for a Custom Block – makes the area negative directly. And __option_padding__, which OptionField.unpack reports as the part of a declared area its options did not consume, goes negative when they consumed more than the area held: it subtracts each parsed option’s real size from the area without checking that it fits. Both mean the same thing for a read – there are no octets here – and zero says that, where a negative says something struct cannot express.

Flooring rather than refusing is the choice bounded_area() makes too: a block read has no catch point above FieldBase.unpack, so one refusal aborts the whole extraction rather than one block, and a capture cut short by its snapshot length must keep parsing. The end of the file is the one case that is not a floor, since there no block is being read at all – see PCAPNG._check_block_floor, which reports it as the StreamEOFError the frame loop catches.

Note

Unlike bounded_option() this needs no __length__ opt-out for the packing path, because it floors a difference rather than checking against the remaining area: a negative difference is not a legitimate thing to pack either – struct.pack('-8s', ...) raises exactly as calcsize does – where checking against the remainder would have refused a perfectly good option.

That distinction is what keeps the decryption-secrets payloads – UnknownSecrets.data, TLSKeyLog.data and WireGuardKeyLog.data – out of this. They read __length__ whole rather than subtracting from it, and Schema.pack leaves it at -1 for “unknown”, so flooring them packs nothing at all. On the parsing path their __length__ is the length the enclosing SchemaField declared from a 32-bit secrets_length, which cannot be negative, so there is nothing there to floor.

pcapkit.protocols.misc.pcapng.schema.held_body(framing)[source]

Bound a block body read as one field to the octets the stream holds.

Parameters:

framing (int) – Octets the block’s fixed fields span, both copies of the Block Total Length included.

Return type:

Callable[[dict[str, Any]], int]

Returns:

A callback returning the block’s Block Total Length less framing, never below zero, and never past what is left of the stream.

The bodies of UnknownBlock, CustomBlock and SystemdJournalExportBlock are each one BytesField spanning the whole block, so a Block Total Length that runs past the end of the file is one field declaring that many octets. Unbounded, that field is zero-filled within MAX_ZERO_PAD_LENGTH, and past it FieldBase.unpack raises FieldValueError from inside the block’s schema, where PCAPNG.read cannot keep the block as captured, so the whole extraction ends (#1984). The other block types read their bodies field by field, so none of them declares that much in one field.

Bounded, the body is the octets the file actually holds, whatever the block declares, and PCAPNG.read reports the truncation as it does for every other block type. On a well-formed block the stream holds the body and the trailing Block Total Length, so this is a no-op; on the packing path Schema.pack leaves __length__ at -1 for “unknown”, and the declared span is kept.

pcapkit.protocols.misc.pcapng.schema.bounded_option(length)[source]

Refuse an option or record payload that runs past its area.

Parameters:

length (Callable[[dict[str, Any]], int]) – Callback computing the payload’s nominal length, as the option’s or record’s own declared length field gives it.

Return type:

Callable[[dict[str, Any]], int]

Returns:

A callback returning that length.

Raises:

ProtocolError – If the payload declares more octets than the enclosing option or record area has left.

An option’s length is a 16-bit wire field, so one four-octet option header can declare 65,535 octets of payload. Read as declared, every shortfall would be zero-padded at the field layer, and the zeros rebuilt as if they had been captured (#594, #1325). So a payload that runs past the area is refused here instead. Inside a block, OptionAreaField then keeps the whole option area as the octets captured, so the block still parses and rebuilds byte for byte.

Note

The check is skipped when __length__ is absent or negative, which is what Schema.pack leaves it as when no length is known. The nominal length still goes through nonnegative() first, on both paths, since an option declaring less payload than the part of itself it describes makes the subtraction negative.

pcapkit.protocols.misc.pcapng.schema.bounded_area(length)[source]

Clamp a packet block’s option area to the octets the block itself holds.

Parameters:

length (Callable[[dict[str, Any]], int]) – Callback computing the option area’s nominal span, from the block’s own declared Block Total Length.

Return type:

Callable[[dict[str, Any]], int]

Returns:

A callback returning that span, never past the octets left of the block.

bounded_option() refuses a payload that runs past the area, and the area is sized from the block’s declared Block Total Length. Nothing checks that length against the file: BlockType.post_process compares length only against its own trailing copy. A block declaring 1,000,000 octets while holding 36 would therefore size its option area at 999,964, read the trailing Block Total Length into it, and leave that field to be zero-filled. Clamping the area to __length__ keeps the trailing length out of the area, so the area holds exactly the octets the block was handed for it, whatever it declared.

This is a no-op on every well-formed block rather than a second guess at the area. At the option field the only field still to come is the trailing Block Total Length, so __length__ is exactly the area plus that field’s four octets, and subtracting them makes the two equal. Taking __length__ whole over-grants by exactly four, which is not academic: the area then reaches the trailing length itself and reads it as option payload, measured as four octets of payload on a block that holds none.

Note

The non-packet blocks’ option areas – Section Header, Interface Description, Name Resolution, Interface Statistics and Decryption Secrets – are deliberately left unclamped against the block here, since each computes its span with a different offset and the equality above has to be re-established per block rather than assumed. They do go through nonnegative(), which stops a negative declared length reaching a read at all; the per-block equality is not enforced for them.

The nominal span goes through nonnegative() first here too. That closes a hole in this function’s own arithmetic: a captured_len past the end of the block makes the span negative, and nominal <= available below is then true, so the negative would be returned unclamped and reach a struct template as f'{-N}s'. Measured on 200 Enhanced Packet Blocks declaring captured_len 0xFFFFFF in 8,048 octets.

pcapkit.protocols.misc.pcapng.schema.captured_area(name)[source]

Bound a packet block’s Packet Data to the octets the block holds.

Parameters:

name (str) – Name of the block’s captured length field, captured_len or captured_length.

Return type:

Callable[[dict[str, Any]], int]

Returns:

A callback returning the captured length, never past the block’s Block Total Length less its 32 framing octets, and never below zero.

A captured length running past the block would otherwise read the trailing Block Total Length, and whatever follows the block, as packet data, so the rebuild could not be byte-exact. Bounded, the block keeps its declared captured length and exactly the octets it holds, and the padding and option area are sized from those octets rather than from the declared length (#1405).

pcapkit.protocols.misc.pcapng.schema.secrets_area(packet)[source]

Bound a Decryption Secrets Block’s Secrets Data to the octets the block holds.

Parameters:

packet (dict[str, Any]) – Unpacked data so far, with length and secrets_length.

Return type:

int

Returns:

The declared secrets_length, never past the block’s Block Total Length less its 20 framing octets, and never below zero.

secrets_length is a 32-bit wire field. Read as declared, a length past the block would read the trailing Block Total Length and the blocks after it as secrets, and past MAX_ZERO_PAD_LENGTH the read would raise FieldValueError from inside the block’s schema, ending the whole extraction (#1980). This is the Secrets Data counterpart of captured_area(): the block keeps its declared secrets_length, the secrets are the octets the block holds, and the padding and option area are sized from those octets. DecryptionSecretsBlock.post_process() reports the overrun.

pcapkit.protocols.misc.pcapng.schema.zigbee_key_has_trailing(packet)[source]

Tell whether a ZigBee key schema carries octets past its fixed fields.

Parameters:

packet (dict[str, Any]) – Unpacked data so far, or the data being packed.

Return type:

bool

Returns:

On unpacking, whether any of the span the block gives the key is left once its fixed fields are read; on packing, whether the schema holds such octets.

pcapkit.protocols.misc.pcapng.schema.zigbee_key_trailing(packet)[source]

Size the octets a ZigBee key schema carries past its fixed fields.

Parameters:

packet (dict[str, Any]) – Unpacked data so far, or the data being packed.

Return type:

int

Returns:

On unpacking, what is left of the span the block gives the key; on packing, the octets the schema holds.

The ZigBee NWK and APS keys have a fixed width, but a block’s Secrets Length may declare more. The octets past the fixed fields are kept here, rather than dropped, so that the key rebuilds as captured (#1986).

pcapkit.protocols.misc.pcapng.schema.zigbee_key_held(schema, data)[source]

Rebuild a ZigBee key schema from the Secrets Data octets its block held.

Parameters:
Return type:

_ZigBeeKey

Returns:

A schema instance that holds, and packs back to, exactly data.

data is unpacked as the block’s Secrets Data is, with any octets past the fixed fields kept as the schema’s trailing octets. A data short of the fixed width is a short read, which Schema.unpack records for Schema._cut_short_read. A key shorter than its fixed width, or a Secrets Length longer than it, then rebuilds byte for byte (#1986). The length is declared, so an empty data is an empty key rather than the end of the stream. The short read’s warnings are dropped, since the parse that held data reported them.

Changed in version 1.6.0: The schema’s buffers hold data as given, rather than zero-filled to the fixed width, so its bytes() and len() are those of data and a block sized from it is written as captured (#2688).

pcapkit.protocols.misc.pcapng.schema._spb_data_length(packet)[source]

Length of a Simple Packet Block’s packet data.

Parameters:

packet (dict[str, Any]) – Unpacked data so far, with length, original_len and, when interface 0 sets one, snaplen.

Return type:

int

Returns:

min(original_len, snaplen), bounded by the octets the block holds less its 16 framing octets. A block that holds more than that length and its padding – past the snaplen (#1384) or past original_len (#1414) – keeps the excess as packet data instead, so no octet is dropped and the trailing Block Total Length is read where it sits.

pcapkit.protocols.misc.pcapng.schema._cut_last_line(schema, index, lines, packet=None)[source]

Tell whether a key log line that did not parse is one the capture cut.

Parameters:

  • schema (Schema) – Key log secrets schema, just unpacked.

  • index (int) – Index of the line in lines.

  • lines (list[str]) – Lines of the key log.

  • packet (dict[str, Any] | None) – Unpacked data of schema, if any.

Return type:

bool

Returns:

Whether lines[index] is the last line of a key log the data ended inside, which Schema.unpack records as __short_read__, or that the enclosing block ended inside, as secrets_area() bounds it (#1980). Such a line is only the first octets of an entry, and the log text, kept verbatim, still rebuilds it (#1470).

pcapkit.protocols.misc.pcapng.schema._malformed_line_message(kind, labels, line)[source]

Report a key log line that does not parse, without quoting what it holds.

Parameters:

  • kind (str) – Name of the key log, e.g. 'TLS'.

  • labels (Callable[[str], Any]) – Enumeration of the key log’s labels, called on the upper-cased first field of the line.

  • line (str) – The line that does not parse.

Return type:

str

Returns:

A warning message naming the line’s label, when that is one labels knows, and eliding its values. The line itself is never quoted, since it carries key material (#1985); nor is an unrecognised label, which may be key material too.

Data Models

Removed in version 1.6.0: pcapkit.protocols.data.misc.pcapng, with no alias: the module moved here (#2534).

class pcapkit.protocols.misc.pcapng.data.PCAPNG(*args, **kwargs)[source]

Bases: Protocol

Data model for PCAP-NG file blocks.

type: BlockType

Block type.

length: int

Block total length.

class pcapkit.protocols.misc.pcapng.data.UnknownBlock(type, length, body)[source]

Bases: PCAPNG

Data model for unknown PCAP-NG file blocks.

body: bytes

Block body.

class pcapkit.protocols.misc.pcapng.data.SectionHeaderBlock(type, length, byteorder, version, section_length, options)[source]

Bases: PCAPNG

Data model for PCAP-NG Section Header Block (SHB).

byteorder: Literal['big', 'little']

Byte order.

version: VersionInfo

Version number.

section_length: int

Section length.

options: OrderedMultiInfo[OptionType, Option]

Options.

padding_opts: bytes

Octets after opt_endofopt, as captured; present only when the option area holds any (#1437).

class pcapkit.protocols.misc.pcapng.data.InterfaceDescriptionBlock(type, length, linktype, snaplen, options)[source]

Bases: PCAPNG

Data model for PCAP-NG Interface Description Block (IDB).

linktype: LinkType

Link type.

snaplen: int

Snap length.

options: OrderedMultiInfo[OptionType, Option]

Options.

reserved: bytes

Reserved octets, as captured; present only when they are not all zeros (#1437).

padding_opts: bytes

Octets after opt_endofopt, as captured; present only when the option area holds any (#1437).

class pcapkit.protocols.misc.pcapng.data.EnhancedPacketBlock(type, length, section_number, number, interface_id, timestamp, timestamp_epoch, captured_len, original_len, options)[source]

Bases: PCAPNG

Data model for PCAP-NG Enhanced Packet Block (EPB).

section_number: int

Section index.

number: int

Frame index.

interface_id: int

Interface ID.

timestamp: datetime

Timestamp.

timestamp_epoch: Decimal

Timestamp as in UNIX epoch (in seconds).

captured_len: int

Captured packet length.

original_len: int

Original packet length.

options: OrderedMultiInfo[OptionType, Option]

Options.

padding_data: bytes

Padding of the packet data to 32 bits, as captured; present only when it is not all zeros (#1437).

padding_opts: bytes

Octets after opt_endofopt, as captured; present only when the option area holds any (#1437).

protocols: str

Protocol chain.

class pcapkit.protocols.misc.pcapng.data.SimplePacketBlock(type, length, section_number, number, original_len, captured_len)[source]

Bases: PCAPNG

Data model for PCAP-NG Simple Packet Block (SPB).

section_number: int

Section index.

number: int

Frame index.

original_len: int

Original packet length.

captured_len: int

Captured packet length.

__post_init__()[source]

Post-initialization handling.

padding_data: bytes

Padding of the packet data to 32 bits, as captured; present only when it is not all zeros (#1437).

protocols: str

Protocol chain.

interface_id: int

Interface ID, always 0, since the block refers to the section’s first interface.

timestamp: datetime

Timestamp, always the UNIX epoch, as the block carries none.

timestamp_epoch: Decimal

Timestamp as in UNIX epoch (in seconds), always 0.

class pcapkit.protocols.misc.pcapng.data.NameResolutionBlock(type, length, records, options)[source]

Bases: PCAPNG

Data model for PCAP-NG Name Resolution Block (NRB).

records: OrderedMultiInfo[RecordType, NameResolutionRecord]

Records.

options: OrderedMultiInfo[OptionType, Option]

Options.

__post_init__()[source]

Post-initialization handling.

padding_opts: bytes

Octets after opt_endofopt, as captured; present only when the option area holds any (#1437).

mapping: MultiInfo[IPv4Address | IPv6Address, str]

Name resolution mapping (IP address -> name).

reverse_mapping: MultiInfo[str, IPv4Address | IPv6Address]

Name resolution mapping (name -> IP address).

class pcapkit.protocols.misc.pcapng.data.InterfaceStatisticsBlock(type, length, interface_id, timestamp, timestamp_epoch, options)[source]

Bases: PCAPNG

Data model for PCAP-NG Interface Statistics Block (ISB).

interface_id: int

Interface ID.

timestamp: datetime

Timestamp.

timestamp_epoch: Decimal

Timestamp as in UNIX epoch (in seconds).

options: OrderedMultiInfo[OptionType, Option]

Options.

padding_opts: bytes

Octets after opt_endofopt, as captured; present only when the option area holds any (#1437).

class pcapkit.protocols.misc.pcapng.data.SystemdJournalExportBlock(type, length, data)[source]

Bases: PCAPNG

Data model for PCAP-NG systemd(1) Journal Export Block.

data: tuple[OrderedMultiInfo[str, str | bytes], ...]

Journal entries; empty for a malformed block, whose entry is then kept as captured under entry_raw (#1406).

entry_raw: bytes

Malformed entry kept as captured, present only for such a block.

class pcapkit.protocols.misc.pcapng.data.DecryptionSecretsBlock(type, length, secrets_type, secrets_length, secrets_data, options)[source]

Bases: PCAPNG

Data model for PCAP-NG Decryption Secrets Block (DSB).

secrets_type: SecretsType

Secrets type.

secrets_length: int

Secrets length.

secrets_data: DSBSecrets

Secrets data.

options: OrderedMultiInfo[OptionType, Option]

Options.

padding_data: bytes

Padding of the secrets data to 32 bits, as captured; present only when it is not all zeros (#1437).

padding_opts: bytes

Octets after opt_endofopt, as captured; present only when the option area holds any (#1437).

class pcapkit.protocols.misc.pcapng.data.CustomBlock(type, length, pen, data)[source]

Bases: PCAPNG

Data model for PCAP-NG Custom Block (CB).

pen: int

Private enterprise number.

data: bytes

Custom block data (incl. data, options and padding).

class pcapkit.protocols.misc.pcapng.data.PacketBlock(type, length, section_number, number, interface_id, drop_count, timestamp, timestamp_epoch, captured_len, original_len, options)[source]

Bases: PCAPNG

Data model for PCAP-NG Packet Block (obsolete).

section_number: int

Section index.

number: int

Frame index.

interface_id: int

Interface ID.

drop_count: int

Drops count.

timestamp: datetime

Timestamp.

timestamp_epoch: Decimal

Timestamp as in UNIX epoch (in seconds).

captured_len: int

Captured packet length.

original_len: int

Original packet length.

options: OrderedMultiInfo[OptionType, Option]

Options.

padding_data: bytes

Padding of the packet data to 32 bits, as captured; present only when it is not all zeros (#1437).

padding_opts: bytes

Octets after opt_endofopt, as captured; present only when the option area holds any (#1437).

protocols: str

Protocol chain.

class pcapkit.protocols.misc.pcapng.data.Option(*args, **kwargs)[source]

Bases: Data

Data model for PCAP-NG file options.

type: OptionType

Option type.

length: int

Option data length.

padding: bytes

Padding of the option value to 32 bits, as captured; present only when it is not all zeros (#1437).

class pcapkit.protocols.misc.pcapng.data.UnknownOption(type, length, data)[source]

Bases: Option

Data model for unknown PCAP-NG file options.

data: bytes

Option data.

class pcapkit.protocols.misc.pcapng.data.EndOfOption(type, length)[source]

Bases: Option

Data model for PCAP-NG file opt_endofopt options.

class pcapkit.protocols.misc.pcapng.data.CommentOption(type, length, comment)[source]

Bases: Option

Data model for PCAP-NG file opt_comment options.

comment: str

Comment text.

class pcapkit.protocols.misc.pcapng.data.CustomOption(type, length, pen, data)[source]

Bases: Option

Data model for PCAP-NG file opt_custom options.

pen: int

Private enterprise number (PEN).

data: bytes

Custom data.

class pcapkit.protocols.misc.pcapng.data.IF_NameOption(type, length, name)[source]

Bases: Option

Data model for PCAP-NG file if_name options.

name: str

Interface name.

class pcapkit.protocols.misc.pcapng.data.IF_DescriptionOption(type, length, description)[source]

Bases: Option

Data model for PCAP-NG file if_description options.

description: str

Interface description.

class pcapkit.protocols.misc.pcapng.data.IF_IPv4AddrOption(type, length, interface)[source]

Bases: Option

Data model for PCAP-NG file if_IPv4addr options.

interface: IPv4Interface

IPv4 interface.

class pcapkit.protocols.misc.pcapng.data.IF_IPv6AddrOption(type, length, interface)[source]

Bases: Option

Data model for PCAP-NG file if_IPv6addr options.

interface: IPv6Interface

IPv6 interface.

class pcapkit.protocols.misc.pcapng.data.IF_MACAddrOption(type, length, interface)[source]

Bases: Option

Data model for PCAP-NG file if_MACaddr options.

interface: str

MAC address.

class pcapkit.protocols.misc.pcapng.data.IF_EUIAddrOption(type, length, interface)[source]

Bases: Option

Data model for PCAP-NG file if_EUIaddr options.

interface: str

EUI address.

class pcapkit.protocols.misc.pcapng.data.IF_SpeedOption(type, length, speed)[source]

Bases: Option

Data model for PCAP-NG file if_speed options.

speed: int

Interface speed, in bits per second.

class pcapkit.protocols.misc.pcapng.data.IF_TSResolOption(type, length, resolution)[source]

Bases: Option

Data model for PCAP-NG file if_tsresol options.

resolution: int

Time stamp resolution, in units per second.

class pcapkit.protocols.misc.pcapng.data.IF_TZoneOption(type, length, timezone)[source]

Bases: Option

Data model for PCAP-NG file if_tzone options.

timezone: timezone | timedelta

Time zone. An offset of 24 hours or more, which no timezone can hold, is kept as captured as a timedelta.

class pcapkit.protocols.misc.pcapng.data.IF_FilterOption(type, length, code, expression)[source]

Bases: Option

Data model for PCAP-NG file if_filter options.

code: FilterType

Filter code.

expression: bytes

Filter expression.

class pcapkit.protocols.misc.pcapng.data.IF_OSOption(type, length, os)[source]

Bases: Option

Data model for PCAP-NG file if_os options.

os: str

Operating system.

class pcapkit.protocols.misc.pcapng.data.IF_FCSLenOption(type, length, fcs_length)[source]

Bases: Option

Data model for PCAP-NG file if_fcslen options.

fcs_length: int

FCS length.

class pcapkit.protocols.misc.pcapng.data.IF_TSOffsetOption(type, length, offset)[source]

Bases: Option

Data model for PCAP-NG file if_tsoffset options.

offset: int

Timestamp offset (in seconds).

class pcapkit.protocols.misc.pcapng.data.IF_HardwareOption(type, length, hardware)[source]

Bases: Option

Data model for PCAP-NG file if_hardware options.

hardware: str

Hardware information.

class pcapkit.protocols.misc.pcapng.data.IF_TxSpeedOption(type, length, speed)[source]

Bases: Option

Data model for PCAP-NG file if_txspeed options.

speed: int

Interface transmit speed (in bits per second).

class pcapkit.protocols.misc.pcapng.data.IF_RxSpeedOption(type, length, speed)[source]

Bases: Option

Data model for PCAP-NG file if_rxspeed options.

speed: int

Interface receive speed (in bits per second).

class pcapkit.protocols.misc.pcapng.data.EPB_FlagsOption(type, length, direction, reception, fcs_len, checksum_not_ready, checksum_valid, tcp_segmentation_offloaded, reserved, crc_error, too_long, too_short, gap_error, unaligned_error, delimiter_error, preamble_error, symbol_error)[source]

Bases: Option

Data model for PCAP-NG file epb_flags options.

direction: PacketDirection

Inbound / Outbound packet.

reception: PacketReception

Reception type.

fcs_len: int

FCS length.

checksum_not_ready: bool

Checksum not ready (bit 9).

checksum_valid: bool

Checksum valid (bit 10).

tcp_segmentation_offloaded: bool

TCP segmentation offloaded (bit 11).

reserved: int

Bits 12 to 23 of the flags word, kept verbatim (reserved bits and unnamed link-layer-dependent errors).

crc_error: bool

Link-layer-dependent error - CRC error (bit 24).

too_long: bool

Link-layer-dependent error - packet too long error (bit 25).

too_short: bool

Link-layer-dependent error - packet too short error (bit 26).

gap_error: bool

Link-layer-dependent error - wrong Inter Frame Gap error (bit 27).

unaligned_error: bool

Link-layer-dependent error - unaligned frame error (bit 28).

delimiter_error: bool

Link-layer-dependent error - Start Frame Delimiter error (bit 29).

preamble_error: bool

Link-layer-dependent error - preamble error (bit 30).

symbol_error: bool

Link-layer-dependent error - symbol error (bit 31).

class pcapkit.protocols.misc.pcapng.data.EPB_HashOption(type, length, algorithm, hash)[source]

Bases: Option

Data model for PCAP-NG epb_hash options.

algorithm: HashAlgorithm

Hash algorithm.

hash: bytes

Hash value.

class pcapkit.protocols.misc.pcapng.data.EPB_DropCountOption(type, length, drop_count)[source]

Bases: Option

Data model for PCAP-NG epb_dropcount options.

drop_count: int

Number of packets dropped by the interface.

class pcapkit.protocols.misc.pcapng.data.EPB_PacketIDOption(type, length, packet_id)[source]

Bases: Option

Data model for PCAP-NG epb_packetid options.

packet_id: int

Packet ID.

class pcapkit.protocols.misc.pcapng.data.EPB_QueueOption(type, length, queue_id)[source]

Bases: Option

Data model for PCAP-NG epb_queue options.

queue_id: int

Queue ID.

class pcapkit.protocols.misc.pcapng.data.EPB_VerdictOption(type, length, verdict, value)[source]

Bases: Option

Data model for PCAP-NG epb_verdict options.

verdict: VerdictType

Verdict type.

value: bytes

Verdict value.

class pcapkit.protocols.misc.pcapng.data.NS_DNSNameOption(type, length, name)[source]

Bases: Option

Data model for PCAP-NG ns_dnsname option.

name: str

DNS name.

class pcapkit.protocols.misc.pcapng.data.NS_DNSIP4AddrOption(type, length, ip)[source]

Bases: Option

Data model for PCAP-NG ns_dnsIP4addr option.

ip: IPv4Address

IPv4 address.

class pcapkit.protocols.misc.pcapng.data.NS_DNSIP6AddrOption(type, length, ip)[source]

Bases: Option

Data model for PCAP-NG ns_dnsIP6addr option.

ip: IPv6Address

IPv6 address.

class pcapkit.protocols.misc.pcapng.data.ISB_StartTimeOption(type, length, timestamp, timestamp_epoch)[source]

Bases: Option

Data model for PCAP-NG isb_starttime option.

timestamp: datetime

Start time.

timestamp_epoch: Decimal

Start time as in UNIX epoch (in seconds).

class pcapkit.protocols.misc.pcapng.data.ISB_EndTimeOption(type, length, timestamp, timestamp_epoch)[source]

Bases: Option

Data model for PCAP-NG isb_endtime option.

timestamp: datetime

End time.

timestamp_epoch: Decimal

End time as in UNIX epoch (in seconds).

class pcapkit.protocols.misc.pcapng.data.ISB_IFRecvOption(type, length, packets)[source]

Bases: Option

Data model for PCAP-NG isb_ifrecv option.

packets: int

Number of packets received.

class pcapkit.protocols.misc.pcapng.data.ISB_IFDropOption(type, length, packets)[source]

Bases: Option

Data model for PCAP-NG isb_ifdrop option.

packets: int

Number of packets dropped.

class pcapkit.protocols.misc.pcapng.data.ISB_FilterAcceptOption(type, length, packets)[source]

Bases: Option

Data model for PCAP-NG isb_filteraccept option.

packets: int

Number of packets accepted by the filter.

class pcapkit.protocols.misc.pcapng.data.ISB_OSDropOption(type, length, packets)[source]

Bases: Option

Data model for PCAP-NG isb_osdrop option.

packets: int

Number of packets dropped by the operating system.

class pcapkit.protocols.misc.pcapng.data.ISB_UsrDelivOption(type, length, packets)[source]

Bases: Option

Data model for PCAP-NG isb_usrdeliv option.

packets: int

Number of packets delivered to the user.

class pcapkit.protocols.misc.pcapng.data.PACK_FlagsOption(type, length, direction, reception, fcs_len, checksum_not_ready, checksum_valid, tcp_segmentation_offloaded, reserved, crc_error, too_long, too_short, gap_error, unaligned_error, delimiter_error, preamble_error, symbol_error)[source]

Bases: Option

Data model for PCAP-NG file pack_flags options.

direction: PacketDirection

Inbound / Outbound packet.

reception: PacketReception

Reception type.

fcs_len: int

FCS length.

checksum_not_ready: bool

Checksum not ready (bit 9).

checksum_valid: bool

Checksum valid (bit 10).

tcp_segmentation_offloaded: bool

TCP segmentation offloaded (bit 11).

reserved: int

Bits 12 to 23 of the flags word, kept verbatim (reserved bits and unnamed link-layer-dependent errors).

crc_error: bool

Link-layer-dependent error - CRC error (bit 24).

too_long: bool

Link-layer-dependent error - packet too long error (bit 25).

too_short: bool

Link-layer-dependent error - packet too short error (bit 26).

gap_error: bool

Link-layer-dependent error - wrong Inter Frame Gap error (bit 27).

unaligned_error: bool

Link-layer-dependent error - unaligned frame error (bit 28).

delimiter_error: bool

Link-layer-dependent error - Start Frame Delimiter error (bit 29).

preamble_error: bool

Link-layer-dependent error - preamble error (bit 30).

symbol_error: bool

Link-layer-dependent error - symbol error (bit 31).

class pcapkit.protocols.misc.pcapng.data.PACK_HashOption(type, length, algorithm, hash)[source]

Bases: Option

Data model for PCAP-NG pack_hash options.

algorithm: HashAlgorithm

Hash algorithm.

hash: bytes

Hash value.

class pcapkit.protocols.misc.pcapng.data.NameResolutionRecord(*args, **kwargs)[source]

Bases: Data

Data model for PCAP-NG NRB records.

type: RecordType

Record type.

length: int

Record value length.

padding: bytes

Padding of the record value to 32 bits, as captured; present only when it is not all zeros (#1437).

class pcapkit.protocols.misc.pcapng.data.UnknownRecord(type, length, data)[source]

Bases: NameResolutionRecord

Data model for PCAP-NG NRB unknown records.

data: bytes

Unknown record value.

class pcapkit.protocols.misc.pcapng.data.EndRecord(type, length)[source]

Bases: NameResolutionRecord

Data model for PCAP-NG nrb_record_end records.

class pcapkit.protocols.misc.pcapng.data.IPv4Record(type, length, ip, records)[source]

Bases: NameResolutionRecord

Data model for PCAP-NG nrb_record_ipv4 records.

ip: IPv4Address

IPv4 address.

records: tuple[str, ...]

Name resolution data.

class pcapkit.protocols.misc.pcapng.data.IPv6Record(type, length, ip, records)[source]

Bases: NameResolutionRecord

Data model for PCAP-NG nrb_record_ipv6 records.

ip: IPv6Address

IPv6 address.

records: tuple[str, ...]

Name resolution data.

class pcapkit.protocols.misc.pcapng.data.DSBSecrets(*args, **kwargs)[source]

Bases: Data

Data model for DSB secrets data.

class pcapkit.protocols.misc.pcapng.data.UnknownSecrets(data)[source]

Bases: DSBSecrets

Data model for unknown DSB secrets.

data: bytes

Secrets data.

class pcapkit.protocols.misc.pcapng.data.TLSKeyLogEntries(dict_=None, **kwargs)[source]

Bases: Data

Data model for the entries of a TLS key log, keyed by label.

A key is each TLSKeyLabel the log has an entry under, and its value that label’s client random to secret pairs, in log order, as an OrderedMultiInfo. A label also reads as an attribute, as entries.CLIENT_RANDOM.

Added in version 1.6.0.

class pcapkit.protocols.misc.pcapng.data.TLSKeyLog(entries)[source]

Bases: DSBSecrets

Data model for TLS key log DSB secrets.

Changed in version 1.6.0: entries is a TLSKeyLogEntries rather than a dict, and a mapping given for it is stored as one; to_dict() exports it as an OrderedMultiDict, as it does any nested data model. A pickle holds it as a dict, so pickles load across 1.6.0 in both directions (#2726).

entries: TLSKeyLogEntries

TLS key log entries.

data: str

TLS key log text as the block carries it, comments and line order included. Set on parsing only, and written back verbatim on rebuild.

__post_init__()[source]

Store a mapping given for entries as a TLSKeyLogEntries.

__getstate__()[source]

Return the state to pickle, holding entries as a dict.

A release before 1.6.0 loads them as the dict it holds, and __setstate__() loads them as a TLSKeyLogEntries.

Return type:

dict[str, Any]

__setstate__(state)[source]

Restore a pickled state, storing entries as a TLSKeyLogEntries.

Parameters:

state (dict[str, Any]) – The state __getstate__() returns, or one holding the entries as a dict, as before 1.6.0.

class pcapkit.protocols.misc.pcapng.data.WireGuardKeyLog(entries)[source]

Bases: DSBSecrets

Data model for WireGuard key DSB secrets.

entries: OrderedMultiInfo[WireGuardKeyLabel, bytes]

WireGuard Key Log entries.

data: str

WireGuard key log text as the block carries it, comments included. Set on parsing only, and written back verbatim on rebuild.

class pcapkit.protocols.misc.pcapng.data.ZigBeeNWKKey(nwk_key, pan_id)[source]

Bases: DSBSecrets

Data model for ZigBee NWK Key and ZigBee PANID secrets data.

nwk_key: bytes

AES-128 NWK key.

pan_id: int

PAN ID.

data: bytes

Secrets Data octets as the block carries them, which a Secrets Length may make shorter or longer than the key’s fixed width. Set on parsing only, and written back verbatim on rebuild (#1986).

class pcapkit.protocols.misc.pcapng.data.ZigBeeAPSKey(aps_key, pan_id, short_address)[source]

Bases: DSBSecrets

Data model for ZigBee APS Key secrets data.

aps_key: bytes

AES-128 APS key.

pan_id: int

PAN ID.

short_address: int

Node short address.

data: bytes

Secrets Data octets as the block carries them, as for ZigBeeNWKKey.data. Set on parsing only, and written back verbatim on rebuild (#1986).

Footnotes