mirror of
https://github.com/imjasonh/snoop
synced 2026-07-14 19:35:42 +00:00
No description
87dab9839a
Implement comprehensive ring buffer overflow handling: - Add dropped_events BPF map to track overflow in kernel space - Create submit_event() helper that checks bpf_ringbuf_output() return value and atomically increments drop counter on failure - Add Drops() method to read drop counter from eBPF map - Add snoop_events_dropped_total Prometheus metric - Track drop deltas and log warnings when overflow occurs - Include drop count in JSON reports Ring buffer overflows can occur under high load when events are generated faster than userspace can consume them. This implementation provides full observability into overflow events without data loss of the drop count itself. Signed-off-by: Jason Hall <jason@chainguard.dev> |
||
|---|---|---|
| .github/workflows | ||
| cmd/snoop | ||
| deploy | ||
| pkg | ||
| scripts | ||
| .gitignore | ||
| .ko.yaml | ||
| CHECKLIST.md | ||
| CLAUDE.md | ||
| Dockerfile | ||
| go.mod | ||
| go.sum | ||
| Makefile | ||
| plan.md | ||
| prompt.md | ||
| QUICKSTART.md | ||
| README.md | ||
| STATUS.md | ||
| SUMMARY.md | ||
| TESTING.md | ||
Snoop
A lightweight eBPF-based sidecar that observes file access patterns in production containers.
Current Status: Milestone 1 - eBPF Proof of Concept
This is an initial proof of concept demonstrating:
- Basic eBPF program tracing
openatandexecvesyscalls - Cgroup-based filtering to trace specific containers
- Userspace Go loader using cilium/ebpf
- Ring buffer for efficient event delivery
Requirements
Build Requirements
- Go 1.21+
- clang (for eBPF compilation)
- llvm (for eBPF bytecode generation)
- Linux kernel 5.4+ with BTF support
- Linux headers or vmlinux.h
Runtime Requirements
- Linux with kernel 5.4+
- Cgroup v2 enabled
- Capabilities:
CAP_SYS_ADMIN,CAP_BPF(kernel 5.8+),CAP_PERFMON(kernel 5.8+)
Building
Generate eBPF code
First, generate vmlinux.h from your running kernel (on a Linux system):
bpftool btf dump file /sys/kernel/btf/vmlinux format c > pkg/ebpf/bpf/vmlinux.h
Then generate the Go bindings:
go generate ./pkg/ebpf/bpf
Build the binary
go build -o snoop ./cmd/snoop
Build with Docker
docker build -t snoop:latest .
Testing Locally with Docker Compose
- Start the test application:
cd deploy
docker compose up -d app
- Find the cgroup path for the app container:
../scripts/find-cgroup.sh deploy-app-1
- Run snoop to trace the container:
sudo ./snoop -cgroup <cgroup-path-from-step-2>
You should see file access events like:
[PID 1234] [Cgroup 567] [Syscall 257] /etc/passwd
[PID 1234] [Cgroup 567] [Syscall 257] /usr/bin/ls
Project Structure
snoop/
├── cmd/snoop/ # Main entry point
├── pkg/
│ ├── ebpf/ # eBPF loader and management
│ │ └── bpf/ # eBPF C code
│ └── cgroup/ # Cgroup discovery
├── deploy/ # Deployment configurations
├── scripts/ # Helper scripts
└── plan.md # Full technical design
Development Status
See plan.md for the complete technical design and roadmap.
Completed
- Basic Go project structure
- eBPF program for openat and execve tracing
- Cgroup-based filtering
- Ring buffer event delivery
- Basic userspace loader
Next Steps
- Generate vmlinux.h on Linux system
- Test on Linux with Docker
- Add more syscalls (stat, access, readlink)
- Path normalization
- Deduplication
- JSON report output
Notes
- This project is in early proof-of-concept stage
- eBPF development requires Linux; development on macOS is limited to Go code
- For full functionality, build and test on a Linux system with kernel 5.4+