Core Interface¶

pcapkit.interface.core defines core user-oriented interfaces, variables, and etc., which wraps around the foundation classes from pcapkit.foundation.

pcapkit.interface.core.extract(fin=None, fout=None, format=None, auto=True, extension=True, store=True, files=False, nofile=False, verbose=False, engine=None, layer=None, protocol=None, reassembly=False, reasm_strict=True, reasm_store=True, reasm_timeout=None, trace=False, trace_fout=None, trace_format=None, trace_byteorder='little', trace_nanosecond=False, trace_bidirectional=True, trace_analyse=False, ip=False, ipv4=False, ipv6=False, tcp=False, buffer_size=131072, buffer_save=False, buffer_path=None, no_eof=False, context=None)[source]¶

Extract a PCAP file.

Parameters:

fin (str | IO[bytes] | None) – file name to be read or a binary IO object; if file not exist, raise FileNotFound
fout (str | None) – file name to be written
format (Literal['pcap', 'cap', 'json', 'tree', 'text', 'txt', 'plist', 'xml'] | None) – file format of output
auto (bool) – if automatically run till EOF
extension (bool) – if check and append extensions to output file
store (bool) – if store extracted packet info
files (bool) – if split each frame into different files
nofile (bool) – if no output file is to be dumped
verbose (bool | Callable[[Extractor, Frame | PCAPNG | Packet | Packet | Packet | pcap_packet | tuple[float, bytes]], Any]) – a bool value or a function takes the Extractor instance and current parsed frame (depends on engine selected) as parameters to print verbose output information
engine (Literal['default', 'pcapkit', 'dpkt', 'scapy', 'pyshark', 'pypcap', 'pcap_ct', 'pypcapfile'] | None) – extraction engine to be used
layer (Literal['link', 'internet', 'transport', 'application', 'none'] | None | Type[ProtocolBase]) – extract til which layer
protocol (str | ProtocolBase | Type[ProtocolBase] | None) – extract til which protocol
reassembly (bool) – if perform reassembly
reasm_strict (bool) – if set strict flag for reassembly
reasm_store (bool) – if store reassembled datagrams
reasm_timeout (float | None) – reassembly timeout in seconds, on the capture’s own clock; None selects each protocol’s default (60 seconds for IPv4 and IPv6, disabled for TCP)
trace (bool) – if trace TCP traffic flows
trace_fout (str | None) – path name for flow tracer if necessary
trace_format (Literal['pcap', 'cap', 'json', 'tree', 'text', 'txt', 'plist', 'xml'] | None) – output file format of flow tracer
trace_byteorder (Literal['big', 'little']) – output file byte order
trace_nanosecond (bool) – output nanosecond-resolution file flag
trace_bidirectional (bool) – whether both halves of a conversation are traced as one flow, which is the default
trace_analyse (bool) – whether each traced flow reassembles its application layer, so that its packet can be read; off by default
ip (bool) – if record data for IPv4 & IPv6 reassembly (must be used with reassembly=True)
ipv4 (bool) – if perform IPv4 reassembly (must be used with reassembly=True)
ipv6 (bool) – if perform IPv6 reassembly (must be used with reassembly=True)
tcp (bool) – if perform TCP reassembly and/or flow tracing (must be used with reassembly=True or trace=True)
buffer_size (int) – buffer size for reading input file (for SeekableReader only)
buffer_save (bool) – if save buffer to file (for SeekableReader only)
buffer_path (str | None) – path name for buffer file if necessary (for SeekableReader only)
no_eof (bool) – if not raise EOFError when reach EOF – retry instead, which is what a live capture on a pipe or on standard input wants, since a read there blocks until the writer produces more or closes. Retrying stops as soon as one retry finds nothing new, so an exhausted input finishes rather than spinning; on a seekable input, where nothing blocks, that means a file still being appended to ends at the data present when the extraction reached it

context (ContextRegistry | ProtocolContext | Mapping[str, ProtocolContext] | Iterable[ProtocolContext] | None) –

caller supplied parsing context for protocols that need information not carried on the wire, keyed by protocol index ID – c.f. pcapkit.corekit.context. The motivating case is ESP, which needs the Security Association to find the trailer and decrypt the payload:

>>> from pcapkit.protocols.internet.esp import (Cipher, ESPContext,
...                                            SecurityAssociation)
>>> sa = SecurityAssociation(spi=0x4321, encryption=Cipher.AES_CBC,
...                          encryption_key=key)
>>> extraction = pcapkit.extract('esp.pcap', context=ESPContext(sa))

Return type:

Extractor

Returns:

An Extractor object.

Changed in version 1.2.0: strict is renamed reasm_strict, with no alias, and reasm_store is inserted after it, so a positional argument from trace onwards moves one place along.

Changed in version 1.5.0: reasm_timeout, trace_bidirectional and trace_analyse are inserted among the positional parameters and context is appended, so a positional argument after reasm_store has to move to a keyword. Flows are traced bidirectionally by default, and IPv4 and IPv6 reassembly buffers expire after 60 seconds of capture time.

pcapkit.interface.core.reassemble(protocol, strict=False, timeout=None)[source]¶

Reassemble fragmented datagrams.

Parameters:

protocol (str | Type[ProtocolBase]) – protocol to be reassembled
strict (bool) – if True, report a datagram that is not completely reassembled as the tuple of its received runs; otherwise as one contiguous payload
timeout (float | None) – reassembly timeout in seconds, on the capture’s own clock; None selects the protocol’s own default

Return type:

ReassemblyBase

Returns:

A ReassemblyBase object of corresponding protocol.

Raises:

FormatError – If protocol is NOT any of IPv4, IPv6 or TCP.

Changed in version 1.5.0: timeout is added. IPv4 and IPv6 buffers expire after 60 seconds of capture time by default, where 1.4.x held them for the life of the object.

pcapkit.interface.core.trace(protocol, fout, format, byteorder='little', nanosecond=False, bidirectional=True)[source]¶

Trace flows.

Parameters:

protocol (str | Type[ProtocolBase]) – protocol to be reassembled
fout (str | None) – output path
format (str | None) – output format
byteorder (Literal['little', 'big']) – output file byte order
nanosecond (bool) – output nanosecond-resolution file flag
bidirectional (bool) – whether both halves of a conversation are traced as one flow, which is the default

Return type:

TraceFlowBase

Returns:

A TraceFlowBase object.

Raises:

FormatError – If protocol is NOT TCP.

Changed in version 1.5.0: bidirectional is added, and by default both directions of a conversation are traced as one flow; 1.4.x traced each direction as a flow of its own.

Constants Definition¶

Output File Formats¶

pcapkit.interface.core.TREE = 'tree'¶

pcapkit.interface.core.JSON = 'json'¶

pcapkit.interface.core.PLIST = 'plist'¶

pcapkit.interface.core.PCAP = 'pcap'¶

Layer Thresholds¶

pcapkit.interface.core.RAW = 'none'¶

pcapkit.interface.core.LINK = 'link'¶

pcapkit.interface.core.INET = 'internet'¶

pcapkit.interface.core.TRANS = 'transport'¶

pcapkit.interface.core.APP = 'application'¶

Extraction Engines¶

pcapkit.interface.core.DPKT = 'dpkt'¶

pcapkit.interface.core.Scapy = 'scapy'¶

pcapkit.interface.core.PCAPKit = 'default'¶

pcapkit.interface.core.PyShark = 'pyshark'¶

pcapkit.interface.core.PyPCAP = 'pypcap'¶

pcapkit.interface.core.PCAP_CT = 'pcap_ct'¶

pcapkit.interface.core.PyPCAPFile = 'pypcapfile'¶

Note

Every engine pcapkit ships has a constant here. Each constant is its engine= string – 'pypcap', 'pcap_ct' and 'pypcapfile' for the PyPCAP, pcap-ct and PyPCAPFile ones – so the two spellings are interchangeable. An engine registered at runtime with register_extractor_engine() has no constant and is addressed by the name it was registered under.