eBPF XDP Packet Monitor

A high-performance packet monitoring tool built with eBPF, XDP, and Go. The application attaches an XDP program to a network interface and streams IPv4 packet metadata—including Layer 4 port information—to userspace using a Linux eBPF ring buffer.

The monitor is designed to provide low-overhead, real-time visibility into network traffic while allowing all packets to continue through the networking stack (XDP_PASS).

---

Table of Contents

• Features
• Architecture
• Requirements
• Installation
• Building
• Usage
• Output Example
• Project Structure
• How It Works
• Packet Metadata
• Configuration
• Limitations
• Troubleshooting
• Future Improvements
• License

---

Features

• High-performance XDP packet inspection
• Zero-copy communication via eBPF Ring Buffer
• IPv4 packet monitoring
• TCP and UDP port extraction
• ICMP protocol identification
• Automatic protocol detection
• Dynamic IPv4 header parsing
• Safe verifier-compatible bounds checking
• Root privilege verification
• Graceful shutdown on SIGINT/SIGTERM
• Lightweight userspace written in Go

---

Architecture

             Incoming Packets
                     │
                     ▼
             Network Interface
                     │
                     ▼
              XDP eBPF Program
                     │
      ┌──────────────┴──────────────┐
      │ Parse Ethernet Header       │
      │ Parse IPv4 Header           │
      │ Parse TCP/UDP Header        │
      └──────────────┬──────────────┘
                     │
                     ▼
             Ring Buffer Map
                     │
                     ▼
               Go Userspace
                     │
                     ▼
             Console Output

---

Requirements

• Linux kernel with eBPF support
• XDP-enabled network driver
• Go 1.20+
• clang/LLVM
• libbpf headers
• root privileges

Required Go packages:

github.com/cilium/ebpf

---

Installation

Clone the repository:

git clone <repository-url>
cd <repository>

Install Go dependencies:

go mod tidy

---

Building

Generate Go bindings from the eBPF program:

go generate

Build the application:

go build -o ebpf-visualizer

---

Usage

Monitor the default interface (eth0):

sudo ./ebpf-visualizer

Monitor another interface:

sudo ./ebpf-visualizer -i ens33

Display help:

./ebpf-visualizer -h

---

Output Example

TCP:

[TCP ]    192.168.1.10:54231 → 142.250.72.46:443    len=60

UDP:

[UDP ]    192.168.1.15:60120 → 8.8.8.8:53           len=76

ICMP:

[ICMP]    192.168.1.20       → 1.1.1.1              len=84

---

Project Structure

.
├── bpf/
│   ├── packet_monitor.c  # XDP eBPF program
│   └── headers/          # Kernel headers used by bpf2go
├── main.go               # Userspace application
├── go.mod
├── go.sum
├── LICENSE
└── README.md

The C source lives in bpf/ rather than the package root. Go's build tooling rejects any package directory containing .c files unless cgo is explicitly enabled — even when, as here, the .c file is never meant to be compiled by go build at all (it's built separately by bpf2go/clang for the kernel, not by cgo). Keeping it in a subdirectory is what makes go install github.com/foxhackerzdevs/ebpf-visualizer@latest work at all.

---

How It Works

Kernel (XDP)

The XDP program performs the following steps:

1. Reads the Ethernet header.
2. Ensures the packet is IPv4.
3. Verifies all memory boundaries for verifier safety.
4. Parses the IPv4 header.
5. Calculates the dynamic IP header size using ihl.
6. Parses TCP or UDP headers when applicable.
7. Extracts:
   • Source IP
   • Destination IP
   • Source Port
   • Destination Port
   • Protocol
   • Packet Length
8. Writes the metadata into a Ring Buffer.
9. Returns XDP_PASS so packets continue through the normal networking stack.

---

Userspace

The Go application:

• Removes the memlock limit
• Loads the compiled eBPF object
• Attaches the XDP program
• Opens the Ring Buffer
• Reads events continuously
• Converts binary data into Go structures
• Prints packet information in a human-readable format

---

Packet Metadata

The kernel sends the following structure:

struct packet_meta {
    __u32 src_ip;
    __u32 dst_ip;
    __u16 src_port;
    __u16 dst_port;
    __u16 payload_len;
    __u8  protocol;
    __u8  pad;
};

Field	Description
src_ip	Source IPv4 address
dst_ip	Destination IPv4 address
src_port	TCP/UDP source port
dst_port	TCP/UDP destination port
payload_len	IPv4 total length
protocol	IP protocol number
pad	Alignment padding

---

Configuration

Interface

Default:

eth0

Custom:

-i <interface>

Example:

-i enp0s3

---

Supported Protocols

Protocol	Supported
IPv4	✅
TCP	✅
UDP	✅
ICMP	✅
IPv6	❌
ARP	❌

---

Safety Features

The XDP program includes verifier-friendly safety checks:

• Ethernet bounds validation
• IPv4 bounds validation
• Dynamic IP header length validation
• TCP header bounds validation
• UDP header bounds validation
• Ring buffer allocation failure handling
• Explicit structure padding initialization

---

Performance Characteristics

The monitor is optimized for high throughput:

• Runs entirely in the XDP hook
• Minimal packet parsing
• Zero-copy Ring Buffer communication
• No packet modifications
• No packet drops (always returns XDP_PASS)
• Low userspace overhead

---

Limitations

Current limitations include:

• IPv4 only
• No IPv6 support
• No packet payload capture
• Console output only
• No packet filtering
• No statistics aggregation
• No persistent logging

---

Troubleshooting

"This tool requires root privileges"

Run with:

sudo ./ebpf-visualizer

---

Interface not found

List available interfaces:

ip link

---

Failed to attach XDP

Possible reasons:

• Interface does not support XDP.
• Driver does not implement native XDP.
• Another XDP program is already attached.
• Insufficient permissions.

---

Ring Buffer Errors

Verify:

• Kernel supports BPF Ring Buffers.
• eBPF program loaded successfully.
• XDP attachment succeeded.

---

Future Improvements

Potential enhancements include:

• IPv6 support
• ARP parsing
• VLAN awareness
• DNS decoding
• HTTP inspection
• Packet filtering
• Prometheus metrics
• JSON output
• PCAP export
• Interactive terminal UI
• Flow tracking
• Per-interface statistics
• Packet rate monitoring
• eBPF maps for counters
• Prometheus exporter

---

License

The eBPF program is released under the GPL license:

char LICENSE[] SEC("license") = "GPL";

Refer to the project's LICENSE file for the complete licensing terms.

---

Acknowledgements

• Linux eBPF subsystem
• XDP (Express Data Path)
• Cilium eBPF Go library
• Linux Kernel networking stack