foxsniff

A minimal, dependency-free IPv4 packet sniffer for Linux, built directly on Python raw sockets.

foxsniff is a small educational packet sniffer that captures Ethernet frames using Linux raw sockets and manually parses Ethernet and IPv4 headers using only Python's standard library.

It intentionally avoids libpcap, Scapy, and other packet-capture frameworks so that the mechanics of packet capture and protocol parsing remain visible and easy to understand.

---

Table of Contents

• Overview
• Features
• How It Works
• Requirements
• Installation
  • Install from PyPI
  • Install from Source
  • Development Installation
• Usage
• Example Output
• Packet Parsing
  • Ethernet
  • IPv4
  • Protocol Numbers
• Project Structure
• Testing
• Architecture
• Limitations
• Troubleshooting
• Security and Responsible Use
• Roadmap
• Contributing
• License

---

Overview

Traditional packet-analysis tools often hide low-level packet handling behind mature libraries.

foxsniff takes the opposite approach.

It opens a Linux AF_PACKET raw socket, receives raw Ethernet frames, parses the Ethernet header, filters for IPv4 traffic, and then parses the IPv4 header directly with struct.unpack().

The result is a compact codebase that is useful for:

• Learning how Ethernet frames are structured
• Understanding IPv4 header fields
• Learning Python's socket and struct modules
• Experimenting with raw sockets
• Building a foundation for a more capable packet analyzer
• Exploring networking concepts without external dependencies

What foxsniff currently captures

Ethernet frame
    │
    ├── Destination MAC
    ├── Source MAC
    └── EtherType
             │
             └── IPv4 (0x0800)
                    │
                    ├── Version
                    ├── Header Length
                    ├── TTL
                    ├── Protocol
                    ├── Source IP
                    └── Destination IP

foxsniff currently reports IPv4 packet metadata rather than attempting to fully decode the transport-layer payload.

---

Features

• Raw packet capture using Linux AF_PACKET
• Ethernet header parsing
• IPv4 header parsing
• Variable-length IPv4 header support through the IHL field
• MAC address formatting
• IPv4 address formatting
• Protocol number reporting
• TTL reporting
• Zero third-party runtime dependencies
• Small, readable implementation
• Command-line entry point
• Python 3.8+ support
• MIT licensed

---

How It Works

foxsniff operates at the Ethernet layer and works upward through the IPv4 header.

1. Create a raw socket

The program creates a Linux packet socket:

socket.socket(
    socket.AF_PACKET,
    socket.SOCK_RAW,
    socket.ntohs(3)
)

AF_PACKET provides access to packets at the link layer and is specific to Linux.

Because raw packet sockets require elevated privileges, foxsniff normally needs to be executed with sudo.

2. Receive a frame

The sniffer waits for incoming frames:

raw_data, addr = conn.recvfrom(65536)

The returned data contains the raw bytes of the captured frame.

3. Parse the Ethernet header

The first 14 bytes are interpreted as:

6 bytes   Destination MAC
6 bytes   Source MAC
2 bytes   EtherType

foxsniff uses network byte order (!) with Python's struct module.

IPv4 frames have an EtherType of:

0x0800

Only frames with this EtherType are passed to the IPv4 parser.

4. Parse the IPv4 header

The IPv4 parser extracts:

• IP version
• Internet Header Length (IHL)
• TTL
• Protocol
• Source address
• Destination address

The IHL value is used to determine where the IPv4 payload begins, allowing the parser to account for IPv4 header options.

5. Display the result

The extracted information is printed to the terminal in a compact, human-readable format.

---

Requirements

Operating system

Linux is required.

foxsniff relies on:

socket.AF_PACKET

which is a Linux-specific packet-capture interface.

It is not currently a portable Windows or macOS packet sniffer.

Python

Python 3.8 or newer is required.

Runtime dependencies

None.

foxsniff uses Python standard-library modules such as:

• socket
• struct
• sys

Privileges

Raw packet sockets generally require elevated privileges.

Run the program with:

sudo foxsniff

---

Installation

Install from PyPI

If a published package is available:

python3 -m pip install foxsniff

Then run:

sudo foxsniff

Install from Source

Clone the repository:

git clone https://github.com/foxhackerzdevs/foxsniff.git
cd foxsniff

Install it:

python3 -m pip install .

Run:

sudo foxsniff

Development Installation

For local development, install the package in editable mode:

python3 -m pip install -e .

This allows changes to the source tree to be reflected without reinstalling the package.

---

Usage

Start the sniffer with:

sudo foxsniff

You should see:

Listening for incoming packets...

foxsniff then waits for IPv4 packets.

Press:

Ctrl+C

to stop the sniffer.

---

Example Output

A typical capture looks like:

Listening for incoming packets...

[+] IPv4 Packet: 192.0.2.1 -> 192.0.2.2
    |- Ethernet Frame: MAC Src: 02:FC:00:00:00:05 | MAC Dst: 02:FC:00:00:00:01
    |- Protocol: 6 | TTL: 60

Reading the output

192.0.2.1 -> 192.0.2.2

The source and destination IPv4 addresses.

MAC Src: 02:FC:00:00:00:05

The Ethernet source address.

MAC Dst: 02:FC:00:00:00:01

The Ethernet destination address.

Protocol: 6

The IPv4 protocol field. 6 represents TCP.

TTL: 60

The IPv4 Time To Live value.

---

Packet Parsing

Ethernet

foxsniff reads the standard Ethernet II header:

Field	Size	Description
Destination MAC	6 bytes	Receiving interface MAC address
Source MAC	6 bytes	Sending interface MAC address
EtherType	2 bytes	Identifies the encapsulated protocol

The parser uses:

struct.unpack('! 6s 6s H', data[:14])

The ! specifies network byte order.

IPv4 is identified with:

0x0800

IPv4

foxsniff reads the beginning of the IPv4 header and extracts:

Field	Description
Version	IP version
IHL	IPv4 header length
TTL	Time To Live
Protocol	Encapsulated transport/network protocol
Source IP	Packet origin
Destination IP	Packet destination

The IPv4 header is not always exactly 20 bytes. The IHL field specifies its length in 32-bit words.

foxsniff converts that value to bytes:

header_length = (version_and_header_length & 15) * 4

This allows the parser to locate the IPv4 payload correctly when optional IPv4 header fields are present.

---

Protocol Numbers

The IPv4 Protocol field identifies the next protocol.

Common values include:

Number	Protocol
1	ICMP
6	TCP
17	UDP
41	IPv6
47	GRE
50	ESP
51	AH
89	OSPF

foxsniff currently prints the numeric protocol value rather than decoding it into a protocol name.

For example:

Protocol: 6

means TCP.

---

Project Structure

foxsniff/
├── src/
│   └── sniffer/
│       ├── __init__.py
│       └── sniffer.py
├── tests/
│   └── test_sniffer.py
├── .gitignore
├── LICENSE
├── README.md
└── pyproject.toml

src/sniffer/sniffer.py

Contains the packet-sniffing implementation, including:

• Raw socket creation
• Ethernet frame parsing
• IPv4 packet parsing
• MAC formatting
• IP formatting
• Main capture loop

tests/test_sniffer.py

Contains tests for the sniffer's parsing functionality.

pyproject.toml

Defines the Python package metadata, build configuration, dependencies, and the foxsniff command-line entry point.

The package exposes:

foxsniff -> sniffer.sniffer:main

LICENSE

Contains the project's MIT license.

---

Testing

Run the test suite with:

python3 -m pytest

If pytest is not installed in your development environment:

python3 -m pip install pytest

The tests are separate from the runtime package, so pytest is not required simply to run foxsniff.

---

Architecture

foxsniff follows a deliberately simple processing pipeline:

                Linux Network Interface
                          │
                          ▼
                 AF_PACKET raw socket
                          │
                          ▼
                    Raw Ethernet
                       frame
                          │
                          ▼
              ┌───────────────────────┐
              │ Ethernet parser       │
              │                       │
              │ Src MAC               │
              │ Dst MAC               │
              │ EtherType             │
              └───────────┬───────────┘
                          │
                    EtherType
                    == 0x0800
                          │
                          ▼
              ┌───────────────────────┐
              │ IPv4 parser           │
              │                       │
              │ Version               │
              │ IHL                   │
              │ TTL                   │
              │ Protocol              │
              │ Source IP             │
              │ Destination IP        │
              └───────────┬───────────┘
                          │
                          ▼
                    Terminal output

The design intentionally keeps protocol parsing explicit instead of delegating it to a packet-analysis library.

---

Limitations

foxsniff is intentionally minimal and should not be considered a replacement for mature packet-analysis tools.

Current limitations include:

• Linux only
• Requires elevated privileges
• IPv4-focused
• Does not currently decode TCP headers
• Does not currently decode UDP headers
• Does not currently decode ICMP messages
• Does not display TCP/UDP ports
• Does not decode TCP flags
• Does not save packets to PCAP
• Does not provide BPF-style filtering
• Does not provide interface-selection CLI options
• Does not reconstruct connections or flows
• Does not inspect application-layer protocols
• Does not provide a graphical interface
• Does not provide packet statistics or summaries

For advanced packet analysis, tools such as Wireshark or Scapy are more appropriate.

The goal of foxsniff is simplicity and education.

---

Troubleshooting

PermissionError

If you see:

Error: You must run this script with root/administrator privileges.

run:

sudo foxsniff

Raw packet sockets generally require elevated privileges.

AF_PACKET is unavailable

If the socket creation fails because AF_PACKET is unavailable, verify that you are running Linux.

foxsniff is not currently designed for Windows or macOS.

No packets appear

Try generating some network traffic from another terminal:

ping 1.1.1.1

or:

curl https://example.com

Then watch the foxsniff terminal for IPv4 packets.

Also verify that your system and network configuration allow the interface to expose the traffic you expect to capture.

Stopping the sniffer

Press:

Ctrl+C

The program catches KeyboardInterrupt and exits the capture loop.

---

Security and Responsible Use

Packet sniffing provides visibility into network traffic and should be used responsibly.

Only capture traffic on systems and networks that you own or have explicit authorization to monitor.

Do not use foxsniff to intercept traffic belonging to other people, organizations, or networks without permission.

Remember that packet captures can potentially expose sensitive metadata or content depending on the protocols and traffic being observed. Treat captured information accordingly.

foxsniff is primarily intended for:

• Personal labs
• Development environments
• Networking education
• Authorized troubleshooting
• Security research in controlled environments

---

Roadmap

Potential future improvements include:

• Human-readable protocol names
• TCP header parsing
• UDP header parsing
• ICMP parsing
• Source/destination port display
• TCP flag decoding
• Packet length and timestamp output
• Network-interface selection
• Protocol/IP/port filtering
• Optional payload inspection
• PCAP export
• Better error handling for malformed packets
• Expanded unit-test coverage
• IPv6 support
• Command-line configuration options

These features are intentionally outside the scope of the current minimal implementation but provide natural directions for extending the project.

---

Contributing

Contributions are welcome.

A typical development workflow is:

git clone https://github.com/foxhackerzdevs/foxsniff.git
cd foxsniff
python3 -m pip install -e .

Before submitting a change:

1. Keep the implementation small and readable.
2. Add or update tests where appropriate.
3. Avoid introducing unnecessary runtime dependencies.
4. Document user-visible behavior.
5. Verify that existing functionality continues to work.

For larger changes, open an issue first to discuss the proposed direction.

---

License

foxsniff is released under the MIT License.

See LICENSE for the complete license text.

---

Disclaimer

foxsniff is provided for educational, development, and authorized network-monitoring purposes.

The authors are not responsible for misuse of the software. You are responsible for ensuring that your use of foxsniff complies with applicable laws, regulations, policies, and network-authorization requirements.

---

Project Links

• Source: https://github.com/foxhackerzdevs/foxsniff
• License: MIT

---

Built with Python's standard library. No libpcap. No Scapy. Just raw sockets, bytes, and protocol headers.