pcapng_utils.tshark package

Subpackages

Submodules

pcapng_utils.tshark.traffic module

class pcapng_utils.tshark.traffic.NetworkTrafficDump(tshark_output)[source]

Bases: object

The NetworkTrafficDump class is designed to handle and process network traffic data.

creation_metadata

Some metadata of input file to export in HAR creator comment

Type:

dict

traffic

A list of dictionaries containing traffic data.

Type:

list[dict]

parsed_traffic

Mapping of parsed traffic per protocol class (e.g. Http1Traffic, Http2Traffic)

Type:

dict[class, instance]

parse_traffic()[source]

Parse the HTTP1 and HTTP2 network traffic.

to_har()[source]

Convert the network traffic data to HTTP Archive (HAR) format.

Returns:

the network traffic data in HAR format

Return type:

dict[str, Any]

pcapng_utils.tshark.types module

class pcapng_utils.tshark.types.HasLayers(*args, **kwargs)[source]

Bases: Protocol

property layers: Mapping[str, Any]
class pcapng_utils.tshark.types.ParsedTrafficProtocol(traffic)[source]

Bases: Protocol

get_har_entries()[source]
Return type:

list[dict[str, Any]]

pcapng_utils.tshark.utils module

pcapng_utils.tshark.utils.get_tshark_bytes_from_raw(r)[source]

Format of ‘*_raw’ fields produced with ‘-x’ flag: [hexa: str, *sizes: int]

Sizes are 4 integers in tshark old versions and 5 integers in newer (>= v4.6)

Return type:

bytes

pcapng_utils.tshark.utils.har_entry_with_common_fields(har_entry)[source]

Return provided HAR entry together with common fields.

In particular, we add the non-standard _sha1Id field that serves both as entry identifier + easy changes-tracker across different releases of this software.

Return type:

dict[str, Any]

pcapng_utils.tshark.wrapper module

class pcapng_utils.tshark.wrapper.Tshark(tshark_cmd='/usr/bin/tshark', *, hash_algo='sha1', name_resolution='nds', hosts_file=PosixPath('/etc/hosts'), display_filter='http || http2 || websocket', protocol_match_filter='http http2 websocket', tcp_reassemble_out_of_order=True, timeout=60.0)[source]

Bases: object

A class to interact with tshark for loading and parsing network traffic data from a PCAPNG file.

tshark is a command-line tool for capturing and analyzing network traffic. It is part of the Wireshark suite and provides similar functionality to the Wireshark GUI in a terminal environment.

  • Packet capture and analysis: tshark can capture live network traffic and analyze packets from capture files (e.g., PCAP, PCAPNG).

  • Protocol decoding: It supports decoding a wide range of network protocols, providing detailed information about each packet.

  • Filtering: tshark allows filtering packets using display filters to focus on specific traffic.

  • Statistics: It can generate various statistics about the captured traffic, such as protocol hierarchy,

endpoint statistics, and conversation lists. - Exporting data: tshark can export packet data to different formats, including JSON, CSV, and plain text. - Decryption: tshark supports decryption of encrypted traffic using SSL/TLS keys provided in an SSLKEYLOG file.

tshark can convert PCAPNG files to JSON format using the -T json option. This allows for easy parsing and analysis of network traffic data in a structured format.

Useful commands:

  • Capture live traffic: tshark -i <interface>

  • Read from a PCAP file: tshark -r <file.[pcap|pcapng]>

  • Display packet details: tshark -V

  • Filter packets: tshark -Y <filter>

  • Export to JSON: tshark -r <file.[pcap|pcapng]> -T json

  • Decrypt SSL/TLS traffic: tshark -r <file.[pcap|pcapng]> -o “ssl.keys_list: <key_file>”

  • Inject the TLS secrets: editcap –inject-secrets tls,<keylog_file> <file.pcap> <output.pcapng>

get_command(pcapng_file)[source]

Get full command to be executed

Return type:

list[str]

load_traffic(pcapng_file)[source]

Loads network traffic data from the provided pcapng file using tshark.

This method runs the tshark command to read the pcapng file and parse the output as JSON. The parsed traffic data is then returned, together with some metadata.

Raises:

subprocess.CalledProcessError – If the tshark command fails.

Return type:

TsharkOutput

Note that no HTTP3 traffic is expected since it is rejected by Pirogue.

display_filter: Annotated[str, _ArgConfig(name=None, metavar=None, help=None, help_behavior_hint=None, aliases='-Y', prefix_name=None, constructor_factory=None, default=tyro.MISSING_NONPROP)] = 'http || http2 || websocket'

Display filter (documented in tshark manual under -Y flag)

hash_algo: Annotated[str, _ArgConfig(name=None, metavar=ALGO, help=None, help_behavior_hint=None, aliases=None, prefix_name=None, constructor_factory=None, default=tyro.MISSING_NONPROP)] = 'sha1'

Hash algorithm to generate digest of input .pcapng

hosts_file: Path | None = PosixPath('/etc/hosts')

Hosts file for tshark name resolution - only used when name resolution contains’n’

property less_than_v4_4: bool[source]
name_resolution: Annotated[Literal[False] | str, _ArgConfig(name=None, metavar=FLAGS | False, help=None, help_behavior_hint=None, aliases=None, prefix_name=None, constructor_factory=None, default=tyro.MISSING_NONPROP)] = 'nds'

Name resolution flags, as documented in tshark manual under -N flag; by default we avoid using any external DNS resolver

protocol_match_filter: Annotated[str, _ArgConfig(name=None, metavar=None, help=None, help_behavior_hint=None, aliases='-J', prefix_name=None, constructor_factory=None, default=tyro.MISSING_NONPROP)] = 'http http2 websocket'

Protocol match filter (documented in tshark manual under -J flag), in addition to base protocols

tcp_reassemble_out_of_order: bool = True

Whether to allow or not to reassemble out-of-order TCP segments

timeout: Annotated[float, _ArgConfig(name=None, metavar=SECONDS, help=None, help_behavior_hint=None, aliases=None, prefix_name=None, constructor_factory=None, default=tyro.MISSING_NONPROP)] = 60.0

Timeout in seconds for tshark command completion

tshark_cmd: Annotated[str, _ArgConfig(name=tshark, metavar=CMD, help=None, help_behavior_hint=None, aliases='-c', prefix_name=None, constructor_factory=None, default=tyro.MISSING_NONPROP)] = '/usr/bin/tshark'

Path/command for tshark executable

property version: str[source]
class pcapng_utils.tshark.wrapper.TsharkOutput(list_packets, metadata)[source]

Bases: object

Output of tshark network traffic dump, together with some metadata of about it.

property list_layers: Sequence[Mapping[str, Any]]

for each packet, it extracts the layers from the _source key.

Type:

Extract layers

list_packets: Sequence[Mapping[str, Any]]
metadata: Mapping[str, Any]
pcapng_utils.tshark.wrapper.cli_dump_tshark_layers_as_json()[source]

Standard output may be redirected to a .json to inspect tshark intermediate output

Module contents

class pcapng_utils.tshark.NetworkTrafficDump(tshark_output)[source]

Bases: object

The NetworkTrafficDump class is designed to handle and process network traffic data.

creation_metadata

Some metadata of input file to export in HAR creator comment

Type:

dict

traffic

A list of dictionaries containing traffic data.

Type:

list[dict]

parsed_traffic

Mapping of parsed traffic per protocol class (e.g. Http1Traffic, Http2Traffic)

Type:

dict[class, instance]

parse_traffic()[source]

Parse the HTTP1 and HTTP2 network traffic.

to_har()[source]

Convert the network traffic data to HTTP Archive (HAR) format.

Returns:

the network traffic data in HAR format

Return type:

dict[str, Any]

class pcapng_utils.tshark.Tshark(tshark_cmd='/usr/bin/tshark', *, hash_algo='sha1', name_resolution='nds', hosts_file=PosixPath('/etc/hosts'), display_filter='http || http2 || websocket', protocol_match_filter='http http2 websocket', tcp_reassemble_out_of_order=True, timeout=60.0)[source]

Bases: object

A class to interact with tshark for loading and parsing network traffic data from a PCAPNG file.

tshark is a command-line tool for capturing and analyzing network traffic. It is part of the Wireshark suite and provides similar functionality to the Wireshark GUI in a terminal environment.

  • Packet capture and analysis: tshark can capture live network traffic and analyze packets from capture files (e.g., PCAP, PCAPNG).

  • Protocol decoding: It supports decoding a wide range of network protocols, providing detailed information about each packet.

  • Filtering: tshark allows filtering packets using display filters to focus on specific traffic.

  • Statistics: It can generate various statistics about the captured traffic, such as protocol hierarchy,

endpoint statistics, and conversation lists. - Exporting data: tshark can export packet data to different formats, including JSON, CSV, and plain text. - Decryption: tshark supports decryption of encrypted traffic using SSL/TLS keys provided in an SSLKEYLOG file.

tshark can convert PCAPNG files to JSON format using the -T json option. This allows for easy parsing and analysis of network traffic data in a structured format.

Useful commands:

  • Capture live traffic: tshark -i <interface>

  • Read from a PCAP file: tshark -r <file.[pcap|pcapng]>

  • Display packet details: tshark -V

  • Filter packets: tshark -Y <filter>

  • Export to JSON: tshark -r <file.[pcap|pcapng]> -T json

  • Decrypt SSL/TLS traffic: tshark -r <file.[pcap|pcapng]> -o “ssl.keys_list: <key_file>”

  • Inject the TLS secrets: editcap –inject-secrets tls,<keylog_file> <file.pcap> <output.pcapng>

get_command(pcapng_file)[source]

Get full command to be executed

Return type:

list[str]

load_traffic(pcapng_file)[source]

Loads network traffic data from the provided pcapng file using tshark.

This method runs the tshark command to read the pcapng file and parse the output as JSON. The parsed traffic data is then returned, together with some metadata.

Raises:

subprocess.CalledProcessError – If the tshark command fails.

Return type:

TsharkOutput

Note that no HTTP3 traffic is expected since it is rejected by Pirogue.

display_filter: Annotated[str, _ArgConfig(name=None, metavar=None, help=None, help_behavior_hint=None, aliases='-Y', prefix_name=None, constructor_factory=None, default=tyro.MISSING_NONPROP)] = 'http || http2 || websocket'

Display filter (documented in tshark manual under -Y flag)

hash_algo: Annotated[str, _ArgConfig(name=None, metavar=ALGO, help=None, help_behavior_hint=None, aliases=None, prefix_name=None, constructor_factory=None, default=tyro.MISSING_NONPROP)] = 'sha1'

Hash algorithm to generate digest of input .pcapng

hosts_file: Path | None = PosixPath('/etc/hosts')

Hosts file for tshark name resolution - only used when name resolution contains’n’

property less_than_v4_4: bool[source]
name_resolution: Annotated[Literal[False] | str, _ArgConfig(name=None, metavar=FLAGS | False, help=None, help_behavior_hint=None, aliases=None, prefix_name=None, constructor_factory=None, default=tyro.MISSING_NONPROP)] = 'nds'

Name resolution flags, as documented in tshark manual under -N flag; by default we avoid using any external DNS resolver

protocol_match_filter: Annotated[str, _ArgConfig(name=None, metavar=None, help=None, help_behavior_hint=None, aliases='-J', prefix_name=None, constructor_factory=None, default=tyro.MISSING_NONPROP)] = 'http http2 websocket'

Protocol match filter (documented in tshark manual under -J flag), in addition to base protocols

tcp_reassemble_out_of_order: bool = True

Whether to allow or not to reassemble out-of-order TCP segments

timeout: Annotated[float, _ArgConfig(name=None, metavar=SECONDS, help=None, help_behavior_hint=None, aliases=None, prefix_name=None, constructor_factory=None, default=tyro.MISSING_NONPROP)] = 60.0

Timeout in seconds for tshark command completion

tshark_cmd: Annotated[str, _ArgConfig(name=tshark, metavar=CMD, help=None, help_behavior_hint=None, aliases='-c', prefix_name=None, constructor_factory=None, default=tyro.MISSING_NONPROP)] = '/usr/bin/tshark'

Path/command for tshark executable

property version: str[source]