PCAP File Headers

pcapkit.protocols.misc.pcap contains header descriptions for PCAP files, including global header (Header) and frame header (Frame).

Global Header

pcapkit.protocols.misc.pcap.header.protocol contains Header only, which implements an extractor for global headers [*] of PCAP, whose structure is:

typedef struct pcap_hdr_s {
    guint32 magic_number;   /* magic number */
    guint16 version_major;  /* major version number */
    guint16 version_minor;  /* minor version number */
    gint32  thiszone;       /* GMT to local correction */
    guint32 sigfigs;        /* accuracy of timestamps */
    guint32 snaplen;        /* max length of captured packets, in octets */
    guint32 network;        /* data link type */
} pcap_hdr_t;

Changed in version 1.5.0: A global header cut short rebuilds as captured, where it rebuilt at full width (#1470).

class pcapkit.protocols.misc.pcap.header.protocol.Header(file=None, length=None, **kwargs)

Bases: ProtocolBase[Header, Header]

PCAP file global header extractor.

Changed in version 1.6.0: The network field of make() takes a member or an int code, resolved with the enumeration’s get; a name, a bool, or a code the field cannot carry raises ProtocolError, rather than resolving against an enumeration inferred from the caller’s frame or writing a different value (#2594).

Removed in version 1.6.0: The network_default, network_namespace and network_reversed arguments of make(); resolve a name with resolve_index() first (#2594).

property name: Literal['Global Header']

Name of corresponding protocol.

property length: Literal[24]

Header length of corresponding protocol.

property version: VersionInfo

Version information of input PCAP file.

property payload: NoReturn

Payload of current instance.

Raises:

UnsupportedCall – This protocol doesn’t support payload.

property protocol: LinkType

Data link type.

property protochain: NoReturn

Protocol chain of current instance.

Raises:

UnsupportedCall – This protocol doesn’t support protochain.

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

Header byte order.

property nanosecond: bool

Nanosecond-resolution flag.

read(length=None, **kwargs)

Read global header of PCAP file.

Notes

PCAP file has four different valid magic numbers.

• d4 c3 b2 a1 – Little-endian microsecond-timestamp PCAP file.

• a1 b2 c3 d4 – Big-endian microsecond-timestamp PCAP file.

• 4d 3c b2 a1 – Little-endian nanosecond-timestamp PCAP file.

• a1 b2 3c 4d – Big-endian nanosecond-timestamp PCAP file.

Parameters:

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

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

Return type:

Header

Returns:

Parsed packet data.

Raises:

ProtocolError – If the magic number is invalid. Parsing does not get this far with one: the schema’s magic_number_callback() raises it while the header is unpacked.

make(byteorder=sys.byteorder, lilendian=None, bigendian=None, nanosecond=False, version=(2, 4), version_major=None, version_minor=None, thiszone=0, sigfigs=0, snaplen=0x40_000, network=LinkType.NULL, **kwargs)

Make (construct) packet data.

Parameters:

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

• lilendian (bool | None) – little-endian flag; overrides byteorder if given

• bigendian (bool | None) – big-endian flag; overrides byteorder if given

• nanosecond (bool) – nanosecond-resolution file flag

• version (tuple[int, int] | VersionInfo) – version information

• version_major (int | None) – major version number

• version_minor (int | None) – minor version number

• thiszone (int) – GMT to local correction

• sigfigs (int) – accuracy of timestamps

• snaplen (int) – max length of captured packets, in octets

• network (LinkType | int) – data link type

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

Return type:

Header

Returns:

Constructed packet data.

Raises:

ProtocolError – If network is a name, a bool, or a member or code the 32-bit network field cannot carry.

__post_init__(file=None, length=None, **kwargs)

Post initialisation hook.

Overloads:

• file (IO[bytes] | bytes), length (int | None) = ..., **kwargs (Any) → None

• **kwargs (Any) → None

Parameters:

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

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

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

See also

For construction arguments, please refer to make().

Notes

A header the data ends inside keeps that in its info, so that from_data() rebuilds only what was captured (#1470).

classmethod __index__()

Numeral registry index of the protocol.

Raises:

UnsupportedCall – This protocol has no registry entry.

Return type:

NoReturn

classmethod _make_data(data)

Create key-value pairs from data for protocol construction.

Parameters:

data (Header) – protocol data

Return type:

dict[str, Any]

Returns:

Key-value pairs for protocol construction.

_read_protos(size)

Read next layer protocol type.

Reads size octets as an unsigned integer in the file’s byte order (byteorder), falling back to little-endian before read() has set it (#2312).

Parameters:

size (int) – buffer size

Return type:

LinkType

Returns:

Link layer protocol enumeration.

Header Schemas

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

pcapkit.protocols.misc.pcap.header.schema.GLOBAL_HEADER_LEN = 24

Length of the PCAP global header, which opens the file. 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.pcap.header.schema.MAGIC_NUMBER: Dict[bytes, tuple[Literal['big', 'little'], bool]]

PCAP magic numbers, as the octets open the file, mapped to the byte order ('big' or 'little') and the timestamp resolution (True for nanoseconds, False for microseconds) each one declares. 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.pcap.header.schema.RESOLUTION: Dict[bool, int]

Units per second of a record’s ts_usec field, keyed by the nanosecond flag its file’s magic number declares (MAGIC_NUMBER): microseconds, or nanoseconds. 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.pcap.header.schema.RESOLUTION_PLACES: Dict[bool, int]

Decimal places of a ts_usec fraction at each resolution of RESOLUTION, keyed the same way – six for microseconds, nine for nanoseconds – and derived from it, so that an epoch rounded to its file’s resolution follows the one home (#1739).

Added in version 1.5.0.

class pcapkit.protocols.misc.pcap.header.schema.Header(magic_number=NO_VALUE, version_major=NO_VALUE, version_minor=NO_VALUE, thiszone=NO_VALUE, sigfigs=NO_VALUE, snaplen=NO_VALUE, network=NO_VALUE, *, __packet__=None, **kwargs)

Bases: Schema

Global header of PCAP file.

magic_number: bytes = <BytesField magic_number>

Magic number.

version_major: int = <UInt16Field version_major>

Version number major.

version_minor: int = <UInt16Field version_minor>

Version number minor.

thiszone: int = <Int32Field thiszone>

GMT to local correction.

sigfigs: int = <UInt32Field sigfigs>

Accuracy of timestamps.

snaplen: int = <UInt32Field snaplen>

Max length of captured packets, in octets.

network: LinkType = <EnumField network>

Data link type.

Data Models

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

class pcapkit.protocols.misc.pcap.header.data.Header(magic_number, version, thiszone, sigfigs, snaplen, network)

Bases: Protocol

Global header of PCAP file.

magic_number: MagicNumber

Magic number.

version: VersionInfo

Version number.

thiszone: int

GMT to local correction.

sigfigs: int

Accuracy of timestamps.

snaplen: int

Max length of captured packets, in octets.

network: LinkType

Data link type.

class pcapkit.protocols.misc.pcap.header.data.MagicNumber(data, byteorder, nanosecond)

Bases: Data

Magic number of PCAP file.

data: bytes

Magic number sequence.

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

Byte order.

nanosecond: bool

Nanosecond-timestamp resolution flag.

Frame Header

pcapkit.protocols.misc.pcap.frame.protocol contains Frame only, which implements an extractor for frame headers [†] of PCAP, whose structure is:

typedef struct pcaprec_hdr_s {
    guint32 ts_sec;     /* timestamp seconds */
    guint32 ts_usec;    /* timestamp microseconds */
    guint32 incl_len;   /* number of octets of packet saved in file */
    guint32 orig_len;   /* actual length of packet */
} pcaprec_hdr_t;

Changed in version 1.5.0: bytes(frame) and packet hold this frame’s own octets, where they held the next frame’s (#357), and the parsed time is timezone-aware UTC. The parsed len is the on-wire length and cap_len the captured one, where the two were swapped (#618).

class pcapkit.protocols.misc.pcap.frame.protocol.Frame(file=None, length=None, **kwargs)

Bases: ProtocolBase[Frame, Frame]

Per packet frame header extractor.

This 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().

__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_pcap() does; PCAPNG, whose registry is keyed by the same enum, declares its own (#2268).

property name: str

Name of corresponding protocol.

property length: Literal[16]

Header length of corresponding protocol.

property header: Header

Global header of the PCAP file.

classmethod register(code, protocol)

Register a new protocol class.

Notes

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

Parameters:

• code (LinkType) – protocol code as in LinkType

• protocol (ModuleDescriptor[ProtocolBase] | Type[ProtocolBase]) – module descriptor or a ProtocolBase subclass

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 holds a different entry for PCAP frames, naming the displaced one and its replacement; see Protocol.register for the guard and for the shipped descriptor a restore puts back (#1504).

index(name)

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)

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 (#1769).

unpack(length=None, **kwargs)

Unpack (parse) packet data.

Parameters:

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

• _seek_set (int) – File offset before reading, forwarded to self.read through **kwargs.

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

Return type:

Frame

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.

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

Read each block after global header.

Parameters:

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

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

• _seek_set – File offset of the record’s own first octet, i.e. where the stream stood before self.unpack consumed the record. It cannot be recovered from the stream here, since that unpack has consumed the whole record, packet data included.

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

Returns:

Parsed packet data.

Return type:

Frame

Warns:

pcapkit.utilities.warnings.ProtocolWarning – If the timestamp is out of range, or if the record’s incl_len runs past the end of the data being parsed, in which case the record is kept as captured.

make(timestamp=None, ts_sec=None, ts_usec=None, incl_len=None, orig_len=None, packet=b'', nanosecond=False, **kwargs)

Make frame packet data.

Parameters:

• timestamp (float | Decimal | int | datetime | None) – UNIX-Epoch timestamp

• ts_sec (int | None) – timestamp seconds

• ts_usec (int | None) – timestamp microseconds

• incl_len (int | None) – number of octets of packet saved in file

• orig_len (int | None) – actual length of packet

• packet (bytes | ProtocolBase | Schema) – raw packet data

• nanosecond (bool) – nanosecond-resolution file flag

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

Return type:

Frame

Returns:

Constructed packet data.

__post_init__(file=None, length=None, *, num, header, **kwargs)

Initialisation.

Overloads:

• file (IO[bytes] | bytes), length (int | None) = ..., *, num (int), header (Header), **kwargs (Any) → None

• *, num (int), header (Header), **kwargs (Any) → None

Parameters:

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

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

• num (int) – Frame index number.

• header (Header) – Global header of the PCAP file.

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

See also

For construction arguments, please refer to make().

__index__()

Index of the frame.

Parameters:

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

Return type:

int

Returns:

If the object is initialised, i.e. self._fnum exists, returns the frame index number of itself; else raises UnsupportedCall.

Raises:

UnsupportedCall – If called on the class rather than on a frame.

classmethod _make_data(data)

Create key-value pairs from data for protocol construction.

Parameters:

data (Frame) – protocol data

Return type:

dict[str, Any]

Returns:

Key-value pairs for protocol construction.

Notes

The frame index and the global header are context of the PCAP file rather than fields of the frame, so they are not returned here: pass them to from_data() as num and header.

_dispatch_linktype(proto, length=None)

Link type a frame’s data is dispatched under.

Parameters:

• proto (int | None) – link type of the capture

• 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

LINKTYPE_RAW (101) carries a bare IPv4 or IPv6 datagram, and only the version nibble of its first octet tells which, so it has no entry of its own in __proto__ (#1502). Dispatched as IPV4 or IPV6, it reaches whatever those link types are registered against. An entry registered under RAW itself is used as it stands, and data of any other version is kept as Raw. PCAPNG._dispatch_linktype does the same for PCAP-NG.

Header Schemas

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

pcapkit.protocols.misc.pcap.frame.schema.RECORD_HEADER_LEN = 16

Length of a PCAP record header, which precedes each record’s packet data. The one home of this value (#1739); the format fixes it, so it is never configurable.

Added in version 1.5.0.

class pcapkit.protocols.misc.pcap.frame.schema.Frame(ts_sec=NO_VALUE, ts_usec=NO_VALUE, incl_len=NO_VALUE, orig_len=NO_VALUE, packet=NO_VALUE, *, __packet__=None, **kwargs)

Bases: Schema

Frame header of PCAP file format.

ts_sec: int = <UInt32Field ts_sec>

Timestamp seconds.

ts_usec: int = <UInt32Field ts_usec>

Timestamp microseconds, or nanoseconds in a nanosecond-resolution file.

incl_len: int = <UInt32Field incl_len>

Number of octets of packet saved in file.

orig_len: int = <UInt32Field orig_len>

Actual length of packet.

packet: bytes = <PayloadField packet>

Payload, read no further than the record header and it together can go in one read, sys.maxsize; the frame reader moves past the rest (#1975).

Data Models

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

class pcapkit.protocols.misc.pcap.frame.data.Frame(frame_info, time, number, time_epoch, len, cap_len)

Bases: Protocol

Frame header of PCAP file.

frame_info: FrameInfo

Metadata information.

time: datetime

Timestamp instance.

number: int

Frame index.

time_epoch: Decimal

UNIX timestamp.

len: int

Actual length of the packet as it appeared on the wire, i.e. the record header’s orig_len. Larger than cap_len for a frame the snapshot length cut short. Named after Wireshark’s frame.len, registered as “Frame length on the wire”.

cap_len: int

Number of octets of packet data actually captured and saved in the file, i.e. the record header’s incl_len, and so the number of octets packet holds. Named after Wireshark’s frame.cap_len, registered as “Frame length stored into the capture file”.

protocols: str

Protocol chain.

class pcapkit.protocols.misc.pcap.frame.data.FrameInfo(ts_sec, ts_usec, incl_len, orig_len)

Bases: Data

Frame metadata information.

ts_sec: int

Timestamp seconds.

ts_usec: int

Timestamp microseconds, or nanoseconds in a nanosecond-resolution file.

incl_len: int

Number of octets of packet saved in file.

orig_len: int

Actual length of packet.

Footnotes

[*]

https://wiki.wireshark.org/Development/LibpcapFileFormat#Global_Header

[†]

https://wiki.wireshark.org/Development/LibpcapFileFormat#Record_.28Packet.29_Header