1import json
2import subprocess
3from pathlib import Path
4from hashlib import file_digest
5from functools import cached_property
6from dataclasses import dataclass
7from collections.abc import Sequence, Mapping
8from typing import Any
9
10from .types import DictPacket, DictLayers
11
12
[docs]
13@dataclass(frozen=True)
14class TsharkOutput:
15 """Output of tshark network traffic dump, together with some metadata of about it."""
16
17 list_packets: Sequence[DictPacket]
18 metadata: Mapping[str, Any]
19
20 def __post_init__(self) -> None:
21 assert isinstance(self.list_packets, Sequence), type(self.list_packets)
22
23 @property
24 def list_layers(self) -> Sequence[DictLayers]:
25 """Extract layers: for each packet, it extracts the layers from the `_source` key."""
26 return [
27 packet['_source']['layers'] for packet in self.list_packets
28 ]
29
30
[docs]
31@dataclass(frozen=True)
32class Tshark:
33 """
34 A class to interact with tshark for loading and parsing network traffic data from a PCAPNG file.
35
36 **tshark** is a command-line tool for capturing and analyzing network traffic.
37 It is part of the Wireshark suite and provides similar functionality to the Wireshark GUI in a terminal environment.
38
39 - Packet capture and analysis: `tshark` can capture live network traffic and analyze packets from capture files (e.g., PCAP, PCAPNG).
40 - Protocol decoding: It supports decoding a wide range of network protocols, providing detailed information about each packet.
41 - Filtering: `tshark` allows filtering packets using display filters to focus on specific traffic.
42 - Statistics: It can generate various statistics about the captured traffic, such as protocol hierarchy, endpoint statistics, and conversation lists.
43 - Exporting data: `tshark` can export packet data to different formats, including JSON, CSV, and plain text.
44 - Decryption: `tshark` supports decryption of encrypted traffic using SSL/TLS keys provided in an SSLKEYLOG file.
45
46 `tshark` can convert PCAPNG files to JSON format using the `-T json` option.
47 This allows for easy parsing and analysis of network traffic data in a structured format.
48
49 **Useful commands**:
50
51 - Capture live traffic: `tshark -i <interface>`
52 - Read from a PCAP file: `tshark -r <file.[pcap|pcapng]>`
53 - Display packet details: `tshark -V`
54 - Filter packets: `tshark -Y <filter>`
55 - Export to JSON: `tshark -r <file.[pcap|pcapng]> -T json`
56 - Decrypt SSL/TLS traffic: `tshark -r <file.[pcap|pcapng]> -o "ssl.keys_list: <key_file>"`
57 - Inject the TLS secrets: `editcap --inject-secrets tls,<keylog_file> <file.pcap> <output.pcapng>`
58
59 Attributes:
60 tshark_cmd (str): The path to the tshark executable.
61 """
62 tshark_cmd: str = 'tshark'
63 hash_algo: str = 'sha1'
64
[docs]
65 @cached_property
66 def version(self) -> str:
67 proc = subprocess.run([self.tshark_cmd, '--version'], text=True, stdout=subprocess.PIPE, stderr=subprocess.PIPE)
68 if proc.returncode != 0:
69 raise RuntimeError(proc.stderr)
70 version_first_line = proc.stdout.splitlines()[0].strip()
71 return version_first_line.removeprefix('TShark (Wireshark) ').removesuffix('.')
72
[docs]
73 def load_traffic(self, pcapng_file: Path) -> TsharkOutput:
74 """
75 Loads network traffic data from the provided pcapng file using tshark.
76
77 This method runs the tshark command to read the pcapng file and parse the output as JSON.
78 The parsed traffic data is then returned, together with some metadata.
79
80 Raises:
81 subprocess.CalledProcessError: If the tshark command fails.
82
83 Note that no HTTP3 traffic is expected since it is rejected by Pirogue.
84 """
85 with pcapng_file.open('rb') as fp:
86 metadata = {
87 'tshark_version': self.version,
88 f'input_{self.hash_algo}': file_digest(fp, self.hash_algo).hexdigest(),
89 }
90 cmd = [
91 self.tshark_cmd,
92 '-2', # two passes
93 '-r', pcapng_file.as_posix(),
94 '-x', # output raw fields as well
95 '-T', 'json',
96 '-NdnN', # name resolution
97 '--no-duplicate-keys', # merge json keys
98 '-Y', 'http || http2', # display filters
99 '-J', 'frame ip ipv6 tcp http http2', # do not export data of useless layers
100 '--enable-protocol', 'communityid',
101 ]
102 proc = subprocess.run(cmd, stdout=subprocess.PIPE, stderr=subprocess.PIPE)
103 if proc.returncode != 0:
104 raise RuntimeError(proc.stderr.decode())
105 list_packets = json.loads(proc.stdout)
106 return TsharkOutput(list_packets, metadata)