snoop/CHECKLIST.md

Milestone 1 Completion Checklist

Code Implementation ✅

• eBPF C program (pkg/ebpf/bpf/snoop.c)

  • Tracepoint for sys_enter_openat
  • Tracepoint for sys_enter_execve
  • Ring buffer for events (256KB)
  • Per-CPU heap for event building
  • Traced cgroups hash map
  • Cgroup filtering logic
  • Event structure (cgroup ID, PID, syscall, path)

• Go eBPF loader (pkg/ebpf/probe.go)

  • Load eBPF objects with cilium/ebpf
  • Attach tracepoints
  • Manage traced cgroups
  • Ring buffer reader
  • Event parsing
  • Cleanup on close

• Cgroup utilities (pkg/cgroup/discovery.go)

  • Get self cgroup ID
  • Get cgroup ID by path
  • Discovery interface
  • Self-excluding discovery stub

• Main application (cmd/snoop/main.go)

  • CLI flag parsing
  • Signal handling (SIGINT, SIGTERM)
  • Probe lifecycle management
  • Event display loop
  • Graceful shutdown

Build Infrastructure ✅

• Go module (go.mod)

  • cilium/ebpf dependency
  • golang.org/x/sys dependency

• Dockerfile

  • Multi-stage build
  • clang, llvm, libbpf-dev
  • eBPF code generation
  • Go build
  • Minimal runtime image

• Makefile

  • vmlinux target (generate vmlinux.h)
  • generate target (eBPF code gen)
  • build target
  • test target
  • docker-build target
  • clean target
  • Help text

• ko configuration (.ko.yaml)

  • Build settings
  • Base image

• .gitignore

  • Binary artifacts
  • Generated eBPF files
  • IDE files

Testing Infrastructure ✅

• Docker Compose (deploy/docker-compose.yaml)

  • Test app service
  • Snoop sidecar configuration
  • Volume mounts for cgroup/tracefs
  • Privileged mode

• Helper scripts

  • scripts/find-cgroup.sh - Find container cgroups
  • Executable permissions

• Unit tests

  • pkg/cgroup/discovery_test.go

• CI/CD (.github/workflows/build.yaml)

  • Ubuntu runner
  • Go setup
  • Dependency installation
  • vmlinux.h generation
  • eBPF code generation
  • Build step
  • Test step
  • go vet
  • staticcheck

Documentation ✅

• README.md

  • Project overview
  • Current status
  • Requirements
  • Build instructions
  • Testing overview
  • Project structure

• QUICKSTART.md

  • Prerequisites
  • Generate kernel headers
  • Build steps
  • Run example
  • Docker build option

• TESTING.md

  • Prerequisites
  • Setup instructions
  • Test 1: Basic tracing
  • Test 2: Multiple syscalls
  • Test 3: Docker Compose
  • Troubleshooting section
  • Success criteria

• STATUS.md

  • What's been done
  • What's left
  • Project structure
  • Design decisions
  • Known limitations
  • Next milestone preview

• CHECKLIST.md (this file)

• plan.md updates

  • Current status banner
  • Milestone 1 completion status
  • Files created list
  • Current status description

Milestone 2 Progress ⏳

• Additional syscalls (statx, newfstatat, faccessat, faccessat2, readlinkat, openat2, execveat)
• Path normalization logic
• Deduplication data structures
• JSON report output
• Prometheus metrics
• Path exclusion filtering
• Configuration via environment variables

Testing Required (Needs Linux) ⚠️

Cannot be completed on macOS, requires Linux system:

• Generate vmlinux.h from kernel
• Generate eBPF Go bindings
• Build snoop binary
• Load eBPF program (verify no errors)
• Trace test container
• Verify events captured
• Verify cgroup filtering works
• Test graceful shutdown
• Verify no kernel panics

How to Mark Milestone 1 Complete

Run the following on a Linux system (kernel 5.4+):

# 1. Setup
make vmlinux
make generate
make build

# 2. Run test
docker run -d --name test alpine sh -c "while true; do cat /etc/passwd > /dev/null; sleep 2; done"
CGROUP=$(./scripts/find-cgroup.sh test | grep "Cgroup Path:" | cut -d: -f2 | xargs)
sudo ./snoop -cgroup "$CGROUP"

# 3. Expected output
# Should see:
# [PID XXXX] [Cgroup YYYY] [Syscall 257] /etc/passwd
# (Repeating every 2 seconds)

# 4. Test filtering
# Snoop's own file accesses should NOT appear
# Only the test container's accesses

# 5. Test shutdown
# Press Ctrl+C - should exit cleanly

# 6. Cleanup
docker stop test
docker rm test

If all tests pass, Milestone 1 is complete! ✅

Statistics

• Lines of Code: ~450 lines (Go + C)
• Files Created: 20+
• Documentation: 5 markdown files
• Time to Complete: ~1 session
• Dependencies: 2 (cilium/ebpf, golang.org/x/sys)