Skip to content

README.md

Latest commit

 

History

History
225 lines (171 loc) · 7.25 KB

README.md

File metadata and controls

225 lines (171 loc) · 7.25 KB

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.