Skip to content

9.2-glossary.md

Latest commit

 

History

History
163 lines (127 loc) · 10.9 KB

9.2-glossary.md

File metadata and controls

163 lines (127 loc) · 10.9 KB
Raw

Glossary

Relevant source files

The following files were used as context for generating this wiki page:

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.

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.

eCapture Subsystems

EventProcessor

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

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.

IParser

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

eCaptureQ

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

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.

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 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.

graph TD
    subgraph "Kernel Space (C)"
        A["uprobe: SSL_read/write"] -->|bpf_perf_event_output| B[("BPF Map: tls_events")]
        C["TC Hook: capture_packets"] -->|bpf_perf_event_output| D[("BPF Map: skb_events")]
    end

    subgraph "User Space (Go)"
        B --> E["EventProcessor.Run()"]
        D --> E
        E -->|UUID Affinity| F["eventWorker.Write()"]
        F --> G["eventWorker.parser.Write()"]
        G --> H["eventWorker.Display()"]
        H --> I["CollectorWriter / Protobuf Encoder"]
        I --> J["Stdout / File / WebSocket"]
    end
Loading

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.

graph LR
    subgraph "Go Binary (ELF Space)"
        SYM1["crypto/tls.(*Conn).Write"] 
        SYM2["crypto/tls.(*Conn).Read"]
    end

    subgraph "eCapture Probe (Code Space)"
        P1["probe_tls_write"] -->|uprobe| SYM1
        P2["probe_tls_read"] -->|uprobe| SYM2
        
        subgraph "Struct Mapping (kern/gotls_kern.c)"
            E1["go_tls_event"]
            F1["extract_fd_from_netfd_ptr"]
            F2["extract_addr_from_netfd_ptr"]
        end
        
        P1 --> E1
        P2 --> E1
        E1 --> F1
        E1 --> F2
    end
Loading

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

Build System Vocabulary

Term Definition Code Reference
BYTECODE_FILES Makefile variable defining which eBPF programs to compile. variables.mk:36-36
go-bindata Tool used to embed eBPF .o or .nocore files into the Go binary. main.go:4-4
EXTRA_CFLAGS Compiler flags for eBPF programs, including optimization levels (-O2). variables.mk:236-240
TARGET_TAG Build tag used to differentiate between linux and ecap_android. variables.mk:65-68

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