## 📸 Dashboard Preview
📊 Stats View — Live bandwidth, protocol distribution, top talkers (click to expand)
🔍 Inspection View — Deep packet inspection with hex dump (click to expand)
🔧 Filter View — Custom DSL with protocol, IP, port, and compound filters (click to expand)
🛡️ Threat Detection — ARP spoofing, port scanning, DNS tunneling detection (click to expand)
❓ Help View — Complete keybinding reference (click to expand)
## 🎯 Who Is This For?
| Audience | Use Case |
|----------|----------|
| 🔐 **Cybersecurity Students** | Learn packet analysis, understand protocol headers, study network attacks |
| 🕵️ **Penetration Testers** | Monitor attack traffic in real-time, verify ARP spoofing / scanning tools |
| 🌐 **Network Administrators** | Diagnose network issues, monitor bandwidth, identify rogue traffic |
| 🧑💻 **Developers** | Debug HTTP/DNS/TLS traffic from applications |
| 📚 **Researchers** | Capture and export traffic datasets for analysis |
| 🏠 **Home Lab Enthusiasts** | Monitor home network for suspicious activity |
## ✨ Features
### 🚀 Core Capabilities
- **Real-time packet capture** using raw sockets via `pnet` — no `libpcap` dependency
- **Promiscuous mode** — captures ALL traffic on the network segment
- **Multi-threaded architecture** — capture thread + UI thread with lock-free channels
- **Zero-copy parsing** — efficient packet dissection without unnecessary memory allocation
### 🔬 Deep Protocol Inspection (OSI Layers 2–7)
| OSI Layer | Protocols | Details |
|-----------|-----------|---------|
| **Link (L2)** | Ethernet, ARP | MAC addresses, EtherType, ARP request/reply parsing |
| **Network (L3)** | IPv4, IPv6, ICMP, ICMPv6 | IP addresses, TTL/Hop Limit, flags, DSCP, identification |
| **Transport (L4)** | TCP, UDP | Ports, sequence/ack numbers, all TCP flags (SYN/ACK/FIN/RST/PSH/URG/ECE/CWR), window size |
| **Application (L7)** | HTTP, DNS, TLS, SSH, DHCP | HTTP methods/status, DNS queries/answers, TLS version + SNI extraction, SSH version detection |
### 🛡️ Threat Detection Engine
| Threat | Detection Method | Severity |
|--------|-----------------|----------|
| **Port Scanning** | >15 unique destination ports from single source within 60s | 🟠 HIGH |
| **ARP Spoofing** | Multiple MAC addresses claiming same IP via ARP Reply | 🔴 CRITICAL |
| **DNS Tunneling** | DNS query labels >40 characters or total query >100 chars | 🟡 MEDIUM |
| **Suspicious Ports** | Traffic to known malware ports (4444, 31337, 6667, etc.) | 🔵 LOW |
| **DDoS Indicators** | >500 packets in 10 seconds from single source | 🟠 HIGH |
### 🔧 Custom Filter DSL
A powerful domain-specific language for filtering traffic:
## Protocol filters
tcp # All TCP packets (includes HTTP, TLS, SSH)
udp # All UDP packets (includes DNS, DHCP)
dns # DNS traffic only
http || tls # HTTP or TLS
arp # ARP packets
!icmp # Everything except ICMP
## Field filters
ip == 192.168.1.1 # Source IP match
dst == 8.8.8.8 # Destination IP
port == 443 # Source or destination port
sport == 80 # Source port only
dport == 53 # Destination port only
port 80..443 # Port range
len > 1000 # Packet size > 1000 bytes
ttl < 64 # TTL less than 64
direction == in # Incoming packets only
## Compound filters
tcp && port == 443 # TCP on port 443
(http || dns) && direction == out
tcp && len > 500 && dst == 10.0.0.1
contains "google" # Text search in packet summary
### 📊 Live Statistics Dashboard
- **Bandwidth sparkline graph** — real-time bytes/second visualization
- **Protocol distribution table** — packet count, bytes, and percentage per protocol
- **TCP flag analysis** — SYN, ACK, FIN, RST, PSH breakdown
- **Top sources / destinations / conversations** — ranked by packet count
- **Directional traffic** — incoming vs outgoing byte counters
- **Performance metrics** — packets/second, bytes/second, average packet size
### 📁 Multi-Format Export
- **JSON** — Full packet details with all parsed layer data (`e` key)
- **CSV** — Summary table for spreadsheet analysis (`E` key)
- **PCAP** — Industry-standard format, compatible with Wireshark (`p` key)
### 🎨 Terminal UI (TUI)
- **6 interactive tabs**: Dashboard, Inspection, Stats, Filters, Threats, Help
- **Vim-style navigation** — `j/k` scroll, `g/G` jump, `/` search
- **Packet detail pane** with hex dump view
- **Protocol-colored packet list** — each protocol has a distinct color
- **Auto-scroll** with toggle
- **Live status bar** — capture status, packet count, data volume, active filter
## 📋 Prerequisites
| Requirement | Details |
|-------------|---------|
| **Operating System** | Linux (tested on Kali Linux 2024.x) |
| **Rust** | 1.75 or newer [install via rustup](https://rustup.rs/) |
| **System Libraries** | `build-essential`, `libpcap-dev`, `pkg-config` |
| **Privileges** | Root (`sudo`) or `CAP_NET_RAW` + `CAP_NET_ADMIN` capabilities |
| **Terminal** | Any modern terminal emulator with Unicode support |
## 🚀 Installation
### Install Dependencies (Debian/Ubuntu/Kali)
```
sudo apt update
sudo apt install -y build-essential libpcap-dev pkg-config
```
*Real-time packet capture, deep protocol inspection, threat detection, and traffic analysis — all from your terminal.*
**PacketViper** is a terminal-based network traffic analyzer designed for cybersecurity professionals, penetration testers, network administrators, and students. It captures live network packets, parses them across all OSI layers (L2–L7), detects active threats like ARP spoofing and port scanning, and provides a rich dashboard with real-time statistics — all without leaving your terminal.