snoop/TESTING.md

Testing Snoop

Since Snoop uses eBPF, it requires a Linux system for testing. This document describes how to test the proof of concept.

Prerequisites

• Linux system with kernel 5.4+
• Docker or Podman
• Root/sudo access
• bpftool (for generating vmlinux.h)

Setup on Linux

1. Generate vmlinux.h (required once):

   make vmlinux
   

   This extracts kernel type information needed for eBPF compilation.

2. Generate eBPF code:

   make generate
   

   This compiles the C eBPF program and generates Go bindings.

3. Build snoop:

   make build
   

Testing with Docker

Test 1: Basic File Access Tracing

1. Start a test container:

   docker run -d --name test-app alpine:latest sh -c \
     "while true; do cat /etc/passwd > /dev/null; sleep 2; done"
   

2. Find the container's cgroup:

   ./scripts/find-cgroup.sh test-app
   

   This will output something like:

   Container: test-app
   Container ID: abc123...
   Cgroup Path: /system.slice/docker-abc123.scope
   
   To trace this container, run snoop with:
     snoop -cgroup '/system.slice/docker-abc123.scope'
   

3. Run snoop (requires root):

   sudo ./snoop -cgroup '/system.slice/docker-abc123.scope'
   

4. Expected output:

   Loading eBPF program...
   eBPF program loaded successfully
   Tracing cgroup: /system.slice/docker-abc123.scope (ID: 12345)
   Waiting for events (press Ctrl+C to exit)...
   [PID 1234] [Cgroup 12345] [Syscall 257] /etc/passwd
   [PID 1234] [Cgroup 12345] [Syscall 257] /bin/sh
   [PID 1234] [Cgroup 12345] [Syscall 257] /bin/cat
   

5. Verify cgroup filtering works:

   • Snoop's own file accesses should NOT appear in the output
   • Only the test container's accesses should be shown

6. Cleanup:

   docker stop test-app
   docker rm test-app
   

Test 2: Multiple Syscalls

1. Start a more active container:

   docker run -d --name test-busy alpine:latest sh -c \
     "while true; do \
       ls /usr/bin > /dev/null; \
       cat /etc/os-release > /dev/null; \
       /bin/sh -c 'echo test' > /dev/null; \
       sleep 1; \
     done"
   

2. Trace it:

   CGROUP=$(./scripts/find-cgroup.sh test-busy | grep "Cgroup Path:" | cut -d: -f2 | xargs)
   sudo ./snoop -cgroup "$CGROUP"
   

3. Expected output:

   • Should see both openat (syscall 257) and execve (syscall 59) events
   • Paths like /usr/bin/ls, /bin/sh, /etc/os-release

4. Cleanup:

   docker stop test-busy
   docker rm test-busy
   

Test 3: Docker Compose Test Environment

1. Start the test environment:

   cd deploy
   docker compose up -d app
   

2. Get the cgroup:

   CGROUP=$(../scripts/find-cgroup.sh deploy-app-1 | grep "Cgroup Path:" | cut -d: -f2 | xargs)
   echo "Cgroup: $CGROUP"
   

3. Run snoop:

   cd ..
   sudo ./snoop -cgroup "$CGROUP"
   

4. Stop the test environment:

   cd deploy
   docker compose down
   

Troubleshooting

"failed to load eBPF program"

• Ensure you have CAP_SYS_ADMIN capability (run with sudo)
• Verify kernel version: uname -r (need 5.4+)
• Check if BTF is available: ls /sys/kernel/btf/vmlinux

"cgroup v2 not found"

• Verify cgroup v2 is enabled: mount | grep cgroup2
• If not mounted: sudo mount -t cgroup2 none /sys/fs/cgroup

"No events appearing"

• Verify the container is actually running: docker ps
• Check if the cgroup path is correct: cat /proc/<container-pid>/cgroup
• Ensure the container is doing file operations

"cannot find vmlinux.h"

• Run make vmlinux to generate it
• If bpftool is not available: sudo apt-get install linux-tools-generic

Success Criteria

For Milestone 1 to be complete, the following must work:

1. ✅ Snoop loads without errors
2. ✅ File access events are captured from target container
3. ✅ Cgroup filtering works (snoop's own accesses don't appear)
4. ✅ Both openat and execve syscalls are traced
5. ✅ Graceful shutdown on Ctrl+C
6. ✅ No kernel panics or system instability

Next Steps

After Milestone 1 testing is complete:

• Add more syscalls (stat, access, readlink)
• Implement path normalization
• Add deduplication
• Create JSON report output
• Add Prometheus metrics