Built-in Engines

PCAP Support

pcapkit.foundation.engines.pcap is the PCAP extraction engine used by pcapkit.foundation.extraction.Extractor.

class pcapkit.foundation.engines.pcap.PCAP(extractor)[source]

Bases: EngineBase[Frame]

PCAP file extraction support.

Parameters:

extractor (Extractor) – Extractor instance.

__engine_name__: str = 'PCAP'

Engine name.

__engine_module__: str = 'pcapkit.protocols.misc.pcap'

Engine module name.

property header: Header

Global header.

property version: VersionInfo

Version of input PCAP file.

Data link layer protocol.

property nanosecond: bool

Nanosecond flag.

run()[source]

Start extraction.

This method is the entry point for PCAP file extraction. It will start the extraction process by parsing the PCAP global header and then halt the extraction process until the self.extractor.record_frames method is called.

The method will parse the PCAP global header and save the parsed result as self.header. Information such as PCAP version, data link layer protocol type and nanosecond flag are also saved on the current PCAP engine instance.

For output, the method will create the output writer from the parsed PCAP global header, via Extractor._open_output, and dump the header under the name of Global Header – except to a PCAP writer, which has already written it.

read_frame()[source]

Read frames.

This method performs following operations:

  • extract frames and each layer of packets;

  • make Info object out of frame properties;

  • write to output file with corresponding dumper;

  • reassemble IP and/or TCP datagram;

  • trace TCP flows if any;

  • record frame Info object to frame storage.

Return type:

Frame

Returns:

Parsed frame instance.

_gbhdr: Header

Global header.

_vinfo: VersionInfo

Version info.

Data link layer protocol.

_nnsec: bool

Nanosecond flag.

PCAP-NG Support

pcapkit.foundation.engines.pcapng is the PCAP-NG extraction engine used by pcapkit.foundation.extraction.Extractor.

class pcapkit.foundation.engines.pcapng.PCAPNG(extractor)[source]

Bases: EngineBase[PCAPNG]

PCAP-NG file extraction support.

Parameters:

extractor (Extractor) – Extractor instance.

__engine_name__: str = 'PCAP-NG'

Engine name.

__engine_module__: str = 'pcapkit.protocols.misc.pcapng'

Engine module name.

run()[source]

Start extraction.

This method is the entry point for PCAP-NG file extraction. It will directly extract the first block, which should be a section header block, and then save the related information into the internal context storage.

Raises:

FormatError – If the first block is not a section header block, or if the output format is PCAP.

read_frame()[source]

Read frames.

This method performs following tasks:

  • read the next block from input file;

  • check if the block is a packet block;

  • if not, save the block into the internal context storage and repeat;

  • if yes, save the related information into the internal context storage;

  • write the parsed block into output file.

  • reassemble IP and/or TCP fragments;

  • trace TCP flows if any;

  • record frame information if any.

Return type:

PCAPNG

Returns:

Parsed PCAP-NG block.

_ctx: Context

Current context.

_ctx_list: list[Context]

File context storage.

Internal Definitions

class pcapkit.foundation.engines.pcapng.Context(*args: VT, **kwargs: VT)[source]

Bases: Info

Context manager for PCAP-NG file format.

Important

Packet blocks – PacketBlock, SimplePacketBlock and EnhancedPacketBlock – are not stored in Context, since the Extractor stores them directly.

section: SectionHeaderBlock

Section header.

interfaces: list[InterfaceDescriptionBlock]

Interface descriptions.

names: list[NameResolutionBlock]

Name resolution records.

journals: list[SystemdJournalExportBlock]

systemd(1) journal export records.

secrets: list[DecryptionSecretsBlock]

Decryption secrets.

custom: list[CustomBlock]

Custom blocks.

statistics: list[InterfaceStatisticsBlock]

Interface statistics.

unknown: list[UnknownBlock]

Unknown blocks.