Text Mode ​

Purpose and Scope ​

This page details Text Mode (-m text), the default operating mode for eCapture's core TLS capture modules (tls, gotls, and gnutls). Text mode intercepts encrypted TLS socket read/write operations via eBPF probes, decrypts or captures payloads in memory, and prints human-readable plaintext events directly to standard output or a designated event address. It is designed for immediate interactive inspection of HTTP requests, responses, and arbitrary application-layer payloads without requiring external packet captures or decryption key files.

Sources:

• internal/probe/base/handlers/text_handler.go:26-34
• pkg/event_processor/iworker.go:175-229

Verified Text-Mode Commands ​

To run eCapture in text mode, specify the module (tls, gotls, or gnutls) along with -m text.

OpenSSL / BoringSSL (tls) ​

ecapture tls -m text -p 1234

Alternatively, targeting a specific shared library path:

ecapture tls -m text --libssl /usr/lib/x86_64-linux-gnu/libssl.so.1.1

Go Native TLS (gotls) ​

ecapture gotls -m text --pid 5678

GnuTLS (gnutls) ​

ecapture gnutls -m text -p 9012

Sources:

• internal/probe/base/handlers/text_handler.go:49-57

Default Standard Output and Optional --eventaddr ​

By default, Text Mode routes all formatted plaintext events to standard output (stdout) via writers.NewStdoutWriter().

When operating in distributed or automated environments, you can redirect captured events using the optional --eventaddr flag. Unlike --logaddr (which carries operational engine logs only), --eventaddr transmits the processed event stream to a remote TCP sink, WebSocket endpoint, or file descriptor.

Figure 1: Text Mode Output Routing Architecture

Sources:

• internal/probe/base/handlers/text_handler.go:49-57
• pkg/event_processor/processor.go:70-93

Expected Plaintext Events and Formatting ​

When an application reads or writes data through a hooked TLS session, eCapture dispatches a binary event structure (BaseEvent) which is subsequently processed by eventWorker and formatted by TextHandler.

Event Structure and Layout ​

Each event captures metadata including Process ID (PID), Thread ID (TID), Process Name (Comm), File Descriptor (Fd), TLS Version, and direction (Received vs Send).

Figure 2: Event Decoding and Formatting Entity Flow

An expected plaintext output for an HTTP request captured via tls or gotls resembles:

PID:469929, Comm:curl, TID:469929, Version:TLS1_3_VERSION, Received 308 bytes, Payload:
GET / HTTP/1.1
Host: example.com
User-Agent: curl/7.88.1
Accept: */*

Sources:

• pkg/event_processor/base_event.go:76-167
• internal/probe/base/handlers/text_handler.go:61-111

Simple Verification Flow ​

To verify that text-mode capture is functioning correctly, execute the following validation steps:

1. Start the Target Application: Launch a server or run a repeating client request against an HTTPS endpoint using OpenSSL, Go, or GnuTLS.
2. Execute eCapture: Run the text-mode probe with root privileges:
   bash

   sudo ecapture tls -m text -bb

3. Trigger Traffic: In a separate terminal, execute a request:
   bash

   curl -Iv https://www.example.com/

4. Confirm Output: Observe the terminal running eCapture. Plaintext HTTP headers and request bodies should appear instantly without requiring decryption keys or Wireshark.

Sources:

• pkg/event_processor/processor_test.go:31-114
• internal/probe/base/handlers/text_handler_test.go:133-157