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 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;

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

Bases: ProtocolBase[Header, Header]

PCAP file global header extractor.

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

Post initialisation hook.

Parameters:

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

• length (Optional[int]) – Length of packet data.

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

Return type:

None

See also

For construction argument, please refer to make().

classmethod __index__()

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)

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 nano-timestamp PCAP file.

Parameters:

• length (Optional[int]) – 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='little', lilendian=None, bigendian=None, nanosecond=False, version=(2, 4), version_major=None, version_minor=None, thiszone=0, sigfigs=0, snaplen=262144, network=LinkType.NULL, network_default=None, network_namespace=None, network_reversed=False, **kwargs)

Make (construct) packet data.

Parameters:

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

• lilendian (Optional[bool]) – little-endian flag

• bigendian (Optional[bool]) – big-endian flag

• nanosecond (bool) – nanosecond-resolution file flag

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

• version_major (Optional[int]) – major version number

• version_minor (Optional[int]) – 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 | IntEnum | str | int) – data link type

• network_default (Optional[int]) – default value for unknown data link type

• network_namespace (Union[dict[str, int], dict[int, str], Type[IntEnum], Type[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)

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.

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

Post initialisation hook.

Parameters:

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

• length (Optional[int]) – Length of packet data.

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

Return type:

None

See also

For construction argument, please refer to make().

Header Schemas

class pcapkit.protocols.schema.misc.pcap.header.Header(dict_=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: Enum_LinkType = <EnumField network>

Data link type.

Data Models

class pcapkit.protocols.data.misc.pcap.header.Header(*args: VT, **kwargs: VT)

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(*args: VT, **kwargs: VT)

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 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;

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

Bases: ProtocolBase[Frame, Frame]

Per packet frame header extractor.

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

Index	Protocol
pcapkit.const.reg.linktype.LinkType.ETHERNET	pcapkit.protocols.link.ethernet.Ethernet
pcapkit.const.reg.linktype.LinkType.IPV4	pcapkit.protocols.internet.ipv4.IPv4
pcapkit.const.reg.linktype.LinkType.IPV6	pcapkit.protocols.internet.ipv6.IPv6

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 full qualified class name of the new protocol class should be as {protocol.module}.{protocol.name}.

Parameters:

• code (LinkType) – protocol code as in LinkType

• module – module descriptor or a Protocol subclass

Return type:

None

index(name)

Call ProtoChain.index.

Parameters:

name (Union[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)

Unpack (parse) packet data.

Parameters:

• length (Optional[int]) – Length of packet data.

• **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.

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

Read each block after global header.

Parameters:

• length (Optional[int]) – Length of data to be read.

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

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

Returns:

Parsed packet data.

Return type:

Data_Frame

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 (Union[float, Decimal, int, datetime, None]) – UNIX-Epoch timestamp

• ts_sec (Optional[int]) – timestamp seconds

• ts_usec (Optional[int]) – timestamp microseconds

• incl_len (Optional[int]) – number of octets of packet saved in file

• orig_len (Optional[int]) – 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)

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.

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

Protocol index mapping for decoding next layer, c.f. self._decode_next_layer & self._import_next_layer. The values should be a tuple representing the module name and class name, or a Protocol subclass.

Type:

DefaultDict[Enum_LinkType, ModuleDescriptor[Protocol] | Type[Protocol]]

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

Initialisation.

Parameters:

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

• length (Optional[int]) – Length of packet data.

• num (int) – Frame index number.

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

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

Return type:

None

See also

For construction argument, please refer to make().

__index__()

Index of the frame.

Parameters:

self (Optional[Frame]) – Frame object or None.

Return type:

int

Returns:

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

Raises:

UnsupportedCall – This protocol has no registry entry.

Header Schemas

class pcapkit.protocols.schema.misc.pcap.frame.Frame(dict_=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.

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.

Data Models

class pcapkit.protocols.data.misc.pcap.frame.Frame(*args: VT, **kwargs: VT)

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

Number of octets of packet saved in file.

cap_len: int

Actual length of packet.

protocols: str

Protocol chain.

class pcapkit.protocols.data.misc.pcap.frame.FrameInfo(*args: VT, **kwargs: VT)

Bases: Data

Frame metadata information.

ts_sec: int

Timestamp seconds.

ts_usec: int

Timestamp microseconds.

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