Script pcap_layer_analysis.py

The script pcap_layer_analysis.py analyzes a PCAP/PCAPNG file containing TCP, TLS, and HTTP traffic to measure how long each communication phase takes for every connection and to calculate aggregated statistics.

How it works

1. It reads the SSLKEYLOGFILE environment variable.
   • It must point to a valid TLS key log file.
   • This is used so Wireshark/TShark/PyShark can decrypt TLS traffic.
2. It opens the PCAP with pyshark using the display filter http or tls or tcp.
3. It splits the original capture into multiple temporary PCAP files grouped by tcp.stream.
   • This split is performed with tshark.
   • The goal is to process the analysis in parallel and reduce total execution time.
4. It processes each subset of streams in parallel with multiprocessing.
5. For each TCP stream, it detects these timing phases:
   • TCP: from the SYN packet to SYN-ACK.
   • TCP delay: from SYN-ACK to the TLS ClientHello.
   • TLS: from ClientHello to TLS Finished.
   • TLS delay: from Finished to the HTTP GET request.
   • APP: from the HTTP GET request to the HTTP 200 OK response.
   • Total: the sum of all phases above.
6. It converts all timings to milliseconds and prints aggregated statistics.
7. It removes the temporary files generated during preprocessing.

Input parameters

The script does not use named CLI options. It only requires these inputs:

• Required environment variable: SSLKEYLOGFILE
  • Path to the TLS key log file.
  • If it does not exist or does not point to a valid file, the script exits with an error.
• Required positional argument: <file.pcap>
  • Path to the PCAP/PCAPNG file to analyze.

Example usage:

SSLKEYLOGFILE=/ruta/al/sslkeys.log python3 pcap_layer_analysis.py captura.pcap

Output

The output is written to the console through logging.

Informational messages

During execution, the script prints information such as:

• Number of streams used per temporary file.
• Temporary working directory.
• Number of files generated after splitting.
• Number of parallel workers used.
• Total number of TCP connections analyzed.

Final statistics

At the end, it prints a block of statistics in milliseconds for these categories:

• TCP
• TCP_delay
• TLS
• TLS_delay
• APP
• TOT

For each category, the output includes:

• total samples, except for TOT
• mean
• median, except for TOT
• p90
• p95
• p99
• max
• min
• std

For TOT, the script prints only:

• mean
• std

Quick summary

• Required input: SSLKEYLOGFILE + PCAP path.
• Processes TCP streams in parallel.
• Measures TCP handshake, TLS handshake, transition to application traffic, and HTTP response timings.
• Returns aggregated statistics in the console; it does not generate an output file.

License

This project is distributed under the GNU General Public License v3.0.

See LICENSE for the full license text.