Glossary ​

This page provides definitions for codebase-specific terminology, eBPF domain concepts, and technical jargon used throughout the eCapture project. It serves as a reference for onboarding engineers to understand the implementation details and data flow of the system.

eBPF and Kernel Concepts ​

BTF (BPF Type Format) ​

A metadata format which describes the data types of BPF programs and the Linux kernel. eCapture uses BTF to support CO-RE (Compile Once – Run Everywhere), allowing a single binary to run on different kernel versions without recompilation.

• Code Pointer: globalConf.BtfMode in cli/cmd/root.go:163-163.
• Implementation: eCapture checks for BTF availability to decide between loading CO-RE or non-CO-RE bytecode.

CO-RE vs. Non-CO-RE ​

• CO-RE: Uses vmlinux.h and BPF relocations. Enabled via the #ifndef NOCORE block in kern/ecapture.h:18-26.
• Non-CO-RE: Legacy mode for kernels without BTF support. It uses standard Linux headers and requires specific bytecode for specific kernel versions. Defined in kern/ecapture.h:28-88.

Uprobe / Uretprobe ​

User-space probes. eCapture attaches these to functions in shared libraries (like SSL_read in OpenSSL) to intercept plaintext data.

• Code Pointer: kern/openssl_masterkey.h:163-164 (uprobe for master key extraction).

TC (Traffic Control) Classifier ​

eBPF programs attached to the network interface's egress/ingress hooks. Used in eCapture for pcap mode to capture raw packets.

• Code Pointer: capture_packets function in kern/tc.h:136-199.

eCapture Subsystems ​

EventProcessor ​

The central hub in user-space that receives raw bytes from eBPF maps and dispatches them to specific workers.

• Code Pointer: EventProcessor struct in pkg/event_processor/processor.go.

EventWorker ​

A per-connection or per-thread worker that handles the stateful reassembly and parsing of captured data. It maintains a buffer (payload) and an IParser.

• Code Pointer: eventWorker struct in pkg/event_processor/iworker.go:69-88.
• Functions: Display() pkg/event_processor/iworker.go:174-227 and Run() pkg/event_processor/iworker.go:261-265.

IParser ​

An interface for protocol-specific parsers (e.g., HTTP/1.1, HTTP/2). It transforms raw byte streams into structured logs.

• Code Pointer: IParser interface in pkg/event_processor/iparser.go.

eCaptureQ ​

A WebSocket-based remote event distribution system. It allows eCapture to act as a server, pushing captured events to remote clients using Protobuf.

• Code Pointer: pkg/ecaptureq/ and globalConf.EcaptureQ in cli/cmd/root.go:170-170.

TLS & Crypto Terminology ​

Master Secret / Keylog ​

The secret material used to derive encryption keys for a TLS session. eCapture extracts these to allow Wireshark to decrypt traffic.

• Code Pointer: mastersecret_bssl_t in kern/boringssl_masterkey.h:33-52 and mastersecret_gotls_t in kern/gotls_kern.c:50-57.

SSL/TLS Plaintext Fragment ​

The decrypted data captured from library functions like SSL_read and SSL_write. eCapture limits this to MAX_DATA_SIZE_OPENSSL (16KB) to fit within eBPF map constraints.

• Code Pointer: kern/common.h:39-39.

Code Entity Mapping Diagrams ​

Data Path: From Kernel Hook to User Output ​

This diagram bridges the gap between the C-based kernel probes and the Go-based processing pipeline.

Sources: pkg/event_processor/iworker.go:153-161, pkg/event_processor/iworker.go:174-227, kern/openssl.h:187-189, kern/tc.h:58-63.

GoTLS Implementation: Symbol to Struct Mapping ​

GoTLS capture relies on specific offsets in the Go runtime and TLS library.

Sources: kern/gotls_kern.c:31-48, kern/gotls_kern.c:132-144, kern/gotls_kern.c:162-165.

Build System Vocabulary ​

Sources: variables.mk:36-36, variables.mk:65-68, variables.mk:236-240, main.go:4-4.