What It Is
Lodestone is a network packet sniffer and analyzer built from scratch in C for Linux. It captures live traffic off a network interface, parses it through every layer of the stack (Ethernet → IP → TCP/UDP → DNS/HTTP), and can detect anomalies like port scans, SYN floods, and ARP spoofing in real time. Output goes to the terminal, PCAP files (Wireshark-compatible), or structured logs in CSV/JSON/XML.
The whole thing is about 5,600 lines of C across a cleanly layered architecture.
Why I Built It
I wanted to understand the Linux networking stack at the lowest level — not through abstractions, but by opening raw sockets and parsing bytes off the wire myself. Tools like tcpdump and Wireshark are excellent, but building my own forced me to deal with every detail: Ethernet framing, IP fragmentation, TCP flags, DNS record formats, endianness, and kernel buffer management.
Architecture
The codebase follows a four-layer design that mirrors the network stack itself:
Capture layer handles two modes of packet acquisition. The standard path uses AF_PACKET raw sockets. The high-performance path uses TPACKET_V3 with memory-mapped ring buffers for zero-copy capture — the kernel writes packets directly into userspace memory, avoiding read() syscall overhead entirely. This path targets 10Gbps+ workloads. Both modes support BPF filters applied at the kernel level so irrelevant packets never reach userspace.
Parser layer is a chain of protocol-specific decoders: Ethernet, ARP, IPv4, IPv6 (with extension header walking), TCP, UDP, ICMP, ICMPv6, DNS, and HTTP. Each parser extracts header fields into structs and hands off the payload to the next layer. The IPv6 parser handles the extension header chain correctly, which was trickier than expected — you have to walk a linked list of variable-length headers before you reach the transport layer.
Analysis layer provides TCP stream reassembly and real-time anomaly detection. The stream tracker maintains per-connection state (SYN/ACK/FIN tracking, sequence number ordering) using a hash table keyed on the 4-tuple. The anomaly detector watches for patterns like rapid SYN packets from one source (scan detection), SYN flood signatures, and ARP reply storms (spoofing detection).
Output layer supports four display modes (brief, detailed, hex dump, full decode), a PCAP writer for offline analysis in Wireshark, and structured logging to text, CSV, JSON, or XML. Statistics tracking reports protocol distributions and top talkers.
Key Decisions
Zero-copy mmap capture was the most impactful design choice. Standard recv() on a raw socket copies each packet from kernel to userspace — fine at low rates, but a bottleneck at high traffic. With TPACKET_V3, the kernel and userspace share a ring buffer via mmap(). The kernel writes directly into the shared region; userspace just advances a pointer. This eliminates one copy per packet and significantly reduces syscall overhead.
BPF filtering at the kernel level means packets that don't match the filter expression are dropped before they ever reach userspace. This is critical for targeted captures on busy links — without it, the application would waste cycles parsing and discarding irrelevant traffic.
Hash-based connection tracking for TCP streams uses a simple but effective approach: hash the source/destination IP and port 4-tuple to index into a fixed-size table with chaining for collisions. This keeps stream lookups at O(1) amortized cost even with thousands of concurrent connections.
What I Learned
Writing a packet parser teaches you how fragile assumptions about "well-formed" data are. Real network traffic includes truncated packets, malformed headers, unusual option fields, and protocol violations. Defensive parsing — checking lengths before every access, validating header fields, handling edge cases — is non-negotiable when you're processing raw bytes from the wire.
I also gained practical experience with Linux-specific APIs (AF_PACKET, TPACKET_V3, setsockopt for BPF) that don't exist on other platforms, which is why Lodestone is Linux-only by design rather than by accident.
What's Next
Planned additions include Windows/macOS portability, additional protocol parsers (TLS handshake inspection, DHCP, QUIC), a GUI frontend, and exploring ML-based anomaly detection for more sophisticated intrusion patterns.