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.

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 return all datagrams (including those not implemented) when submit
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 Reassembly object of corresponding protocol.

Raises:

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

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 TraceFlow object.

Raises:

FormatError – If protocol is NOT TCP.

Constants Defintion¶

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'¶

Extration 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 now has a constant here. The PyPCAP, pcap-ct and PyPCAPFile ones were added after the first four, so code written against an earlier release may still select them by their literal engine= values – 'pypcap', 'pcap_ct' and 'pypcapfile'. That keeps working: each constant is that string, 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.