Pulsemap

Visualizes IP packet flows in real time as animated dots on a D3.js force-directed graph. Supports .pcap replay and live capture. Includes connection analytics, anomaly detection, TCP stream viewer, GeoIP map, and more.

Requirements

• Python 3.9+
• Windows: Npcap installed in WinPcap-compatible mode (required for live capture)
• Linux/macOS: libpcap (usually pre-installed)

Install

pip install -r requirements.txt

GeoIP

GeoIP resolution is included automatically via the geoip2fast package (bundled database, no account or download required). Click 🌍 Geo to toggle the world map panel — external IPs are plotted as dots as they appear in traffic.

Run

python main.py           # default port 5000
python main.py --port 8080

The browser opens automatically. If it doesn't, navigate to http://127.0.0.1:5000.

Features

PCAP replay

1. Paste the absolute path to a .pcap file in the PCAP field and click Load, or drag & drop a file onto the graph area, or use Browse… to pick a file.
2. Click ▶ (or press Space) to start replay. Autoplay begins immediately.
3. Use the Speed slider (0.5×–10×) to change playback rate.
4. The Sparkline above the timeline shows the PPS shape across the capture — useful for finding bursts before you seek into them.
5. Drag the Timeline scrubber to jump to any point. Use ← → arrow keys to step one packet at a time.

Live capture

1. Select your network interface from the dropdown (auto-populated on connect).
2. Click Sniff to start. Click Stop to end.

Flows (connection table)

Click ⇄ Flows to open a sortable table of all observed connections — source, destination, protocols, packet count, bytes, first/last seen, duration. Click any row to open the inspector for that flow. Click ↓ Export PCAP to download a filtered .pcap of the current view.

TCP Stream Viewer

Click any TCP link in the graph (or the View button in the Flows table) to open the raw TCP stream. Toggle direction (A→B / B→A / Both) and format (Text / Hex). Large streams load in chunks.

Anomaly detection

The app continuously watches for:

• Port scan — one source reaching ≥15 distinct dst:port pairs within 5 s
• SYN flood — ≥100 SYN-only TCP packets per second from one source
• PPS spike — a single src→dst pair exceeding 500 pps
• ICMP burst — ≥50 ICMP packets per second from one source

When an anomaly fires, the offending node pulses red and the event is logged in the 🔔 Alerts panel. Click any alert to open the inspector for that IP.

GeoIP map

Click 🌍 Geo to toggle a world map panel. External IPs are plotted as blue dots after being resolved.

Node pinning

Click a node to open the inspector, then click the 📌 button to pin it in place. The force simulation will no longer move it. Click 📌 again to unpin.

Filtering

• Type an IP fragment in the Filter box to fade non-matching nodes.
• Use the protocol dropdown to focus on TCP / UDP / ICMP / OTHER.
• Press Esc to clear the filter and close the inspector.

Keyboard shortcuts

Key	Action
Space	Play / Pause
← →	Step one packet
+ −	Speed up / down
F	Fit graph to screen
Esc	Close inspector, clear filter
/	Focus IP filter input
?	Show shortcut help

Protocol colors

Color	Protocol
Cyan #22d3ee	TCP
Orange #fb923c	UDP
Red #ef4444	ICMP
Gray #94a3b8	OTHER

Project structure

main.py              Flask + SocketIO server, replay loop, DNS + GeoIP workers
parser.py            scapy pcap streaming parser, PPS bucket computation
extractor.py         HTTP object extraction + TCP stream reassembly
geoip.py             geoip2fast lookup helper (bundled database)
templates/index.html D3 v7 frontend (single file, all features inline)
requirements.txt     Python dependencies

Windows notes

• Live capture requires Npcap. During install, check "Install Npcap in WinPcap API-compatible Mode".
• Run the terminal as Administrator for live capture if you get permission errors.
• The interface dropdown shows friendly adapter names. The first detected interface is pre-selected at startup.

Sample pcap files

Wireshark sample captures are a good source of test data.