Architecture and Probe Development ​

This developer-facing wiki page provides a high-level architectural overview of ecapture's core TLS capture modules (tls, gotls, and gnutls), their lifecycle management, event/output pipelines, and extension patterns.

For deep technical details, implementations, and ABI specifications, please refer to the dedicated child pages:

• TLS Capture Architecture
• Probe Framework and Lifecycle
• Event and Output Pipeline
• Extending a TLS Probe

5.1. TLS Capture Architecture ​

The ecapture agent captures TLS traffic across OpenSSL/BoringSSL (tls), Go native TLS (gotls), and GnuTLS (gnutls) by attaching eBPF programs (uprobes, uretprobes, and TC hooks) to target binaries or shared libraries. The architecture resolves symbols and library paths, extracts payload or key material, and converts kernel-space byte structures into user-space events via perf buffers or ring buffers.

The shared runtime flow connects command execution, factory creation, manager setup, and event decoding as illustrated below:

For comprehensive details on eBPF attachments, symbol resolution, and C/Go event ABIs, see TLS Capture Architecture.

Sources: main.go, internal/probe/openssl/openssl_probe.go:61-163, internal/probe/gotls/gotls_probe.go:70-156, internal/probe/gnutls/gnutls_probe.go:48-116

5.2. Probe Framework and Lifecycle ​

Concrete probes (openssl.Probe, gotls.Probe, and gnutls.Probe) embed base.BaseProbe internal/probe/openssl/openssl_probe.go:46-47 to inherit shared logging, dispatcher management, reader tracking, and shutdown orchestration. Factory registration occurs during package initialization via Go's init() functions, linking CLI commands directly to probe constructors.

The lifecycle follows a strict sequence: configuration validation, initialization, bytecode selection and asset loading via assets.Asset() internal/probe/openssl/openssl_probe.go:126-129, eBPF manager initialization and attachment, event map retrieval, and reader execution. During teardown, resources are released safely in reverse order.

For details on factory registration, BaseProbe lifecycle hooks, reader tracking, and concurrency management, see Probe Framework and Lifecycle.

Sources: internal/probe/openssl/openssl_probe.go:46-209, internal/probe/gotls/gotls_probe.go:53-211, internal/probe/gnutls/gnutls_probe.go:39-167

5.3. Event and Output Pipeline ​

Captured binary events flow from eBPF perf/ring-buffer readers through EventDecoder.Decode() into the events.Dispatcher. The dispatcher performs synchronous fan-out to registered handlers corresponding to the selected output mode (text, keylog, or pcapng).

The decoupled output architecture routes records to ByteSink destinations (stdout, files, TCP streams, or binary WebSockets) while publishing typed metadata independently via eCaptureQ:

For details on event decoding, dispatcher mechanics, ByteSink transports, and eCaptureQ publication, see Event and Output Pipeline.

Sources: docs/agent/output-pipeline.md, internal/output/writers/factory.go:77-176

5.4. Extending a TLS Probe ​

Extending existing core TLS modules or introducing new capabilities requires maintaining atomic alignment across C eBPF source definitions, ebpfmanager mappings, global constants, and Go decoding logic. Developers must preserve CO-RE (_core.o) and non-CO-RE (_noncore.o) asset paths as well as architecture-specific build tags (linux,netgo,ebpfassets,dynamic).

When modifying or adding probe features, ensure that validation rules remain idempotent and that mode-specific handlers respect the separation between captured payloads and operational logging.

For step-by-step guidance on extending tls, gotls, or gnutls, see Extending a TLS Probe.

Sources: AGENTS.md, docs/agent/probe-development.md, internal/probe/openssl/openssl_probe.go:44-163