NetScope — A Minimal Raw Socket Tool for Learning Network Protocols

NetScope is an educational, Linux-only Python tool designed to help students, engineers, and cybersecurity enthusiasts understand packet-level networking. It captures raw packets from a network interface, parses Ethernet, IPv4, and TCP/UDP headers, and prints structured, human-readable output directly to the terminal.

---

Features

• Raw socket capture: Learn how packets are delivered from the OS network stack.
• Layered parsing: Ethernet → IPv4 → TCP/UDP headers.
• Protocol name mapping: Converts protocol numbers to readable names (e.g., 6 → TCP, 17 → UDP).
• Lightweight and educational: No dependencies outside Python standard library.

---

Repository Structure

NetScope/
├── run.py          # main capture script
├── sniffer.py      # raw socket wrapper and helper functions
├── parse_eth.py    # Ethernet header parser
├── parse_ip.py     # IPv4 header parser
└── parse_tcp.py    # TCP and UDP header parser

---

Requirements

• Linux operating system (raw sockets require root privileges)
• Python 3.13.7
• No additional packages required

---

Usage

Run run.py with sudo to capture a packet and parse headers:

sudo python run.py

Example Output:

[2025-10-15 18:33:11] timestamp
raw socket created successfully
packet captured and sender address: ('eth0', 2048, 0, 1, b'RU\n\x00\x02\x02')
socket closed
data save to : packet_data.bin 
--------parse eth running --------
source mac : 52:55:0a:00:02:02
destination mac : 08:00:27:1f:b7:23
ip protocal version : 8
--------parse ip running --------
Source IP: 34.107.243.93
Destination IP: 10.0.2.15
Protocol name: TCP (Transmission Control Protocol)
protocal number: 6
TTL: 64
Version: 4
Header length: 20 bytes
--------parse tcp running --------

--- TCP Header ---
Source Port:    443
Destination Port:49572
Sequence:       336321316
Acknowledgment: 3360096520
Header Length:  20 bytes

---

Notes

• Root privileges required: Raw sockets require elevated permissions on Linux.
• Educational tool: Designed for learning and experimentation; not intended as a full production sniffer.
• Limitations: Currently Linux-only; does not support live GUI visualization or cross-platform deployment.

---

Next Steps / Extensions

• Support live packet capture loops with multiple packets.
• Add UDP/TCP application-level parsing (DNS, HTTP, DHCP).
• Export captures to .pcap for analysis in Wireshark.
• Add command-line arguments for interface selection, packet count, and filtering.

---

NetScope provides a clean, minimal, and educational framework to explore network packet structures directly from Python. Perfect for learning, debugging, or teaching low-level networking concepts.