def reassemble(protocol, strict=False):
"""Reassemble fragmented datagrams.
Keyword arguments:
* protocol -- str, protocol to be reassembled
* strict -- bool, if return all datagrams (including those not implemented) when submit (default is False)
<keyword> True / False
Returns:
* [if protocol is IPv4] IPv4_Reassembly -- a Reassembly object from `pcapkit.reassembly`
* [if protocol is IPv6] IPv6_Reassembly -- a Reassembly object from `pcapkit.reassembly`
* [if protocol is TCP] TCP_Reassembly -- a Reassembly object from `pcapkit.reassembly`
"""
if isinstance(protocol, type) and issubclass(protocol, Protocol):
protocol = protocol.__index__()
str_check(protocol)
bool_check(strict)
if protocol == 'IPv4':
return IPv4_Reassembly(strict=strict)
elif protocol == 'IPv6':
return IPv6_Reassembly(strict=strict)
elif protocol == 'TCP':
return TCP_Reassembly(strict=strict)
else:
raise FormatError(f'Unsupported reassembly protocol: {protocol}')
def reassemble(protocol, strict=False):
"""Reassemble fragmented datagrams.
Arguments:
protocol (Union[str, Type[Protocol]]) protocol to be reassembled
strict (bool): if return all datagrams (including those not implemented) when submit
Returns:
Union[IPv4_Reassembly, IPv6_Reassembly, TCP_Reassembly]: a :class:`~pcapkit.reassembly.reassembly.Reassembly`
object of corresponding protocol
Raises:
FormatError: If ``protocol`` is **NOT** any of IPv4, IPv6 or TCP.
"""
if isinstance(protocol, type) and issubclass(protocol, Protocol):
protocol = protocol.id()
str_check(protocol)
bool_check(strict)
if protocol == 'IPv4':
return IPv4_Reassembly(strict=strict)
if protocol == 'IPv6':
return IPv6_Reassembly(strict=strict)
if protocol == 'TCP':
return TCP_Reassembly(strict=strict)
raise FormatError(f'Unsupported reassembly protocol: {protocol}')
def get_proxies():
"""Get proxy for blocked sites."""
HTTP_PROXY = os.getenv('PCAPKIT_HTTP_PROXY')
HTTPS_PROXY = os.getenv('PCAPKIT_HTTPS_PROXY')
PROXIES = dict()
if HTTP_PROXY is not None:
str_check(HTTP_PROXY)
PROXIES['http'] = HTTP_PROXY
if HTTPS_PROXY is not None:
str_check(HTTPS_PROXY)
PROXIES['https'] = HTTPS_PROXY
return PROXIES
def trace(fout=None, format=None, byteorder=sys.byteorder, nanosecond=False):
"""Trace TCP flows.
Keyword arguments:
* fout -- str, output path
* format -- str, output format
* byteorder -- str, output file byte order
* nanosecond -- bool, output nanosecond-resolution file flag
"""
str_check(fout or '', format or '')
return TraceFlow(fout=fout,
format=format,
byteorder=byteorder,
nanosecond=nanosecond)
def trace(fout=None, format=None, byteorder=sys.byteorder, nanosecond=False): # pylint: disable=redefined-builtin
"""Trace TCP flows.
Arguments:
fout (str): output path
format (Optional[str]): output format
byteorder (str): output file byte order
nanosecond (bool): output nanosecond-resolution file flag
Returns:
TraceFlow: a :class:`~pcapkit.foundation.traceflow.TraceFlow` object
"""
str_check(fout or '', format or '')
return TraceFlow(fout=fout,
format=format,
byteorder=byteorder,
nanosecond=nanosecond)
def extract(
fin=None,
fout=None,
format=None, # basic settings
auto=True,
extension=True,
store=True, # internal settings
files=False,
nofile=False,
verbose=False, # output settings
engine=None,
layer=None,
protocol=None, # extraction settings
ip=False,
ipv4=False,
ipv6=False,
tcp=False,
strict=True, # reassembly settings
trace=False,
trace_fout=None,
trace_format=None, # trace settings
trace_byteorder=sys.byteorder,
trace_nanosecond=False): # trace settings
"""Extract a PCAP file.
Keyword arguments:
* fin -- str, file name to be read; if file not exist, raise an error
* fout -- str, file name to be written
* format -- str, file format of output
<keyword> 'plist' / 'json' / 'tree' / 'html'
* auto -- bool, if automatically run till EOF (default is True)
<keyword> True / False
* extension -- bool, if check and append extensions to output file (default is True)
<keyword> True / False
* store -- bool, if store extracted packet info (default is True)
<keyword> True / False
* files -- bool, if split each frame into different files (default is False)
<keyword> True / False
* nofile -- bool, if no output file is to be dumped (default is False)
<keyword> True / False
* verbose -- bool, if print verbose output information (default is False)
<keyword> True / False
* engine -- str, extraction engine to be used
<keyword> 'default | pcapkit'
* layer -- str, extract til which layer
<keyword> 'Link' / 'Internet' / 'Transport' / 'Application'
* protocol -- str, extract til which protocol
<keyword> available protocol name
* ip -- bool, if record data for IPv4 & IPv6 reassembly (default is False)
<keyword> True / False
* ipv4 -- bool, if perform IPv4 reassembly (default is False)
<keyword> True / False
* ipv6 -- bool, if perform IPv6 reassembly (default is False)
<keyword> True / False
* tcp -- bool, if perform TCP reassembly (default is False)
<keyword> True / False
* strict -- bool, if set strict flag for reassembly (default is True)
<keyword> True / False
* trace -- bool, if trace TCP traffic flows (default is False)
<keyword> True / False
* trace_fout -- str, path name for flow tracer if necessary
* trace_format -- str, output file format of flow tracer
<keyword> 'plist' / 'json' / 'tree' / 'html' / 'pcap'
* trace_byteorder -- str, output file byte order
<keyword> 'little' / 'big'
* trace_nanosecond -- bool, output nanosecond-resolution file flag
<keyword> True / False
Returns:
* Extractor -- an Extractor object form `pcapkit.extractor`
"""
if isinstance(layer, type) and issubclass(layer, Protocol):
layer = layer.__layer__
if isinstance(protocol, type) and issubclass(protocol, Protocol):
protocol = protocol.__index__()
str_check(fin or '', fout or '', format or '', trace_fout or '',
trace_format or '', engine or '', layer or '', *(protocol or ''))
bool_check(files, nofile, verbose, auto, extension, store, ip, ipv4, ipv6,
tcp, strict, trace)
return Extractor(fin=fin,
fout=fout,
format=format,
store=store,
files=files,
nofile=nofile,
auto=auto,
verbose=verbose,
extension=extension,
engine=engine,
layer=layer,
protocol=protocol,
ip=ip,
ipv4=ipv4,
ipv6=ipv6,
tcp=tcp,
strict=strict,
trace=trace,
trace_fout=trace_fout,
trace_format=trace_format,
trace_byteorder=trace_byteorder,
trace_nanosecond=trace_nanosecond)
def extract(
fin=None,
fout=None,
format=None, # basic settings # pylint: disable=redefined-builtin
auto=True,
extension=True,
store=True, # internal settings
files=False,
nofile=False,
verbose=False, # output settings
engine=None,
layer=None,
protocol=None, # extraction settings
ip=False,
ipv4=False,
ipv6=False,
tcp=False,
strict=True, # reassembly settings
trace=False,
trace_fout=None,
trace_format=None, # trace settings # pylint: disable=redefined-outer-name
trace_byteorder=sys.byteorder,
trace_nanosecond=False): # trace settings
"""Extract a PCAP file.
Arguments:
fin (Optiona[str]): file name to be read; if file not exist, raise :exc:`FileNotFound`
fout (Optiona[str]): file name to be written
format (Optional[Literal['plist', 'json', 'tree']]): 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): if print verbose output information
engine (Optional[Literal['default', 'pcapkit', 'dpkt', 'scapy', 'pyshark', 'server', 'pipeline']]):
extraction engine to be used
layer (Optional[Literal['Link', 'Internet', 'Transport', 'Application']]): extract til which layer
protocol (Optional[Union[str, Tuple[str], Type[Protocol]]]): extract til which protocol
ip (bool): if record data for IPv4 & IPv6 reassembly
ipv4 (bool): if perform IPv4 reassembly
ipv6 (bool): if perform IPv6 reassembly
tcp (bool): if perform TCP reassembly
strict (bool): if set strict flag for reassembly
trace (bool): if trace TCP traffic flows
trace_fout (Optional[str]): path name for flow tracer if necessary
trace_format (Optional[Literal['plist', 'json', 'tree', 'pcap']]): output file
format of flow tracer
trace_byteorder (Literal['little', 'big']): output file byte order
trace_nanosecond (bool): output nanosecond-resolution file flag
Returns:
Extractor -- an :class:`~pcapkit.foundation.extraction.Extractor` object
"""
if isinstance(layer, type) and issubclass(layer, Protocol):
layer = layer.__layer__
if isinstance(protocol, type) and issubclass(protocol, Protocol):
protocol = protocol.id()
str_check(fin or '', fout or '', format or '', trace_fout or '',
trace_format or '', engine or '', layer or '', *(protocol or ''))
bool_check(files, nofile, verbose, auto, extension, store, ip, ipv4, ipv6,
tcp, strict, trace)
return Extractor(fin=fin,
fout=fout,
format=format,
store=store,
files=files,
nofile=nofile,
auto=auto,
verbose=verbose,
extension=extension,
engine=engine,
layer=layer,
protocol=protocol,
ip=ip,
ipv4=ipv4,
ipv6=ipv6,
tcp=tcp,
strict=strict,
trace=trace,
trace_fout=trace_fout,
trace_format=trace_format,
trace_byteorder=trace_byteorder,
trace_nanosecond=trace_nanosecond)
