Network Sniffer Toolkit

Lightweight CLI packet analysis tool for live network monitoring and offline PCAP investigation with built-in anomaly alerts.

🚀 Overview

Network Sniffer Toolkit captures packets, parses protocol-level details, and summarizes traffic so you can quickly understand what is happening on a network.

This project was built as a practical learning and security utility: simple enough for beginners, but structured enough to demonstrate real packet-processing architecture.

Where it is useful in real life:

• Security labs and coursework for basic anomaly detection practice
• Developer environments for troubleshooting local network behavior
• Offline forensic-style review of recorded traffic using PCAP files

🔥 Features

Implemented features in the current codebase:

• Live packet capture with optional network interface selection
• Offline PCAP analysis using the bundled sample capture or any user-provided PCAP
• Packet parsing for IP, TCP, UDP, ICMP, DNS, and basic HTTP request payloads
• Protocol filtering via CLI (--protocol) for TCP, UDP, ICMP, DNS, or HTTP
• Real-time terminal dashboard with packet counts, protocol mix, top source IP, and recent alerts
• Compact per-packet terminal output with timestamp, endpoints, protocol, size, and optional parsed details
• Suspicious traffic heuristics for:
  • potential TCP port scanning (many unique destination ports from one source)
  • high per-source packet volume (every 250 packets)
  • short traffic bursts (40+ packets in 2 seconds)
  • high DNS query volume (possible tunneling signal)
  • DNS queries ending in specific suspicious TLDs (.xyz, .top, .click, .buzz, .gq, .tk)
• Optional packet and alert file logging (--log)
• JSON export of session summary (--report) and packet-level events (--export)
• Runtime error handling for missing PCAP files, read errors, and capture permission issues

🛠 Tech Stack

• Language: Python
• Libraries:
  • Scapy (packet capture, packet parsing, PCAP reading)
  • Rich (live CLI dashboard and styled terminal output)
• Python standard library: argparse, collections, datetime, json, pathlib, typing

📂 Project Structure

network-sniffer-toolkit/
|-- core/
|   |-- sniffer.py        # CLI entry point: live capture and PCAP workflows
|   |-- parser.py         # Converts packets into normalized dictionaries
|   |-- analyzer.py       # Tracks packet, byte, protocol, and endpoint statistics
|   |-- detector.py       # Heuristic suspicious-traffic detection
|   |-- dashboard.py      # Live Rich dashboard rendering
|   `-- report.py         # JSON report and packet event export helpers
|
|-- protocols/
|   |-- dns_parser.py     # DNS query/response detail extraction
|   `-- http_parser.py    # Basic HTTP request line + Host header extraction
|
|-- utils/
|   |-- filters.py        # Protocol filter matching helper
|   `-- logger.py         # File logger for packet/alert lines
|
|-- data/
|   `-- sample.pcap       # Sample capture for offline testing
|
|-- docs/
|   `-- sample-output.md  # Expected results for sample.pcap
|
|-- output/               # Generated artifacts (logs/reports/events)
|-- requirements.txt      # Python dependencies
|-- proejct.md            # Project notes/document draft
`-- README.md

⚙️ Setup & Installation

Prerequisites:

• Python 3.10 or newer
• Administrator/root privileges for live capture mode

Copy-paste setup:

git clone https://github.com/urvalkheni/network-sniffer-toolkit.git
cd network-sniffer-toolkit
pip install -r requirements.txt
python core/sniffer.py --help

What each step does:

• git clone ... downloads the project
• cd ... moves into the project folder
• pip install -r requirements.txt installs Scapy and Rich
• python core/sniffer.py --help verifies the CLI is ready and shows all options

Optional virtual environment setup:

python -m venv .venv
# Windows PowerShell
.\.venv\Scripts\Activate.ps1
# macOS/Linux
source .venv/bin/activate

🧪 Usage Examples

Analyze the bundled sample PCAP (easy first run):

python core/sniffer.py --pcap data/sample.pcap

Analyze only DNS packets from a PCAP:

python core/sniffer.py --pcap data/sample.pcap --protocol DNS

Run live capture on a specific interface:

python core/sniffer.py --iface Ethernet

Capture only a fixed number of live packets:

python core/sniffer.py --count 100

Save logs and export JSON artifacts:

python core/sniffer.py --pcap data/sample.pcap --log output/logs.txt --report output/report.json --export output/events.json

What the exports contain:

• --report: high-level summary (totals, protocol breakdown, top endpoints, suspicious IPs)
• --export: per-packet normalized records with optional alert list

📊 Example Output

Console summary from running:

python core/sniffer.py --pcap data/sample.pcap --report output/sample-report.json --export output/sample-events.json

Analysis Summary
Total Packets: 120
Top Protocol: TCP
Suspicious IPs: 10.0.0.10, 10.0.0.20, 10.0.0.30

Excerpt from output/sample-report.json:

{
	"mode": "pcap",
	"source": "data/sample.pcap",
	"total_packets": 120,
	"total_bytes": 7858,
	"avg_packet_size": 65.48,
	"top_protocol": "TCP",
	"suspicious_ips": [
		"10.0.0.10",
		"10.0.0.20",
		"10.0.0.30"
	]
}

🧠 How It Works

Flow: Input -> Processing -> Output

1. Input
   • Live packets from Scapy capture (sniff) or packets read from a PCAP (PcapReader)
2. Processing
   • Each packet is normalized into a Python dictionary
   • Protocol-specific parsers add DNS and HTTP details when available
   • Analyzer updates running metrics (packet counts, bytes, top endpoints, protocol mix)
   • Detector applies heuristic checks and generates alert messages
3. Output
   • Live dashboard updates in terminal
   • Packet lines and alert lines are printed
   • Optional file log and JSON exports are written

🔐 Limitations / Notes

• Detection is heuristic-based and rule-threshold based, not signature-based IDS or ML
• HTTP parsing covers plain-text request payload patterns only; encrypted HTTPS payloads are not decoded
• Protocol filter is exact-match on parsed packet protocol labels
• Live capture usually requires elevated permissions
• High-throughput production environments may need more performance tuning and richer detection rules

🎯 Learning Outcomes

This project demonstrates practical skills in:

• Packet capture and protocol parsing with Scapy
• Building modular CLI tools in Python
• Real-time terminal UI design with Rich
• Basic network anomaly detection design
• Structured logging and JSON report generation

🚀 Future Improvements

• Add configurable detection thresholds via CLI flags
• Extend protocol parsers (for example TLS metadata and more DNS context)
• Add unit tests for parser and detector modules
• Add CSV export for easier spreadsheet-based review

⚠️ Disclaimer

This tool is for educational and authorized security testing only.

Capture or inspect traffic only on networks and systems you own or have explicit permission to monitor.