Output Formats ​

eCapture provides four distinct output formats for captured network traffic, master secrets, and audit data. Each format serves specific use cases and integrates with different analysis tools. The output format determines both the data encoding (text, binary PCAP, keylog, protobuf) and the destination (console, file, TCP socket, WebSocket).

Output Format Overview ​

For detailed information about specific output modes, see:

• Text Output Mode - Plain text formatting, HTTP parsing, color coding
• PCAP Integration - PCAP-NG file generation, DSB blocks, Wireshark workflow
• TLS Key Logging - Master secret extraction, SSLKEYLOGFILE format
• Protobuf and External Integration - Binary protocol, WebSocket streaming, eCaptureQ

Sources: README.md:172-253, user/module/probe_openssl.go:58-76, user/config/iconfig.go:73-79

Output Format Architecture ​

Format Selection and Encoding Pipeline ​

The following diagram shows how CLI flags are translated into output encoders and destination writers:

Sources: user/module/probe_openssl.go:109-176, user/config/iconfig.go:95-112, cli/cmd/root.go:178-247

Format Type Constants ​

Output formats are defined using the TlsCaptureModelType enumeration in the codebase:

The CLI accepts string values via the --model/-m flag:

• text → TlsCaptureModelTypeText → Uses setupManagersText()
• pcap or pcapng → TlsCaptureModelTypePcap → Uses setupManagersPcap()
• keylog or key → TlsCaptureModelTypeKeylog → Uses setupManagersKeylog()

Protobuf format is automatically enabled when using remote destinations (tcp:// or ws:// in --eventaddr).

Sources: user/module/probe_openssl.go:58-76, user/config/iconfig.go:73-79

Event Structure and Serialization ​

All captured events implement the IEventStruct interface, which defines methods for multiple output formats:

IEventStruct Interface Methods ​

type IEventStruct interface {
    Decode(payload []byte) error
    String() string                    // Text format
    StringHex() string                 // Text format with hex dump
    Clone() IEventStruct
    EventType() Type
    GetUUID() string
    Payload() []byte
    PayloadLen() int
    Base() Base                        // Common metadata
    ToProtobufEvent() *pb.Event       // Protobuf format
}

Event Types by Module ​

Each event structure implements serialization for its supported output formats:

• String() / StringHex() for text output with optional color coding
• ToProtobufEvent() for binary protobuf serialization
• Module-specific methods (saveMasterSecret(), dumpTcSkb()) for PCAP/keylog

Sources: user/event/event_openssl.go:77-391, user/event/event_masterkey.go:37-273, user/event/event_bash.go:37-133, user/event/event_mysqld.go:68-168

Output Destination Configuration ​

eCapture separates logging (diagnostic messages) from event output (captured data). Both support multiple destination types.

Destination Type Detection ​

Sources: cli/cmd/root.go:68-73, cli/cmd/root.go:178-247

Destination Type Constants and Behavior ​

Codec Selection Logic ​

The destination type determines which codec is used for event serialization:

// In initLogger() function
if strings.Contains(addr, "tcp://") || strings.Contains(addr, "ws://") {
    // Remote destinations use protobuf
    module.eventOutputType = codecTypeProtobuf
} else {
    // Local destinations use text
    module.eventOutputType = codecTypeText
}

Remote destinations (tcp://, ws://) automatically enable protobuf encoding via IEventStruct.ToProtobufEvent(), while local destinations use IEventStruct.String().

Log Rotation ​

File destinations support automatic rotation when configured:

• --eventroratesize <MB> - Rotate when file reaches size limit
• --eventroratetime <seconds> - Rotate at time intervals

Rotation is handled by the roratelog.Logger wrapper around the file handle.

Sources: cli/cmd/root.go:68-73, cli/cmd/root.go:178-247, cli/cmd/root.go:151-152

Event Output Pipeline ​

Captured events flow through a multi-stage pipeline before reaching their final destination.

Event Flow Architecture ​

Sources: user/module/imodule.go:285-448, user/module/probe_openssl.go:733-775

Event Routing by Type ​

The event pipeline uses three classification types to route events through different processing stages:

Events are assigned types during Clone():

// Example from SSLDataEvent
func (se *SSLDataEvent) Clone() IEventStruct {
    event := new(SSLDataEvent)
    event.eventType = TypeModuleData  // Routes to module dispatcher
    return event
}

Sources: user/event/event_openssl.go:200-204, user/module/imodule.go:430-447

Format-Specific Processing ​

Each output format implements specialized processing logic within the module's dispatcher.

Format-Specific Use Cases ​

Text Mode ​

When to use:

• Interactive debugging and real-time monitoring
• Console-based traffic inspection
• Log file analysis with grep/awk
• HTTP/HTTP2 protocol analysis

Output examples:

• Plain text request/response bodies with color coding
• HTTP/1.1 headers and content
• HTTP/2 frame-by-frame decoding with stream IDs
• Connection metadata (PID, process name, IP:port tuples)

See Text Output Mode for formatting details, color schemes, and HTTP parsing.

Sources: user/module/probe_openssl.go:756-775, user/event/event_openssl.go:167-198

PCAP Mode ​

When to use:

• Network analysis with Wireshark
• Traffic archival for later analysis
• Integration with existing PCAP-based tools
• Combining plaintext capture with packet inspection

Output structure:

• PCAP-NG file format with Interface Description Block (IDB)
• Enhanced Packet Blocks (EPB) for captured packets
• Decryption Secrets Blocks (DSB) containing master keys
• Automatic key-to-connection association

See PCAP Integration for file format details and Wireshark workflow.

Sources: user/module/probe_openssl.go:733-754

Keylog Mode ​

When to use:

• Decrypting existing pcap files with Wireshark
• Real-time decryption with tshark
• Compliance with SSLKEYLOGFILE-based tools
• Separating key capture from packet capture

Output format:

CLIENT_RANDOM <32-byte-hex> <48-byte-hex-master-key>
CLIENT_HANDSHAKE_TRAFFIC_SECRET <32-byte-hex> <secret>
SERVER_HANDSHAKE_TRAFFIC_SECRET <32-byte-hex> <secret>

See TLS Key Logging for TLS 1.2/1.3 key extraction and integration examples.

Sources: user/module/probe_openssl.go:482-642

Protobuf Mode ​

When to use:

• eCaptureQ GUI integration
• Custom tool development with structured data
• Remote monitoring over TCP/WebSocket
• Event forwarding to SIEM systems

Protocol:

• Binary protobuf encoding via pb.Event message type
• Fields: timestamp, uuid, pid, pname, src_ip, dst_ip, payload
• WebSocket framing with heartbeat mechanism

See Protobuf and External Integration for protocol schema and client examples.

Sources: user/event/event_openssl.go:237-266, protobuf/PROTOCOLS.md

CLI Configuration Reference ​

Global Output Flags ​

Module-Specific Format Flags ​

Available for tls, gotls, gnutls, nss modules:

Example Commands ​

# Text mode to console
sudo ecapture tls

# Text mode to file with rotation
sudo ecapture tls --eventaddr=/var/log/ecapture.log --eventroratesize=100

# PCAP mode with custom file
sudo ecapture tls -m pcap -w /tmp/capture.pcapng -i eth0

# Keylog mode for Wireshark decryption
sudo ecapture tls -m keylog --keylogfile=/tmp/keys.log

# Protobuf streaming to eCaptureQ
sudo ecapture tls --ecaptureq=:9090

# Remote TCP streaming
sudo ecapture tls --eventaddr=tcp://192.168.1.100:8080

Sources: cli/cmd/root.go:136-153, README.md:172-253

Configuration Structure ​

The output configuration is stored in multiple places:

1. BaseConfig: Common settings for all modules

   • LoggerAddr: Logger destination
   • EventCollectorAddr: Event collector destination
   • LoggerType: Destination type (stdout/file/tcp/ws)

2. OpensslConfig: SSL module-specific settings

   • Model: Output format mode
   • PcapFile: PCAP file path
   • KeylogFile: Keylog file path

3. Module Runtime State: Derived from configuration

   • eBPFProgramType: Internal format type enum
   • keylogger: Open file handle for keylog
   • pcapngFilename: Resolved PCAP file path

Sources: user/config/iconfig.go:95-112, user/module/probe_openssl.go:83-106

Output Format Selection Matrix ​

The following table summarizes format capabilities and requirements:

Compatibility Notes:

• Text mode with HTTP/2 support added in v0.8.5
• PCAP DSB block support for embedded master secrets
• Keylog format compatible with Wireshark's "Pre-Master-Secret log filename" setting
• Protobuf mode automatically enabled when using eCaptureQ integration

Sources: README.md:172-253, CHANGELOG.md:487-493