Packet Story — Network Traffic Analysis & Threat Detection

A web-based network traffic analyzer that parses .pcap capture files, reconstructs conversations between hosts, detects security-relevant events, and flags potential threats — all presented through an interactive dashboard.

Built from scratch with Python, Scapy, and FastAPI as a hands-on project to understand how network security monitoring tools work under the hood.

What it does

Packet Story takes a raw packet capture and turns it into a readable security story:

• Packet parsing — reads .pcap files with Scapy and extracts key fields (IPs, ports, protocol, size, flags, timestamps) from each packet.
• Flow reconstruction — groups individual packets into conversations (flows) using a direction-independent 4-tuple key, so a request and its response are recognized as one exchange.
• Event detection — automatically identifies TCP three-way handshakes and DNS queries, labeling what actually happened on the wire.
• Threat detection — flags port-scanning behavior (one source probing many different ports), connections to high-risk ports (Telnet, RDP, SMB, exposed databases), and assigns a risk score to every flow.
• Interactive dashboard — protocol distribution, traffic-over-time timeline, top talkers, detected events, security alerts, and a per-flow risk table.
• File upload — analyze any .pcap file directly from the browser.

Screenshots

Architecture

The project is split into focused modules, each with a single responsibility:

.pcap file
   |
   v
parser.py      ->  reads packets, extracts fields into clean data
   |
   v
flows.py       ->  groups packets into conversations + risk scoring
   |
   v
events.py      ->  detects TCP handshakes and DNS queries
   |
   v
threats.py     ->  port-scan detection, risky-port detection
   |
   v
main.py        ->  FastAPI backend, serves analysis as JSON
   |
   v
dashboard.html ->  fetches JSON, renders charts and tables (Chart.js)

Tech stack

• Python — core language
• Scapy — packet parsing and live capture
• FastAPI + Uvicorn — backend API
• Chart.js — dashboard visualizations
• Npcap — live traffic capture on Windows

Getting started

Requirements

• Python 3.x
• (Optional, for live capture) Npcap on Windows

Installation

# clone the repository
git clone https://github.com/batikanavsar000/packet-story.git
cd packet-story

# create and activate a virtual environment
python -m venv venv
# Windows:
venv\Scripts\activate
# macOS/Linux:
source venv/bin/activate

# install dependencies
python -m pip install -r requirements.txt

Run

python -m uvicorn main:app --reload

Then open http://127.0.0.1:8000 in your browser and upload a .pcap file.

Capture your own traffic (optional)

# run as administrator (required for packet capture)
python capture.py

This captures 200 packets (or 30 seconds) of live traffic and saves it as capture.pcap, which you can then upload to the dashboard.

What I learned

This project was my first end-to-end full-stack build. Along the way I learned:

• Network fundamentals in practice — seeing the TCP three-way handshake (SYN -> SYN-ACK -> ACK), DNS resolution, and TLS connections in real captured traffic, not just in theory.
• How packets are layered — Ethernet -> IP -> TCP/UDP, and how to navigate those layers in code.
• Flow analysis — why a request and its response belong to the same conversation, and how to key them together regardless of direction.
• Security detection logic — how a port scan looks in traffic (one host probing many ports) and how intrusion detection systems reason about anomalies.
• Backend/frontend separation — the backend prepares data and serves it as JSON; the frontend fetches and renders it. GET vs POST, file uploads with FormData.
• Handling real-world data — test data is clean, but real traffic is messy (unexpected packet types, IPv6, malformed packets). I learned to write defensive code that doesn't crash on the unexpected — a core skill in security engineering.
• Refactoring — extracting shared logic into reusable functions instead of duplicating code.

Roadmap

Planned improvements as this project grows toward a full security monitoring platform:

• TLS SNI extraction (see which sites HTTPS connections go to)
• Machine-learning-based anomaly detection
• Threat-intelligence lookups (known-bad IPs and domains)
• Database storage for historical analysis
• Containerization with Docker
• CI/CD pipeline with automated security scanning

Author

Batikan Avsar — Computer Engineering student focused on the intersection of cybersecurity, DevOps, AI, and cloud (MLSecOps).

• GitHub: batikanavsar000