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 contains Header only, which implements an extractor for global headers [*] of PCAP, whose structure is described as below:

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.Header(file=None, length=None, **kwargs)[source]

Bases: ProtocolBase[Header, Header]

PCAP file global header extractor.

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

Post initialisation hook.

Overloads:
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__()[source]

Numeral registry index of the protocol.

Raises:

UnsupportedCall – This protocol has no registry entry.

Return type:

NoReturn

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)[source]

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:

FileError – If the magic number is invalid.

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, network_default=None, network_namespace=None, network_reversed=False, **kwargs)[source]

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 | IntEnum | aenum.IntEnum | str | int) – data link type

  • network_default (int | None) – default value for unknown data link type

  • network_namespace (dict[str, int] | dict[int, str] | Type[IntEnum] | Type[aenum.IntEnum] | None) – data link type namespace

  • network_reversed (bool) – if namespace is str -> int pairs

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

Return type:

Header

Returns:

Constructed packet data.

classmethod _make_data(data)[source]

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)[source]

Read next layer protocol type.

Parameters:

size (int) – buffer size

Return type:

LinkType

Returns:

Link layer protocol enumeration.

Header Schemas

pcapkit.protocols.schema.misc.pcap.header.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.schema.misc.pcap.header.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.schema.misc.pcap.header.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.schema.misc.pcap.header.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.schema.misc.pcap.header.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)[source]

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

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

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.data.misc.pcap.header.MagicNumber(data, byteorder, nanosecond)[source]

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 contains Frame only, which implements an extractor for frame headers [†] of PCAP, whose structure is described as below:

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.Frame(file=None, length=None, **kwargs)[source]

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.Loopback

pcapkit.const.reg.linktype.LinkType.ETHERNET

pcapkit.protocols.link.ethernet.Ethernet

pcapkit.const.reg.linktype.LinkType.LOOP

pcapkit.protocols.link.loopback.Loopback

pcapkit.const.reg.linktype.LinkType.IPV4

pcapkit.protocols.internet.ipv4.IPv4

pcapkit.const.reg.linktype.LinkType.IPV6

pcapkit.protocols.internet.ipv6.IPv6

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

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)[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 Protocol subclass.

Warns:

pcapkit.utilities.warnings.RegistryWarning – If this link type is already registered against PCAP frames, naming the displaced entry and its replacement so a caller can tell what was lost. Fires only when the incumbent differs from the replacement – see ProtocolBase.register for the guard this shares with register_protocol, and for the shipped descriptor a restore puts back (#1504).

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

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

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

We used a special keyword argument __packet__ to pass the global packet data to underlying methods. This is useful when the packet data is not available in the current instance.

pack(**kwargs)[source]

Pack (construct) packet data.

Parameters:

**kwargs (Any) – Arbitrary keyword arguments.

Return type:

bytes

Returns:

Constructed packet data.

Notes

We used a special keyword argument __packet__ to pass the global packet data to underlying methods. This is useful when the packet data is not available in the current instance.

As in Protocol.pack, the header is made on a copy outside construction, so the instance keeps its own (#1769).

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

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)[source]

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.

classmethod _make_data(data)[source]

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)[source]

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.

__proto__: DefaultDict[LinkType | int, 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 Protocol subclass.

__post_init__(file=None, length=None, *, num, header, **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.

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

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

See also

For construction arguments, please refer to make().

__index__()[source]

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.

Header Schemas

pcapkit.protocols.schema.misc.pcap.frame.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.schema.misc.pcap.frame.Frame(ts_sec=NO_VALUE, ts_usec=NO_VALUE, incl_len=NO_VALUE, orig_len=NO_VALUE, packet=NO_VALUE, *, __packet__=None, **kwargs)[source]

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

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

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.data.misc.pcap.frame.FrameInfo(ts_sec, ts_usec, incl_len, orig_len)[source]

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