How to build a Python tool that extracts and decrypts TLS sessions from PCAP files
A packet capture can reveal far more than IP addresses and port numbers, but modern TLS encryption means that application data remains unreadable unless the analyst has the right session secrets. A useful Python utility should therefore focus on authorised diagnostics, incident response, and test environments rather than attempting to “crack” encryption.
The practical design is a pipeline: identify conversations in a PCAP or PCAPNG file, reconstruct the relevant TLS records, obtain secrets from a supported key-log source, and export decoded streams for analysis. This approach works for development teams in Sydney, security engineers in Melbourne, and smaller Australian businesses that need a repeatable local troubleshooting tool without sending captures to a third-party service.
Define the decryption boundary
The first design decision is to state what the program can and cannot decrypt. A capture file by itself normally does not contain the keys needed for TLS 1.2 or TLS 1.3. The most reliable source is a client-side NSS key log, commonly produced by Firefox, Chromium-based browsers, curl, or an application configured with SSLKEYLOGFILE.
Older TLS 1.2 sessions using RSA key exchange may sometimes be decrypted with the server’s private key, but that method does not work with ephemeral Diffie–Hellman exchange and is irrelevant to most TLS 1.3 traffic. A responsible tool should report “secrets unavailable” rather than pretending that encrypted payloads can be recovered.
Build around proven packet parsers
Python can orchestrate the workflow while mature packet-analysis engines handle protocol details. tshark is a practical dependency because Wireshark’s dissectors understand TLS handshakes, record boundaries, TCP reassembly, retransmissions, and many malformed-capture conditions. pyshark can invoke it from Python, while scapy is useful when you need custom packet selection or lower-level inspection.
A simple extraction stage might call tshark with fields such as frame number, timestamp, IP addresses, TCP ports, TLS record type, and handshake type. Keep the original capture untouched and write normalised session metadata to JSON. For large captures from an NBN-connected office or a busy data centre, stream records rather than loading every packet into memory.
Compression and preprocessing can influence both speed and correctness. If your input pipeline archives captures or transforms them before parsing, this discussion of early decompression guidance is relevant: decode data at the appropriate stage so the parser receives the format it expects, while preserving a verifiable copy of the source evidence.
Map packets to TLS conversations
A TLS session is usually identified by a five-tuple: source address, destination address, source port, destination port, and transport protocol. That alone is not enough when NAT, reused ports, retries, or multiplexed HTTP/2 connections are involved. Use the TCP stream identifier supplied by tshark where possible, and retain handshake timestamps so separate connections are not accidentally merged.
Your Python model could represent each conversation with fields for client and server endpoints, SNI, negotiated protocol version, cipher suite, ALPN, certificate names, packet count, and byte count. SNI and certificate metadata are useful for triage, but they are not proof of the application identity. A reverse proxy in a Brisbane hosting facility may terminate TLS before forwarding traffic to another internal service.
TCP reassembly deserves careful treatment. Captures taken on a busy switch can contain missing segments, duplicate packets, or traffic observed from only one direction. Mark incomplete streams explicitly, preserve sequence information, and distinguish “no application data” from “application data unavailable because the capture is truncated”.
Load secrets without weakening security
The key-log file should be supplied as an explicit command-line argument or environment variable, never discovered through broad filesystem searches. Parse each line into a label, client random, and secret, ignoring comments and malformed entries. Restrict file permissions and avoid printing secret values in debug logs, especially when a capture is being processed on a shared Linux host.
For TLS 1.2, labels such as CLIENT_RANDOM may be sufficient for supported cipher suites. TLS 1.3 uses separate traffic secrets, including handshake and application traffic keys, and the exact labels depend on the client and server direction. Rather than implementing cryptographic record processing from scratch, pass the capture and key log to a tested engine such as Wireshark’s TLS dissector.
The Python layer can verify that a matching client random or handshake identifier exists before requesting decryption. This produces useful diagnostics: missing key log, wrong key log, unsupported cipher, incomplete handshake, or corrupted capture. Clear status codes are more valuable than a vague “decryption failed” message.
Use a narrow command-line workflow
A clean interface might look like this:
pcap_tls_tool capture.pcapng \
--keys browser.keys \
--stream 42 \
--output decoded/
The program should first list discoverable TLS streams, then allow the operator to select one or more streams for export. Output can include a JSON report, a metadata summary, and a reconstructed payload file where the dissector confirms that application data was decrypted. Avoid naming a file .http unless the decoded protocol is actually identified as HTTP.
For implementation, Python’s subprocess.run() can invoke tshark with a fixed argument list and captured standard error. Do not build shell commands by concatenating filenames or user-supplied display filters. Validate paths, use timeouts, and return non-zero exit codes for missing dependencies or invalid input. These details matter in Australian managed-service environments where tools may run unattended overnight in Sydney or Perth.
Validate against controlled test captures
Create test traffic that your team owns. Run a local HTTPS server, configure a browser or Python client to emit a key log, capture the loopback or test-interface traffic, and compare the recovered payload with the known request and response. Include tests for TLS 1.2, TLS 1.3, certificate rotation, HTTP/2, retransmissions, and a deliberately incomplete PCAP.
Use Wireshark as a reference implementation during development, not as an assumption that every capture is decryptable. Compare stream counts, negotiated versions, and decrypted byte ranges. Add regression fixtures to the project so a change in tshark output or a Python dependency does not silently break analysis.
Handle Australian operational requirements
Capture files can contain passwords, health information, customer records, and internal business data. Treat them as sensitive evidence under the organisation’s privacy policy, apply retention limits, encrypt storage, and record who accessed each file. Australian teams may also need to align the workflow with the Essential Eight, the ISM, contractual controls, or APRA expectations where regulated financial data is involved.
Performance and supportability matter in the local market. A regional council in regional New South Wales may have slower links than a Melbourne data centre, while a security consultancy handling a large incident in Perth may need predictable command-line processing rather than a graphical interface. Ship pinned dependencies, document Linux package requirements, include Australian Eastern and Western time-zone handling in reports, and keep secrets out of logs.
The finished utility should make its limits visible: it extracts identifiable TLS conversations, decrypts sessions only when authorised key material is available, and preserves enough metadata for another analyst to reproduce the result. That balance makes the tool useful for debugging, forensics, and open-source development without turning it into a mechanism for bypassing TLS protection.
