Skip to content

CLAUDE.md

Latest commit

 

History

History
76 lines (58 loc) · 2.66 KB

CLAUDE.md

File metadata and controls

76 lines (58 loc) · 2.66 KB

CLAUDE.md - Project Context for Claude Code

This file is automatically read by Claude Code at the start of each session to understand the project context.

Project Overview

xdpcap is a high-performance packet capture tool using XDP/eBPF that captures only packet headers (L2-L4), not payload data.

Tech Stack

  • Language: Go 1.21+
  • eBPF: XDP program written in C, compiled with clang
  • Libraries:
    • github.com/cilium/ebpf - eBPF program loading and map management
    • github.com/google/gopacket - pcap file writing
    • github.com/spf13/cobra - CLI framework
    • gopkg.in/yaml.v3 - Configuration parsing

Project Structure

xdpcap/
├── cmd/xdpcap/main.go           # CLI entry point
├── internal/
│   ├── config/config.go         # YAML config parsing
│   ├── capture/capture.go       # eBPF loading, ring buffer reader
│   ├── capture/xdpcap_bpf.go    # Stub for non-Linux (bpf2go generates real one)
│   └── writer/pcap.go           # Time-rotated pcap writer
├── bpf/xdpcap.c                 # XDP/eBPF program (C)
├── configs/xdpcap.yaml.example  # Example configuration
├── Makefile
└── README.md

Key Design Decisions

  1. Header capture: Max 512 bytes per packet (L2-L7 headers including HTTP, TLS, DNS)
  2. Flow filtering: Hash map lookup to exclude specified flows from capture
  3. Ring buffer: Zero-copy transfer from kernel to userspace
  4. Time-based rotation: Configurable pcap file rotation interval
  5. XDP_PASS: Non-intrusive, always passes packets through

Build Dependencies (Ubuntu/Debian)

sudo apt-get install -y clang llvm libbpf-dev linux-tools-common linux-tools-$(uname -r)
# Or: sudo make deps-system

Build Commands

make deps-system  # Install system build dependencies (requires sudo)
make deps         # Download Go module dependencies
make vmlinux      # Generate vmlinux.h from kernel BTF
make generate     # Compile eBPF and generate Go bindings (Linux only)
make build        # Build Go binary
make all          # Both generate and build
make install      # Install to /usr/local/bin

Configuration

Default config location: /etc/xdpcap/xdpcap.yaml

Key config fields:

  • interface: Network interface to capture from
  • output_dir: Directory for pcap files
  • rotation_interval: How often to rotate files (e.g., "5m")
  • exclude_flows: List of flows to exclude from capture

Development Notes

  • The internal/capture/xdpcap_bpf.go stub is for non-Linux development
  • On Linux, go generate creates xdpcap_bpfel.go with real eBPF bindings
  • eBPF program requires Linux kernel 5.8+ for ring buffer support