Skip to content
Tutorials Center
My learning

Topics

Lesson 36 of 37 ยท Projects and Practice

Project: Build a TCP Health Report Tool

Build a small analysis tool that reads packet records, groups them by TCP stream, finds retransmissions, resets and slow handshakes, and prints a ranked health report.

Wireshark finds problems in one connection at a time. When you manage a server with thousands of connections, you want a report that ranks the worst streams automatically. In this project you will build such a tool in Python, step by step, on sample packet records, then see how to feed it real data from tshark.

The code runs here on invented records. Everything the tool needs (stream id, time, sequence numbers, flags) is available from tshark with -T fields.

The plan

Tool outline

Read Packet records.
Group By TCP stream.
1 / 2

Step 1: the data

Each record is a dictionary. In real use you would produce them with:

Terminal
tshark -r capture.pcapng -T fields -E separator=, \
  -e tcp.stream -e frame.time_relative -e ip.src -e tcp.seq -e tcp.len \
  -e tcp.flags.syn -e tcp.flags.ack -e tcp.flags.reset

Here we use a small list instead.

Python Step 1 and 2: parse and group

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Step 3: metrics per stream

Define what "unhealthy" means:

  • Retransmissions: the same source sends the same sequence number twice with data (tcp.len > 0).
  • Resets: any packet with RST.
  • SYN retries: more than one SYN from the client (a handshake that struggles).
  • Handshake RTT: time from the first SYN to the SYN-ACK.
Python Step 3: compute the metrics

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Step 4: score and rank

A score combines the metrics with weights. The weights are a judgment call: resets and failed handshakes are worse than a single retransmission.

Python Step 4: score and print the report

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Step 5: next steps

  • Run it on real tshark output (pipe -T fields into the script) and compare with the Expert Information window to validate it.
  • Add handshake RTT percentiles and a per-server summary.
  • Output CSV or HTML for a dashboard, and run it from a scheduled job on each hourly capture file from a ring buffer.
  • Add sequence-wrap and out-of-order handling: a simple "same sequence seen twice" rule misclassifies keep-alives and zero-window probes, so exclude packets with length 0 or one byte.
  • Write tests: build tiny record lists for each case (clean, SYN retries, reset, retransmission) and assert the metrics.

Your tool is a filter for attention, not a replacement for Wireshark. Use its ranking to decide which streams to open and examine, as in Slow Networks and TCP Retransmissions.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. How does the tool detect a retransmission?

    Resending data under an existing sequence number is the signature of a retransmission.
  2. 2. Why exclude zero-length packets from the retransmission check?

    Pure ACKs, keep-alives and probes repeat sequence numbers without being data retransmissions.
  3. 3. Which tshark option prints the stream index used for grouping?

    tcp.stream numbers each connection, which makes grouping packets simple.
  4. 4. What is the role of the scoring weights?

    Weights are a tunable heuristic for ranking which streams to look at first.

Summary

  • Parse packets, group by stream, compute metrics, score, and rank.
  • Retransmissions, resets, SYN retries and handshake RTT are the core signals.
  • Scripted reports point you at the streams worth opening in Wireshark.
  • Test your tool on small, hand-built cases before trusting it on big files.

Next: Practice: Filter and Analysis Challenges