Skip to content

AGENTS.md

Latest commit

 

History

History
72 lines (64 loc) · 5.33 KB

AGENTS.md

File metadata and controls

72 lines (64 loc) · 5.33 KB
Raw

AGENTS.md — AI Coding Agent Guide for eCapture

Project Overview

eCapture is an eBPF-based tool that captures SSL/TLS plaintext, bash/zsh commands, and SQL queries without CA certificates. It runs only on Linux/Android (x86_64 kernel ≥4.18, aarch64 ≥5.5) and requires root. These kernel version requirements apply per CPU architecture regardless of whether the OS is Linux or Android. Code editing can be done on any OS, but compilation and execution must happen on a Linux machine (physical, VM, or remote server via SSH).

Architecture

main.go → cli/ (cobra commands) → internal/factory → internal/probe/{openssl,bash,gotls,...}
                                                      ↕
                                              kern/*.c (eBPF C programs)
                                                      ↓ compiled to
                                              bytecode/*.o → assets/ebpf_probe.go (embedded via go-bindata)
  • kern/ — eBPF C source files. One per library version (e.g., openssl_3_4_1_kern.c). Shared headers: common.h, ecapture.h, openssl_masterkey*.h.
  • internal/domain/ — Core interfaces: Probe, Event, Configuration, EventDispatcher.
  • internal/probe/ — Probe implementations. Each probe has config.go, event.go, register.go, and *_probe.go. They embed base.BaseProbe (Template Method pattern).
  • internal/factory/ — Factory pattern. Probes self-register via init() in register.go (see internal/probe/openssl/register.go).
  • internal/events/ — Observer pattern event dispatcher.
  • internal/errors/ — Structured error types with error codes (e.g., ErrCodeProbeStart = 202).
  • internal/output/ — Writers (file, pcap, keylog, tcp, websocket) and encoders (json, plain, protobuf).
  • cli/cmd/ — One file per subcommand (tls.go, bash.go, gotls.go, etc.). Commands wire probe config flags and invoke the factory.
  • pkg/event_processor/ — HTTP/2 request/response parsing from captured TLS data.
  • assets/ — ebpf_probe_stub.go (build tag !ebpfassets) provides stubs; real ebpf_probe.go is generated by make assets.

Build System (Linux only)

The build must run on Linux. Key commands via SSH to the remote server:

make env          # Show all build variables and tool versions
make all          # Full build: eBPF (CO-RE + noncore) → assets → binary
make nocore       # Build without CO-RE (uses kernel headers)
make build        # Go binary only (after eBPF/assets are ready)
make clean        # Wipe bin/, bytecode/*.o, assets/ebpf_probe.go
  • Cross-compile: CROSS_ARCH=arm64 make all (on x86_64 host)
  • Android: ANDROID=1 make all
  • Build tags: production binary uses -tags 'linux,netgo,ebpfassets,dynamic'
  • Static linking: libpcap is built as a static lib in lib/libpcap/ and linked via CGO
  • Toolchain requirements: Go ≥1.24, Clang ≥9, bpftool, llc
  • Build variables are in variables.mk; build functions in functions.mk

Testing

# Unit tests (on Linux)
make test-race                    # go test -race -tags dynamic,ebpfassets ./...

# E2E tests (require root + running system)
make e2e-basic                    # bash, tls, gnutls, gotls
make e2e-advanced                 # pcap/keylog/text modes, edge cases
make e2e-bash                     # Single module test
  • E2E tests live in test/e2e/ and share common.sh (kernel version checks, root checks, timeout helpers).
  • Tests require sudo and a real Linux kernel with eBPF support.

Adding a New Probe — Checklist

  1. Create internal/probe/<name>/config.go — embed *config.BaseConfig, add probe-specific fields, implement Validate()
  2. Create internal/probe/<name>/event.go — define event structs with DecodeFromBytes() and Validate()
  3. Create internal/probe/<name>/<name>_probe.go — embed *base.BaseProbe, implement Initialize(), Start(), Stop(), Close()
  4. Create internal/probe/<name>/register.go — call factory.RegisterProbe() in init()
  5. Add eBPF C source in kern/<name>_kern.c, add target to TARGETS list in variables.mk
  6. Add CLI subcommand in cli/cmd/<name>.go, register flags and wire to factory
  7. Add _test.go files for unit tests

Key Conventions

  • Build tags: eBPF asset code uses //go:build ebpfassets; stub uses //go:build !ebpfassets. Always include correct tags.
  • Error handling: Use internal/errors package (structured codes), not raw fmt.Errorf. Add context with .WithContext().
  • Logging: Use internal/logger (wraps zerolog), not fmt.Println or log.
  • eBPF map naming: Maps in C kern files correspond to decoder registrations in Go probe code via mapNameToDecoder.
  • OpenSSL version mapping: Each supported version has its own kern/openssl_X_Y_Z_kern.c file with struct offsets specific to that version. The probe's config.go selects the correct BPF object file based on detected library version.
  • Platform guards: All shell scripts and Makefiles must check for Linux and kernel version before execution. Never assume macOS can build or run.
  • Format code: make format (uses clang-format with Google style, 120 col limit) for C; standard gofmt for Go.
  • replace directive: go.mod replaces github.com/google/gopacket with a fork github.com/cfc4n/gopacket.