Protocol Family¶

pcapkit.protocols is collection of all protocol families, with detailed implementation and methods.

All protocol classes are implemented as Protocol subclasses, which are responsible for processing extracted binary packet data and/or construct protocol packet from given information. Below is a brief diagram of the class hierarchy of pcapkit.protocols:

flowchart LR A{{ProtocolMeta}} -.->|metaclass| B(ProtocolBase) subgraph link [Link Layer] Link --> Ethernet & L2TP & OSPF & VLAN & ARP subgraph arp [ARP Family] ARP --> InARP & RARP subgraph rarp [RARP Family] RARP --> DRARP end end end subgraph internet [Internet Layer] Internet --> HIP & IPX & IP & ipv6ext subgraph ip [IP Family] IP --> IPv4 & IPv6 & IPsec subgraph ipsec [IPsec Family] IPsec --> AH end end subgraph ipv6ext [IPv6 Extension Header] IPv6-Frag & IPv6-Opts & IPv6-Route & HOPOPT & MH end end subgraph transport [Transport Layer] Transport --> TCP & UDP end subgraph application [Application Layer] Application --> HTTP & FTP subgraph http [HTTP Family] HTTP --> h1["HTTP/1.*"] & h2["HTTP/2"] end subgraph ftp [FTP Family] FTP & FTP_DATA end end subgraph misc [Miscellaneous] subgraph pcap [PCAP Format] Header & Frame end subgraph pcapng [PCAP-NG Format] PCAPNG end Raw & NoPayload end B --> Link & Internet & Transport & Application B --> Header & Frame & PCAPNG & Raw & NoPayload Raw --> FTP_DATA B --> C(Protocol) C --> D([user customisation ...]) click A "/pcapkit/protocols/protocol.html#pcapkit.protocols.protocol.ProtocolMeta" click B "/pcapkit/protocols/protocol.html#pcapkit.protocols.protocol.ProtocolBase" click C "/pcapkit/protocols/protocol.html#pcapkit.protocols.protocol.Protocol" click D "/ext.html#what-s-in-for-protocols" click Link "/pcapkit/protocols/link/link.html#pcapkit.protocols.link.Link" click Ethernet "/pcapkit/protocols/link/ethernet.html#pcapkit.protocols.link.ethernet.Ethernet" click L2TP "/pcapkit/protocols/link/l2tp.html#pcapkit.protocols.link.l2tp.L2TP" click OSPF "/pcapkit/protocols/link/ospf.html#pcapkit.protocols.link.ospf.OSPF" click VLAN "/pcapkit/protocols/link/vlan.html#pcapkit.protocols.link.vlan.VLAN" click ARP "/pcapkit/protocols/link/arp.html#pcapkit.protocols.link.arp.ARP" click InARP "/pcapkit/protocols/link/arp.html#pcapkit.protocols.link.arp.InARP" click RARP "/pcapkit/protocols/link/rarp.html#pcapkit.protocols.link.rarp.RARP" click DRARP "/pcapkit/protocols/link/rarp.html#pcapkit.protocols.link.rarp.DRARP" click Internet "/pcapkit/protocols/internet/internet.html#pcapkit.protocols.internet.Internet" click AH "/pcapkit/protocols/internet/ah.html#pcapkit.protocols.internet.ah.AH" click HIP "/pcapkit/protocols/internet/hip.html#pcapkit.protocols.internet.hip.HIP" click HOPOPT "/pcapkit/protocols/internet/hopopt.html#pcapkit.protocols.internet.hopopt.HOPOPT" click IP "/pcapkit/protocols/internet/ip.html#pcapkit.protocols.internet.ip.IP" click IPsec "/pcapkit/protocols/internet/ipsec.html#pcapkit.protocols.internet.ipsec.IPsec" click IPv4 "/pcapkit/protocols/internet/ipv4.html#pcapkit.protocols.internet.ip.ipv4.IPv4" click IPv6 "/pcapkit/protocols/internet/ipv6.html#pcapkit.protocols.internet.ip.ipv6.IPv6" click IPv6-Frag "/pcapkit/protocols/internet/ipv6_frag.html#pcapkit.protocols.internet.ipv6_frag.IPv6_Frag" click IPv6-Opts "/pcapkit/protocols/internet/ipv6_opts.html#pcapkit.protocols.internet.ipv6_opts.IPv6_Opts" click IPv6-Route "/pcapkit/protocols/internet/ipv6_route.html#pcapkit.protocols.internet.ipv6_route.IPv6_Route" click IPX "/pcapkit/protocols/internet/ipx.html#pcapkit.protocols.internet.ipx.IPX" click MH "/pcapkit/protocols/internet/mh.html#pcapkit.protocols.internet.mh.MH" click Transport "/pcapkit/protocols/transport/transport.html#pcapkit.protocols.transport.Transport" click TCP "/pcapkit/protocols/transport/tcp.html#pcapkit.protocols.internet.tcp.TCP" click UDP "/pcapkit/protocols/transport/udp.html#pcapkit.protocols.internet.udp.UDP" click Application "/pcapkit/protocols/application/application.html#pcapkit.protocols.application.Application" click HTTP "/pcapkit/protocols/application/http.html#pcapkit.protocols.application.http.HTTP" click h1 "/pcapkit/protocols/application/httpv1.html#pcapkit.protocols.application.httpv1.HTTP" click h2 "/pcapkit/protocols/application/httpv2.html#pcapkit.protocols.application.httpv2.HTTP" click FTP "/pcapkit/protocols/application/ftp.html#pcapkit.protocols.application.ftp.FTP" click FTP_DATA "/pcapkit/protocols/application/ftp.html#pcapkit.protocols.application.ftp.FTP_DATA" click Raw "/pcapkit/protocols/misc/raw.html#pcapkit.protocols.misc.raw.Raw" click NoPayload "/pcapkit/protocols/misc/null.html#pcapkit.protocols.misc.null.NoPayload" click PCAPNG "/pcapkit/protocols/misc/pcapng.html#pcapkit.protocols.misc.pcapng.PCAPNG" click Header "/pcapkit/protocols/misc/pcap.html#pcapkit.protocols.misc.pcap.header.Header" click Frame "/pcapkit/protocols/misc/pcap.html#pcapkit.protocols.misc.pcap.frame.Frame"

Protocol Registry¶

pcapkit.protocols.__proto__: dict[str, Type[ProtocolBase]]¶

Protocol registry.

Type:: dict[str, Type[Protocol]]

Header Schema¶

class pcapkit.protocols.schema.schema.Schema(dict_=None, **kwargs)[source]¶

Bases: Mapping[str, _VT], Generic[_VT]

Schema for protocol headers.

__payload__: str = 'payload'¶: Field name of the payload.

__additional__: list[str]¶: List of additional built-in names.

__excluded__: list[str]¶: List of names to be excluded from dict conversion.

static __new__(cls, *args, **kwargs)[source]¶

Create a new instance.

The class will try to automatically generate __init__ method with the same signature as specified in class variables’ type annotations, which is inspired by PEP 557 (dataclasses).

Parameters:

*args (TypeVar(_VT)) – Arbitrary positional arguments.
**kwargs (TypeVar(_VT)) – Arbitrary keyword arguments.

Return type:

Self

pack(packet=None)[source]¶

Pack Schema into bytes.

Parameters:: packet (Optional[dict[str, Any]]) – Packet data.
Return type:: bytes
Returns:: Packed Schema as bytes.

Notes

Since we do not know the length of the packet, we use a reasonable default value -1 for the __length__ field, as the Field class will consider negative value as a placeholder.

If you want to pack the packet with the correct length, please provide the __length__ value before packing.

pre_pack(packet)[source]¶

Prepare packet data for packing process.

Parameters:: packet (dict[str, Any]) – packet data
Return type:: None

Note

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

classmethod unpack(cls, data, length=None, packet=None)[source]¶

Unpack bytes into Schema.

Parameters:

data (Union[bytes, IO[bytes]]) – Packed data.
length (Optional[int]) – Length of data.
packet (Optional[dict[str, Any]]) – Unpacked data.

Return type:

Self

Returns:

Unpacked data as Schema.

Notes

We used a __length__ key in packet to record the length of the remaining data, which is used to determine the length of the payload field.

And a __padding_length__ key in the packet to record the length of the padding field after an OptionField, which is used to potentially determine the length of the remaining padding field data.

classmethod pre_unpack(packet)[source]¶

Prepare packet data for unpacking process.

Parameters:: packet (dict[str, Any]) – packet data
Return type:: None

Note

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

post_process(packet)[source]¶

Revise schema data after packing and/or unpacking process.

Parameters:: packet (dict[str, Any]) – Unpacked data.
Return type:: Schema
Returns:: Revised schema.

get_payload(name=None)[source]¶

Get payload of Schema.

Parameters:: name (Optional[str]) – Name of the payload field.
Return type:: bytes
Returns:: Payload of Schema as bytes.

classmethod from_dict(dict_=None, **kwargs)[source]¶

Create a new instance.

If dict_ is present and has a .keys() method, then does: for k in dict_: self[k] = dict_[k].
If dict_ is present and has no .keys() method, then does: for k, v in dict_: self[k] = v.
If dict_ is not present, then does: for k, v in kwargs.items(): self[k] = v.

Parameters:

dict_ (Union[Mapping[str, TypeVar(_VT)], Iterable[tuple[str, TypeVar(_VT)]], None]) – Source data.
**kwargs (TypeVar(_VT)) – Arbitrary keyword arguments.

Return type:

Self

to_dict()[source]¶: Convert Schema into dict. :rtype: dict[str, TypeVar(_VT)]

Important

We only convert nested Schema objects into dict if they are the direct value of the Schema object’s attribute. Should such Schema objects be nested within other data, types, such as list, tuple, set, etc., we shall not convert them into dict and remain them intact.

to_bytes()[source]¶

Convert Schema into bytes.

Return type:: bytes

__fields__: OrderedDict[str, FieldBase]¶: Mapping of fields.

class pcapkit.protocols.schema.schema.EnumSchema(dict_=None, **kwargs)[source]¶

Bases: Schema, Generic[_ET]

Schema with enumeration mapping support.

Examples

To create an enumeration mapping supported schema, simply

class MySchema(EnumSchema[MyEnum]):

    # optional, set the default schema for enumeration mapping
    # if the enumeration number is not found in the mapping
    __default__ = lambda: UnknownSchema  # by default, None

then, you can use inheritance to create a list of schemas for this given enumeration mapping:

class OneSchema(MySchema, code=MyEnum.ONE):
    ...

class MultipleSchema(MySchema, code=[MyEnum.TWO, MyEnum.THREE]):
    ...

or optionally, using the register() method to register a schema to the enumeration mapping:

MySchema.register(MyEnum.ZERO, ZeroSchema)

And now you can access the enumeration mapping via the registry property (more specifically, class attribute):

>>> MySchema.registry[MyEnum.ONE]  # OneSchema

__default__: Callable[[], Type[Self]]¶: Callback to return the default schema for enumeration mapping, by default is a lambda: None statement.

__enum__: DefaultDict[TypeVar(_ET, bound= Enum), Type[Self]]¶: Mapping of enumeration numbers to schemas.

property registry: DefaultDict[_ET, Type[Self]]¶: Mapping of enumeration numbers to schemas.

Note

This property is also available as a class attribute.

classmethod register(code, schema)[source]¶

Parameters:

code (TypeVar(_ET, bound= Enum)) – Enumetaion code.
schema (Type[Self]) – Enumetaion schema.

Return type:

None

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

Parameters:

code (Union[TypeVar(_ET, bound= Enum), Iterable[TypeVar(_ET, bound= Enum)], None]) – Enumeration code. It can be either a single enumeration or a list of enumerations.
*args (Any) – Arbitrary positional arguments.
**kwargs (Any) – Arbitrary keyword arguments.

Return type:

None

If code is provided, the subclass will be registered to the registry mapping with the given code. If code is not given, the subclass will not be registered.

Notes

If __enum__ is not yet defined at function call, it will automatically be defined as a collections.defaultdict object, with the default value set to __default__.

If intended to customise the __enum__ mapping, it is possible to override the __init_subclass__() method and define __enum__ manually.

@pcapkit.protocols.schema.schema.schema_final(cls, *, _finalised=True)[source]¶

Finalise schema class.

This decorator function is used to generate necessary attributes and methods for the decorated Schema class. It can be useful to reduce runtime generation time as well as caching already generated attributes.

Notes

The decorator should only be used on the final class, otherwise, any subclasses derived from a finalised schema class will not be re-finalised.

Parameters:

cls (TypeVar(_ST, bound= Type[Schema])) – Schema class.
_finalised (bool) – Whether to make the schema class finalised.

Return type:

TypeVar(_ST, bound= Type[Schema])

Returns:

Finalised schema class.

Internal Definitions¶

class pcapkit.protocols.schema.schema.SchemaMeta(name: str, bases: tuple[type, ...], attrs: dict[str, Any], **kwargs: Any)[source]¶

Bases: ABCMeta

Meta class to add dynamic support to Schema.

This meta class is used to generate necessary attributes for the Schema class. It can be useful to reduce runtime generation cost as well as caching already generated attributes.

Schema.__fields__ is a dictionary of field names and their corresponding Field objects, which are used to define and parse the protocol headers. The field dictionary will automatically be populated from the class attributes of the Schema class, and the field names will be the same as the attribute names.

See also

This is implemented thru setting up the initial field dictionary in the __prepare__() method, and then inherit the field dictionaries from the base classes.

Later, during the class creation, the Field.__set_name__ method will be called to set the field name for each field object, as well as to add the field object to the field dictionary.
Schema.__additional__ and Schema.__excluded__ are lists of additional and excluded field names, which are used to determine certain names to be included or excluded from the field dictionary. They will be automatically populated from the class attributes of the Schema class and its base classes.
Note

This is implemented thru the __new__() method, which will inherit the additional and excluded field names from the base classes, as well as populating the additional and excluded field from the subclass attributes.
```
class A(Schema):
    __additional__ = ['a', 'b']

class B(A):
    __additional__ = ['c', 'd']

class C(B):
    __additional__ = ['e', 'f']

print(A.__additional__)  # ['a', 'b']
print(B.__additional__)  # ['a', 'b', 'c', 'd']
print(C.__additional__)  # ['a', 'b', 'c', 'd', 'e', 'f']
```

class pcapkit.protocols.schema.schema.EnumMeta(name: str, bases: tuple[type, ...], attrs: dict[str, Any], **kwargs: Any)[source]¶

Bases: SchemaMeta, Generic[_ET]

Meta class to add dynamic support for EnumSchema.

This meta class is used to generate necessary attributes for the SchemaMeta class. It can be useful to reduce runtime generation cost as well as caching already generated attributes.

registry is added to subclasses as an immutable proxy (similar to property, but on class variables) to the EnumSchema.__enum__ mapping.

Type Variables¶

pcapkit.protocols.schema.schema._VT: Any¶

pcapkit.protocols.schema.schema._ET: enum.Enum¶

pcapkit.protocols.schema.schema._ST: Type[pcapkit.protocols.schema.schema.Schema]¶

Data Model¶

class pcapkit.protocols.data.data.Data(dict_=None, **kwargs)[source]¶

Bases: Info

Base class for data models.

__excluded__: list[str]¶: List of names to be excluded from dict conversion.

See also

Please refer to Protocol._decode_next_layer for more information with the inserted names to be excluded.