Skip to content

NetTrace_TODO.md

Latest commit

 

History

History
178 lines (147 loc) · 5.1 KB

NetTrace_TODO.md

File metadata and controls

178 lines (147 loc) · 5.1 KB
Raw

🧭 TODO.md – Network Traffic Analyzer 2.0 (Real-Time FastAPI Version)

🏁 Project Goal

Transform the old .pcap → KML packet analyzer into a real-time, full-stack web app that:

  • Captures packets live from your network.
  • Maps traffic globally on an interactive world map.
  • Shows protocol distribution, live packet stats, and analytics.
  • Runs fully in-browser (no manual KML downloads).

⚙️ Core Improvements

1️⃣ Replace .pcap file dependency with live capture

  • Use Scapy for real-time packet sniffing.
  • Capture key details: source IP, destination IP, protocol.
  • Add optional fallback to .pcap upload for demo/testing.

2️⃣ Integrate GeoIP lookup

  • Replace old pygeoip (deprecated) with geoip2 (MaxMind).
  • Cache lookups to reduce latency.
  • Return coordinates + country codes for frontend visualization.

3️⃣ Build FastAPI backend

  • Create FastAPI app with the following endpoints:
    • GET / → serve frontend page.
    • GET /protocol_stats → returns live packet protocol counts.
    • GET /clear_stats → reset all stats.
    • WebSocket /ws → stream live packet data.
  • Structure backend using modules: 
    /backend
  ├── main.py
  ├── capture.py
  ├── geoip_utils.py
  ├── models.py
  └── static/
  • Maintain in-memory counters for protocol types.
  • Emit structured JSON via WebSocket for frontend.

4️⃣ Create frontend (map + dashboard)

  • Use Leaflet.js + OpenStreetMap (no API key needed).
  • Add WebSocket client to receive live packets: 
    {
  "src_ip": "8.8.8.8",
  "dst_ip": "192.168.1.10",
  "src_coords": {"lat": 37.386, "lon": -122.0838, "country": "US"},
  "dst_coords": {"lat": 28.6139, "lon": 77.2090, "country": "IN"},
  "protocol": 6
}
  • Plot:
    • Colored lines between source → destination.
    • Small markers for each endpoint.
    • Heatmap based on destination density.
  • Sidebar elements:
    • Live protocol counters.
    • Toggle filters for TCP / UDP / ICMP / Other.
    • Simple packet activity graph.

🎨 Frontend UI Design Goals

Element Description
🌍 Map Leaflet map covering full viewport; dark theme tiles.
📊 Sidebar Vertical right-side panel showing protocol counts & filters.
🕹 Controls Checkbox filters for TCP / UDP / ICMP.
🔥 Heatmap Toggle Button to switch between markers/heatmap view.
⏱ Live Packet Rate Mini line chart showing packets per second.
🧹 Reset Button Clear all markers and counters.

Example layout:

 -----------------------------------------------------
|                Leaflet Map (70%)                    |
|-----------------------------------------------------|
| Sidebar (30%) - Stats, Filters, Graphs              |
 -----------------------------------------------------

💡 Additional Features (Optional Enhancements)

  • Export current view as image or .json snapshot.
  • Store live session logs (IP, protocol, timestamp) in SQLite.
  • Show ISP / city names next to markers.
  • Dark mode toggle.
  • Display connection count by country on hover.
  • Visual “pulse” effect on newly received packets.

🧠 Tech Stack

Layer Tool
Backend FastAPI
Packet Capture Scapy
Geo Lookup GeoIP2 (MaxMind)
Frontend Map Leaflet.js + leaflet.heat
Charts Chart.js / Plotly.js
Real-time WebSockets (FastAPI built-in)

🧩 API Contract (Backend → Frontend)

WebSocket: /ws
→ Streams JSON packets in real time.

{
  "src_ip": "49.37.250.148",
  "dst_ip": "142.250.183.78",
  "protocol": 6,
  "src_coords": {"lat": 28.6139, "lon": 77.2090, "country": "IN"},
  "dst_coords": {"lat": 37.422, "lon": -122.084, "country": "US"}
}

GET /protocol_stats →
Returns summarized counts.

{
  "TCP": 145,
  "UDP": 82,
  "ICMP": 11,
  "Other": 5
}

🧰 Setup / Run

  1. Create virtual environment 
    python -m venv env
source env/bin/activate
  2. Install dependencies 
    pip install fastapi uvicorn scapy geoip2 python-multipart
  3. Run server 
    uvicorn main:app --reload
  4. Open browser 
    http://localhost:8000

📅 MVP Milestones

Step Description Status
🧩 Setup FastAPI app structure Backend skeleton with WebSocket ☐
🌍 Add live Scapy packet sniffer Stream packets via WebSocket ☐
🧭 Integrate GeoIP lookup Add country/lat/lon ☐
🗺 Build Leaflet frontend Display markers and lines ☐
🔢 Add protocol stats and filters Sidebar and WebSocket updates ☐
🔥 Heatmap + animation effects Enhance visualization ☐
🧹 Cleanup & Documentation Final README and screenshots ☐

💬 Next Steps

Once backend MVP is ready:

  • Generate the frontend UI in HTML/JS/CSS using Leaflet + Chart.js, based on this structure and API contract.