Network Packet Sniffer 🔎

A powerful and educational network packet sniffer for wired and wireless interfaces with monitor mode support. This tool captures and analyzes network traffic, including non-destined packets, making it perfect for network analysis, security research, and educational purposes.

🚀 Features

• Multi-Interface Support: Capture from both wired (Ethernet) and wireless (Wi-Fi) network interfaces
• Monitor Mode: Enable monitor mode on wireless interfaces to capture all wireless traffic
• Promiscuous Mode: Switch wired interfaces to promiscuous mode to capture all LAN traffic
• Protocol Filtering: Filter packets by protocol (ARP, IP, TCP, UDP, ICMP, DNS, HTTP, HTTPS)
• Real-Time Analysis: View packet details and statistics in real-time during capture
• Packet Details: Inspect packet headers and payload with hex dump view
• Export Options: Save captured packets in multiple formats (JSON, CSV, Text, PCAP, XML)
• GUI & CLI: Use either the graphical interface or command-line tools based on your preference
• Wireshark Compatible: Export captures to PCAP format for deeper analysis in Wireshark

📋 Requirements

• Python 3.8+
• Linux-based operating system (tested on Ubuntu, Kali Linux)
• Root/sudo privileges (required for packet capturing)
• Compatible wireless network interface card for monitor mode
• Dependencies:
  • Scapy
  • PyQt5
  • netifaces
  • python-dateutil
  • aircrack-ng (system package for monitor mode)
  • net-tools (system package)
  • wireless-tools (system package)

🔧 Installation

Method 1: Using the Installation Script (Recommended)

The easiest way to install all dependencies is using our installation script:

# Clone the repository
git clone https://github.com/deviant101/network-packet-sniffer.git
cd network-packet-sniffer

# Make the installation script executable
chmod +x install.sh

# Run the installation script with sudo
sudo ./install.sh

The script will install all required Python and system dependencies automatically.

Method 2: Manual Installation

If you prefer to install dependencies manually:

1. Clone the repository:

git clone https://github.com/yourusername/network-packet-sniffer.git
cd network-packet-sniffer

2. Install system dependencies:

sudo apt-get update
sudo apt-get install -y python3 python3-pip python3-dev aircrack-ng net-tools wireless-tools

3. Install Python dependencies:

# From requirements.txt
sudo pip3 install -r requirements.txt

# Or individually
sudo pip3 install scapy>=2.4.5 PyQt5>=5.15.0 pyqt5-tools>=5.15.0 netifaces>=0.11.0 python-dateutil>=2.8.2

4. Set correct permissions:

# Create logs directory
mkdir -p logs

# Make scripts executable
chmod +x sniffer.py
chmod +x restore-wifi.sh

Method 3: Using Python Virtual Environment

For a cleaner installation that doesn't affect your system Python packages:

# Install system dependencies
sudo apt-get update
sudo apt-get install -y python3 python3-pip python3-dev aircrack-ng net-tools wireless-tools python3-venv

# Clone the repository
git clone https://github.com/yourusername/network-packet-sniffer.git
cd network-packet-sniffer

# Create and activate a virtual environment
python3 -m venv venv
source venv/bin/activate

# Install Python dependencies
pip install -r requirements.txt

# Create logs directory and set permissions
mkdir -p logs
chmod +x sniffer.py restore-wifi.sh

# Note: You'll need to activate the virtual environment each time
# before running the sniffer with: source venv/bin/activate

🏃 Running the Sniffer

GUI Mode

To launch the packet sniffer with the graphical user interface:

sudo python3 sniffer.py --gui

CLI Mode

For command-line interface operation:

sudo python3 sniffer.py --cli

Note: Root/sudo privileges are required for packet capturing as it involves low-level network access.

📖 CLI Options & Commands

The CLI version supports the following options and commands:

Usage: sudo python3 sniffer.py [--gui | --cli] [OPTIONS]

Options:
  --gui                      Start in GUI mode (default)
  --cli                      Start in CLI mode
  --interface, -i INTERFACE  Specify network interface to use
  --monitor, -m              Enable monitor mode (wireless only)
  --promisc, -p              Enable promiscuous mode (wired only)
  --count, -c COUNT          Number of packets to capture (default: 0 = infinite)
  --timeout, -t SECONDS      Capture timeout in seconds
  --output, -o FILE          Save captured packets to file
  --format, -f FORMAT        Output format (json, csv, text, pcap, xml)
  --filter FILTER            Filter by protocol (e.g. "tcp,udp,arp")
  --help, -h                 Show this help message

CLI Interactive Commands

Once in the CLI interactive mode, the following commands are available:

interfaces      - List available network interfaces
use <interface> - Select network interface
monitor on/off  - Enable/disable monitor mode (wireless only)
promisc on/off  - Enable/disable promiscuous mode (wired only)
start           - Start packet capture
stop            - Stop packet capture
filter <proto>  - Set protocol filter (e.g., "tcp,udp,arp")
show <packet>   - Show details of a specific packet
stats           - Show capture statistics
save <file>     - Save captured packets to file
format <type>   - Set output format (json, csv, text, pcap, xml)
clear           - Clear captured packets
help            - Show this help message
exit            - Exit the program

🖥️ GUI Usage Guide

The graphical interface provides an intuitive way to interact with the packet sniffer:

1. Interface Selection: Use the dropdown menu to select a network interface
2. Mode Setting:
   • For wireless interfaces: Check "Enable Monitor Mode"
   • For wired interfaces: Check "Enable Promiscuous Mode"
3. Capture Controls:
   • Click "Start" to begin capturing packets
   • Click "Stop" to halt the capture process
4. Protocol Filters: Check/uncheck protocols in the filter panel
5. Packet List: View all captured packets with summary information
6. Packet Details: Click on a packet in the list to view its details
7. View Options: Switch between structured view, payload, and hex dump
8. Statistics: View packet distribution by protocol
9. Export Options:
   • File → Save Captured Packets → Select format
   • Select packets before exporting to save only selected packets

📊 Understanding Packet Data

The packet sniffer provides the following information for each captured packet:

• Basic Info: Timestamp, packet number, length
• Layer 2: MAC addresses, Ethernet type or 802.11 frame info
• Layer 3: IP addresses, TTL, protocol
• Layer 4: Port numbers, sequence numbers, flags
• Application Data: HTTP requests/responses, DNS queries/answers

⚠️ Ethical & Legal Considerations

This tool is developed strictly for educational purposes as part of the CS-4061 Ethical Hacking Concepts & Practices course. Please use responsibly and ethically:

• Only use this tool on networks you own or have explicit permission to test
• Do not capture packets on public or unauthorized networks
• Be aware that capturing network traffic may expose sensitive information
• Respect privacy and confidentiality of any data captured
• Follow all applicable laws regarding network monitoring in your jurisdiction

🛠️ Troubleshooting

Monitor Mode Issues

If you encounter problems enabling monitor mode:

# Check if your wireless interface supports monitor mode
sudo iw list | grep "Supported interface modes" -A 10

# Manual monitor mode setup (if the built-in method fails)
sudo airmon-ng start <interface>

Wireless Network Recovery

If your wireless connection doesn't recover after using monitor mode:

1. Use the included script to restore normal operation:

sudo ./restore-wifi.sh

2. Or manually restore with:

sudo airmon-ng stop <monitor_interface>
sudo systemctl restart NetworkManager

Permission Denied

If you receive "Permission denied" errors:

# Make sure to run with sudo
sudo python3 sniffer.py

🔍 Project Structure

.
├── sniffer.py              # Main application entry point
├── interface_manager.py    # Network interface handling
├── packet_analyzer.py      # Packet capture and analysis
├── logger.py               # Packet logging and export functionality
├── gui.py                  # Graphical user interface
├── cli.py                  # Command-line interface
├── restore-wifi.md         # Instructions for restoring wireless connectivity
├── logs/                   # Default directory for saved packet logs
└── README.md               # This file

🔄 Known Limitations

• Not all wireless cards support monitor mode
• Deep packet inspection is limited to common protocols
• Performance may degrade with high-volume traffic
• Cannot decrypt encrypted traffic (e.g., HTTPS content)
• GUI performance may slow down with very large capture sets

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

📜 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Developed for CS-4061 Ethical Hacking Concepts & Practices
• Thanks to the Scapy project for providing the packet manipulation library
• Inspired by tools like Wireshark, tcpdump, and other network analysis utilities