Output Formats (text / pcap / keylog) ​

eCapture supports three primary output modes for capturing and analyzing data: Text, Pcap/Pcapng, and Keylog. These modes allow users to choose between immediate human-readable terminal output, professional network analysis via Wireshark, or cryptographic secret extraction for post-capture decryption.

1. Output Mode Overview ​

The output mode is controlled via the -m or --model flag available in most probes (e.g., tls, gotls, gnutls).

Data Flow Architecture ​

The following diagram illustrates how eBPF events from the kernel are transformed into different output formats through the userspace pipeline.

Figure 1: Event to Output Pipeline

Sources: cli/cmd/tls.go:53-55, internal/probe/base/handlers/pcap_handler.go:126-159, internal/output/writers/pcap_writer.go:161-226

2. Text Mode (-m text) ​

Text mode is the default behavior. It captures the plaintext arguments of functions like SSL_read and SSL_write and prints them directly.

• Implementation: Data is read from the eBPF perf buffer, decoded into a string or hex format, and sent to the FileWriter or Stdout.
• Formatting: Supports --hex for hexadecimal dumps and --json for structured logging.
• Example:
  bash

  ecapture tls -m text --pid 1234

Sources: cli/cmd/tls.go:53, internal/output/writers/file_writer.go:27-33

3. Pcap/Pcapng Mode (-m pcap) ​

In this mode, eCapture attaches eBPF programs to the TC (Traffic Control) subsystem to capture raw network packets. It uses the PCAPNG format, which is more extensible than legacy PCAP.

Implementation Details ​

1. TC Attachment: The probe attaches to a network interface (specified by -i). cli/cmd/tls.go:56
2. Packet Capture: Raw packets are sent to userspace via the skb_events perf map. kern/tc.h:58-63
3. Metadata Injection: eCapture uses pcapgo.NgWriter to create a PCAPNG file. It includes interface descriptions and comments identifying eCapture as the source. internal/output/writers/pcap_writer.go:64-80
4. Interface Indexing: By default, the monitored interface is set to index 0 in the pcapng header to ensure compatibility with Wireshark. internal/output/writers/pcap_writer.go:142-147

CLI Example ​

# Capture TLS traffic on eth0 and save to pcapng
ecapture tls -m pcap -i eth0 -w capture.pcapng tcp port 443

Sources: internal/probe/base/handlers/pcap_handler.go:106-123, internal/output/writers/pcap_writer.go:39-53

4. Keylog Mode (-m keylog) ​

Keylog mode extracts TLS secrets (Master Secrets, Client Randoms) directly from the memory of the target process. These secrets are formatted as NSS Key Log entries.

Why use Keylog? ​

While text mode shows you the data eCapture saw, keylog mode allows you to use a standard tool like tcpdump to capture traffic and Wireshark to decrypt it later using the generated key file.

Secret Labels Supported ​

eCapture supports both TLS 1.2 and TLS 1.3 secret labels:

• CLIENT_RANDOM (TLS 1.2)
• CLIENT_HANDSHAKE_TRAFFIC_SECRET (TLS 1.3)
• SERVER_HANDSHAKE_TRAFFIC_SECRET (TLS 1.3)
• EXPORTER_SECRET

Integration with Pcapng (DSB) ​

When using -m pcap, eCapture automatically embeds these keys into the PCAPNG file using Decryption Secrets Blocks (DSB). This means the resulting file can be opened in Wireshark and decrypted without providing an external key file.

Figure 2: DSB Serialization Logic

Logic note: eCapture delays flushing packets for up to 3 seconds to ensure the DSB (key) appears before the encrypted packets in the file stream. internal/output/writers/pcap_writer.go:171-184

CLI Example ​

# Save keys to a separate file
ecapture tls -m keylog -k my_keys.log

Sources: pkg/util/hkdf/hkdf.go:49-57, internal/output/writers/pcap_writer.go:210-226

5. Output Configuration Flags ​

Users can combine encoders and targets using the following flags:

Advanced: Log Rotation ​

The FileWriter supports log rotation via the roratelog package, allowing for production-grade auditing without filling up disk space. internal/output/writers/file_writer.go:56-65

Sources: cli/cmd/tls.go:51-61, internal/output/writers/file_writer.go:36-43