Keploy — How eBPF Intercepts Traffic to Auto-Generate API Tests

A CNCF project written in Go. 17k+ stars. Run keploy record once and it captures all API calls, DB queries, and external requests from your app, outputting them as YAML-based test cases + mocks.

The key is eBPF. No SDK to install, no code to modify. Every language eventually calls kernel syscalls (socket, connect, bind, sendmsg), so hooking there makes it language-agnostic.

Three-Layer Architecture

Agent layer — eBPF hooks + transparent proxy. Attaches to the kernel to intercept traffic.

Service layer — record, replay, mock, coverage orchestration. Core logic for capture/playback/comparison.

Platform layer — YAML storage, per-language coverage collection, Docker/Telemetry.

How eBPF Captures Traffic

Pre-compiled eBPF objects (bpf_x86_bpfel.o, bpf_arm64_bpfel.o) live in pkg/agent/hooks/linux/. Loaded via the cilium/ebpf Go library. No runtime compilation needed.

Key hooks:

sys_enter_socket tracepoint — intercepts socket creation syscalls to track new connections.

SockOps (cgroup-attached) — attached to the cgroupv2 path. The core hook that monitors all socket operations (connect, accept, etc.) within the cgroup.

connect4/connect6 — intercepts IPv4/IPv6 outbound connections.

cgBind4/cgBind6 — monitors bind() calls to detect which ports the app listens on.

BindEvents ring buffer — eBPF writes events to a ring buffer; Go userspace reads via ringbuf.NewReader.

The Core Trick: Destination Redirect

This is the clever part. Three shared eBPF maps are key:

clientRegistrationMap — registers the target app with eBPF.
agentRegistrationMap — registers the Keploy agent.
redirectProxyMap — maps source port → original destination (DestInfo struct: IPv4/IPv6 + port).

The eBPF program rewrites outgoing connection destinations to Keploy's local proxy (127.0.0.1:proxyPort). The real destination is stored in redirectProxyMap. The proxy calls GetDestinationInfo(srcPort) to find where traffic was originally headed.

From the app's perspective, it's connecting to the DB as usual. In reality, it's going through Keploy's proxy. The app code knows nothing.

Transparent Proxy Protocol Parsing

The transparent proxy at pkg/agent/proxy/ handles redirected traffic:

1. Accepts eBPF-redirected connections
2. Looks up original destination from eBPF maps
3. Identifies protocol from first bytes (registered parsers call MatchType())
4. Routes to the appropriate protocol handler

Supported protocols: HTTP, HTTP2, gRPC, MySQL (full wire protocol — connection phase, queries, prepared statements), PostgreSQL, MongoDB, Redis, Kafka. Generic binary capture as fallback.

TLS handled transparently via auto-generated CA certificates in pkg/agent/proxy/tls/.

Record Flow

pkg/service/record/record.go orchestrates:

1. Instrumentation.Setup() — loads eBPF hooks, starts proxy
2. Instrumentation.Run() — launches the target app
3. Three concurrent channels open:

• GetIncoming() — inbound API requests/responses → TestCase objects

• GetOutgoing() — outbound calls (DB, external APIs) → Mock objects

• GetMappings() — links which mocks belong to which test case

  1. Persisted as YAML. Test cases in testdb/, mocks in mockdb/.

Go's goroutines and channels are a perfect fit for this concurrent pipeline.

Replay Flow

pkg/service/replay/ executes tests:

1. Loads test cases + mocks from YAML
2. Loads mocks into proxy's in-memory DB (MockMemDb)
3. Sends recorded HTTP/gRPC requests to the app
4. App's outbound calls hit proxy → serves recorded mock responses
5. Compares actual vs expected responses
6. Denoising — auto-identifies noise fields (timestamps, random IDs) to exclude from comparison
7. Time freezing — freezes system time during replay

Coverage Calculation

pkg/platform/coverage/ has per-language implementations: Go, Java, Python, JavaScript, C#. Each hooks into native coverage tools (Go cover, Istanbul, coverage.py, JaCoCo, etc.).

AI Integration (utgen)

pkg/service/utgen/ provides LLM-based test expansion. Reads existing recordings + Swagger/OpenAPI schemas to generate missing field tests, boundary value tests, and type error tests.

What Happens When You Wrap Rails

keploy record -c "bundle exec rails s" — everything Rails does over the network gets recorded.

Captured:

• Incoming HTTP requests/responses (API endpoints) → become test cases

• PostgreSQL/MySQL queries → become mocks. Every SQL that ActiveRecord sends is captured at the wire protocol level

• Redis calls (cache, Sidekiq) → mocks

• External API calls (Faraday, Net::HTTP, etc.) → mocks

• Kafka/RabbitMQ messages → mocks

Not captured:

• SQLite — doesn't use network sockets. It's file I/O, so eBPF network hooks don't catch it

• File reads/writes

• In-memory operations

• Inter-process communication on localhost (Unix domain sockets partially supported)

Key point: eBPF only catches network socket syscalls. Anything over TCP/UDP gets captured; everything else doesn't. If Rails uses PostgreSQL, every SELECT/INSERT/UPDATE from ActiveRecord gets captured via PostgreSQL wire protocol, and during replay, mocks respond without a real DB.

Linux Only — The Reality for macOS/Windows Developers

eBPF is a Linux kernel feature. Not available on macOS. Not on Windows either (Keploy has experimental Windows hooks but they're not production-ready).

On macOS, Docker is mandatory:

keploy record -c "docker compose up" --containerName "app"

eBPF runs inside Docker Desktop's Linux VM. This adds overhead if you're used to native local development. Running in CI/CD on Linux containers works fine.