Open source · MIT license

PacketStory

Every packet tells a story. PacketStory turns .pcap and .pcapng captures into a ranked, plain-English troubleshooting report: what is broken, why, and what to do next.

Version 2.1.0October 2026Portable, no installRuns locally

The PacketStory window after analysing sample.pcap. At the top, a drop zone for capture files and a button to add a TLS key log. Below it, a health score of 49 out of 100 and six issues ranked from high to medium, each with an explanation, a suggested next step in green and the TCP flows affected. Under the findings, buttons to export findings and TCP flows as CSV, and capture statistics: 41 packets, 9 TCP flows, 3 UDP flows, 4 retransmissions.
PacketStory 2.1.0 analysing a small sample capture. This is a real screenshot.

How it works

From capture to next step in three moves.

  1. Step 1

    Drop in a capture

    One file or several. PacketStory reads .pcap and .pcapng, on any port and any IP protocol.

  2. Step 2

    Read the score

    You get a health score from 0 to 100 and a list of problems, with the worst at the top.

  3. Step 3

    Follow the lead

    Every problem comes with a suggested next step and the exact connections it affects.

What it checks

The questions you would ask of a capture, answered up front.

TCP health

Handshake failures, refused connections, resets, retransmissions, zero windows, duplicate ACKs, round-trip time and server response time.

TLS insight

SNI, ALPN, TLS 1.3 detection, a missing ServerHello, deprecated versions and alerts. Add an SSLKEYLOGFILE to check decrypted certificates for expiry and name mismatch.

MTU and path problems

MSS-implied MTU, fragmentation-needed messages, detection of path MTU black holes and the distribution of frame sizes.

The protocols underneath

TCP, UDP, DNS over UDP and TCP, DHCP, ICMP and ICMPv6, and ARP, including DNS queries that never got an answer.

Several captures at once

Compare captures taken at different points, or merge them into a single timeline to follow one conversation across the path.

Export

Save the findings and the TCP flow table as CSV, ready for a ticket, a spreadsheet or a change record.

Sample output

What the report says, and what it tells you to do.

These are the six findings from the screenshot above, in PacketStory's own words. The capture is a small synthetic sample.

AreaFindingWhat PacketStory sawSuggested next step
TCPHigh
6 connections refused
SYN was answered with RST: nothing is listening or a firewall is rejecting.Confirm the service is running on that port and check firewall reject rules.
TLSHigh
1 handshake got no ServerHello
The ClientHello was sent but the server never started the handshake.Look for SNI filtering, TLS inspection or an overloaded server.
DNSHigh
1 query unanswered
Resolver is unreachable, filtered or overloaded.Check resolver reachability on UDP/TCP 53 and the configured server addresses.
Packet lossMedium
Retransmissions above 2% in 1 flow
Retransmissions point to packet loss or congestion on the path.Check interface errors and drops, link duplex, congestion and Wi-Fi quality along the path.
MTUMedium
PMTU problem suspected, lower confidence
Full-size DF segments went unacknowledged after a working handshake, but nothing proves that smaller data would have succeeded.Compare with a smaller-MTU or MSS-clamped test; rule out ordinary loss and a stalled peer first.
HTTPMedium
Error responses in 1 flow
The server returned 4xx/5xx status codes.Check the application and server logs for these requests.

Install

Windows: download, extract, run.

  1. DownloadPacketStory-Portable.zip from the latest release.
  2. Extractthe zip anywhere. There is nothing to install.
  3. RunPacketStory\PacketStory.exe
Windows SmartScreenThe build is not code-signed yet, so Windows may show a warning the first time. Choose More info, then Run anyway. If you would rather not, run it from source instead.

Any platform: run from source

Python 3.10 or newer. No third-party packages are required. Installing cryptography is optional and enables TLS decryption.

git clone https://github.com/prawinnetsecdevops-creator/PacketStory.git
cd PacketStory

python app.py                             # desktop window
python analyzer_backend.py                # local web UI at 127.0.0.1:8000
python analyzer_backend.py a.pcap b.pcap  # JSON on the command line

python -m unittest discover -s tests -v   # run the tests
Your captures stay with youPacketStory runs entirely on your own machine. Captures are never uploaded, and the web UI listens on the loopback address only.

Roadmap

What is done, what is next.

  1. Done

    The core analyzer

    • Ranked reports and protocol analysis
    • TLS insight with optional decryption
    • DNS over TLS
    • Multi-file merge
    • Windows portable app
  2. Next

    Easier to share and read

    • Shareable HTML and PDF reports
    • Side-by-side comparison view
    • Clearer connection timelines
  3. Ideas

    Under consideration

    • QUIC, HTTP/3 and HTTP/2
    • RTP voice and video quality
    • Linux and macOS builds
    • Code-signed installer

Known limitations

PacketStory is honest about what it cannot see yet.

  • Decryption covers TLS 1.3 and TLS 1.2 with AEAD cipher suites. CBC suites, KeyUpdate, 0-RTT and QUIC are not supported, and encrypted HTTP/2 is not decoded.
  • Merging captures relies on matching packets between files. De-duplication does not work across a NAT boundary, where addresses and ports change.
  • Large captures need disk space and memory in proportion to their size.
  • Findings are leads, not verdicts. Where the evidence is thin, the report says so, as in the lower-confidence MTU finding above.

Found a capture PacketStory misreads?

Bug reports and ideas are welcome on GitHub. Please share only captures you are authorized to share, with sensitive data removed.