Integration and Deployment ​

Purpose and Scope ​

This document provides production guidance for deploying and integrating eCapture's core TLS capture modules (tls, gotls, and gnutls). It details event forwarding mechanisms using --eventaddr and additive eCaptureQ streaming, runtime dynamic configuration via HTTP, sensitive artifact management, and performance evaluation strategies using built-in benchmarking tools.

Sources: docs/event-forward-api.md:1-20, docs/performance-benchmarks.md:1-12

1. Event Forwarding: --eventaddr and eCaptureQ ​

eCapture separates operational logging (--logaddr), raw captured event streams (--eventaddr), and structured real-time publishing (--ecaptureq).

Raw Event Forwarding with --eventaddr ​

The --eventaddr flag specifies the destination for the primary captured-event representation selected by capture modes (text, NSS Key Log, or pcapng).

• Supported targets: Standard output, local file paths, TCP sockets (tcp://host:port), or WebSocket connections (ws://host:port/path).
• Behavior: TCP destinations receive an ordered raw byte stream. WebSocket sinks send ordered binary frames that downstream receivers concatenate into a single artifact.

Sources: docs/event-forward-api.md:34-45

Additive Structured Streaming via eCaptureQ ​

The --ecaptureq flag starts a WebSocket server that streams structured runtime logs and captured business events as Protobuf-encoded LogEntry messages docs/event-forward-api.md:46-60.

eCaptureQ operates additively alongside --eventaddr: --eventaddr writes the raw format (e.g., pcapng or text), while eCaptureQ publishes typed domain events through pkg/ecaptureq/server.go docs/event-forward-api.md:61-71.

Figure 1: Event forwarding data flow bridging event decoding to the eCaptureQ publishing hub (pkg/ecaptureq/server.go and pkg/ecaptureq/hub.go).

Sources: docs/event-forward-api.md:1-71, pkg/ecaptureq/server.go:144-184, pkg/ecaptureq/hub.go:40-64

2. Runtime Dynamic Configuration via HTTP ​

eCapture supports updating runtime configuration parameters without restarting the process by exposing an HTTP control server docs/remote-config-update-api.md:1-21.

Enabling and Endpoints ​

• Enablement: Pass the --listen flag (e.g., --listen 127.0.0.1:28256) docs/remote-config-update-api.md:6-7.
• Endpoints: All configuration routes are HTTP POST requests accepting JSON payloads matching internal configuration structs docs/remote-config-update-api.md:9-28.
  • /tls, /openssl, /boringssl — OpenSSL / BoringSSL capture module
  • /gotls — Go native TLS capture module
  • /gnutls — GnuTLS capture module

Figure 2: HTTP control request routing to module configuration channels.

Response Codes ​

Responses return a unified JSON status structure defined in cli/http/resp.go docs/remote-config-update-api.md:100-119:

Sources: docs/remote-config-update-api.md:1-132, cli/http/resp.go:1-35

3. Sensitive Artifact Management and Security ​

Captured plaintext, NSS key log files, and pcapng files containing embedded TLS Decryption Secrets Blocks carry highly sensitive security data.

• Storage Permissions: Benchmark and capture artifact directories must be restricted using strict file permissions (0700) to prevent unauthorized local access docs/performance-benchmarks.md:93-117.
• Redaction and Cleanup: Captured plaintext logs must be reviewed, redacted, and securely purged after analysis. Never commit captured traffic artifacts to version control repositories docs/performance-benchmarks.md:115-116.

Sources: docs/performance-benchmarks.md:93-117

4. Performance Evaluation and Benchmarking ​

eCapture provides two validation layers for assessing performance overhead and event loss: userspace microbenchmarks and end-to-end kernel benchmarks docs/performance-benchmarks.md:1-12.

Userspace Microbenchmarks ​

Userspace microbenchmarks measure the OpenSSL userspace decode and text-output pipeline efficiency without loading eBPF bytecode docs/performance-benchmarks.md:5-6. Run them using Go test benches:

go test -run '^$' -bench '^BenchmarkTLSDataEvent' -benchmem \
  ./internal/probe/openssl

Functions such as BenchmarkTLSDataEventDecode internal/probe/openssl/event_benchmark_test.go:29-45 validate payload throughput and memory allocations per event decode iteration.

Sources: docs/performance-benchmarks.md:13-31, internal/probe/openssl/event_benchmark_test.go:29-45

End-to-End Kernel Benchmarking ​

The end-to-end benchmark harness (test/benchmark/tls/run_benchmark.sh) evaluates real uprobe attachment, perf-buffer ring pressure, decoder dispatch, and file-writer throughput under load docs/performance-benchmarks.md:7-11.

Key tunable parameters include:

• BENCH_MAP_PAGES: Configures the per-CPU perf reader page count passed to --mapsize docs/performance-benchmarks.md:65-74. Note that this is a page count, not a byte count (e.g., 8192 pages on 4 KiB page systems equates to 32 MiB per CPU).
• BENCH_FAIL_ON_LOSS: Set to 1 to enforce a zero-loss regression gate checking for missing request/response markers or nonzero perf_lost_samples docs/performance-benchmarks.md:67-111.

Sources: docs/performance-benchmarks.md:32-137, test/benchmark/tls/run_benchmark.sh:1-124