⚡ NetSpy — Real-time Network Packet Sniffer/Analyzer

A terminal-based, real-time network packet sniffer and analyzer for Windows, built with Python. This project was built with the idea of how vibecoding can be used to make any kind of tool or to automate your work.

┌──────────────────────────────── ⚡ NetSpy ───────────────────────────────────┐
│  stats │ Packets: 1,234  │ Total: 2.3 MB  │ Speed: 48.2 KB/s  │ Graph: ▅▆▇█│
├──────────────────────┬───────────────────────────────────────────────────────┤
│  📡 Packet Log       │  🔗 Top Connections                                  │
│  12:34:01 DNS  →     │  TCP  192.168.1.5:443  → 142.250.x.x  HTTPS           │
│  12:34:01 TCP  →     │  UDP  192.168.1.5:53   → 8.8.8.8      DNS             │
│  12:34:02 HTTP →     ├───────────────────────────────────────────────────────┤
│  ...                 │  📊 Protocols   🌐 DNS Queries   ⚠ Alerts            │
└──────────────────────┴───────────────────────────────────────────────────────┘

---

Features

• Live packet capture — real-time display updated 4x/second
• Protocol detection — TCP, UDP, ICMP, ARP, DNS, HTTP, HTTPS, SSH, RDP, and 30+ named services
• Bandwidth graph — sparkline showing per-second throughput
• Top connections — ranked by bytes transferred
• Protocol distribution — bar chart with percentages
• DNS query log — live feed of DNS lookups and responses
• Basic alerts — suspicious port access & port scan detection
• PCAP export — save captures to .pcap for Wireshark
• Themes — dark, hacker, light
• BPF filters — filter by protocol, IP, or port

---

Requirements

• Windows 10/11 (or Windows Server)
• Python 3.8+
• Npcap — must be installed for packet capture
• Administrator privileges — required to capture raw packets

---

Installation

1. Install Npcap (required)

Download and install from: https://npcap.com/#download

During installation, check "Install Npcap in WinPcap API-compatible Mode"

2. Install Python dependencies

pip install -r requirements.txt

3. Run as Administrator

Right-click your terminal (CMD or PowerShell) → "Run as Administrator"

python main.py

---

Usage

python main.py [OPTIONS]

Option	Description
-i INTERFACE	Network interface to capture on
-f PROTOCOL	Filter: tcp, udp, icmp, arp, dns, http, all
-p PORT	Filter by port number
--ip ADDRESS	Filter by IP address
-c N	Stop after capturing N packets
--list-interfaces	Show available interfaces
--no-resolve	Skip hostname resolution (faster)
--save FILE.pcap	Also save to .pcap file
--theme THEME	dark / hacker / light

Examples

# Capture all traffic on all interfaces
python main.py

# Capture only on Wi-Fi adapter
python main.py -i "Wi-Fi"

# Show only DNS traffic
python main.py -f dns

# Monitor a specific IP
python main.py --ip 192.168.1.1

# Capture 500 packets and save to file
python main.py -c 500 --save capture.pcap

# Hacker theme, TCP only, no DNS resolution
python main.py -f tcp --no-resolve --theme hacker

# List available network interfaces
python main.py --list-interfaces

---

Project Structure

packet_sniffer/
├── main.py          ← CLI entry point & argument parsing
├── search.py        ← Search bar function for realtime filters
├── sniffer.py       ← Packet capture engine (scapy)
├── analyzer.py      ← Protocol parsing & connection tracking
├── display.py       ← Terminal UI (rich live display)
└── requirements.txt

---

How It Works

1. main.py — Parses CLI args, checks admin rights, launches NetSpy
2. sniffer.py — Uses scapy.sniff() in a background thread; builds BPF filters; tracks bandwidth per second
3. analyzer.py — Parses each packet layer by layer (ARP → IP → TCP/UDP → DNS/HTTP); maintains connection state and raises alerts
4. display.py — Uses rich.live.Live to redraw a multi-panel layout every 250ms without flickering

---

Real-time Search & Filter

Press / at any time to open the search bar — packets are filtered instantly as you type, without stopping the live capture.

Key bindings

Key	Action
/	Open search bar
Enter	Apply current filter
Esc	Cancel (in search mode) / Clear filter (normal mode)
Backspace	Delete last character
Ctrl+U	Clear entire search query
Q	Quit
C	Clear packet log

Filter syntax

All tokens are AND-combined (all must match):

Token	Matches	Example
tcp udp dns http icmp arp	Protocol name	dns
ip:VALUE	Source or destination IP (partial)	ip:192.168
src:VALUE	Source IP only	src:10.0.0.1
dst:VALUE	Destination IP only	dst:8.8.8.8
port:N	Source or destination port	port:443
sport:N	Source port only	sport:52341
dport:N	Destination port only	dport:80
flag:F	TCP flag	flag:SYN flag:RST
len:>N len:<N len:=N	Packet length	len:>1000
info:TEXT	Search in payload/info field	info:google
Bare number	Match any port	443
Bare IP-like	Match src or dst	192.168.1
Anything else	Fuzzy match all fields	google

Filter examples

dns                          → DNS traffic only
tcp port:443                 → TCP on port 443 (HTTPS)
ip:192.168.1 port:80         → Port 80 to/from 192.168.x.x subnet
dst:8.8.8.8                  → Traffic going to Google DNS
flag:SYN flag:ACK            → TCP SYN-ACK packets (handshake)
len:>1400                    → Large packets (near MTU)
info:google                  → Packets with "google" in payload/info
tcp flag:RST                 → TCP resets
src:10.0.0.5 dport:443       → One host's HTTPS outbound

The packet log title shows live match count: 📡 Packet Log 🔍 42/1337

---

Alerts

NetSpy flags:

• Suspicious ports: Access to RDP (3389), SMB (445), Telnet (23), VNC (5900), MSSQL (1433), etc.
• Port scans: A single source IP hitting 15+ unique destination ports within 10 seconds

---

Tips

• Slow performance? Use --no-resolve to skip reverse DNS lookups
• No packets? Make sure Npcap is installed and you're running as Administrator
• Wrong interface? Run --list-interfaces and pass the name with -i
• Wireshark integration: Use --save output.pcap then open in Wireshark

---

License

MIT — free to use, modify, and distribute.