feat: add connection event handling and enhance TLS event structure with additional fields

[cfc4n]

This pull request introduces significant improvements to the OpenSSL probe in the ecapture project, focusing on enhanced connection tracking and event decoding, as well as improvements to timestamp accuracy and event structuring. The changes add new kernel probes for connection lifecycle events, introduce a new ConnDataEvent type for connection metadata, and refactor event decoding logic for clarity and extensibility. Additionally, there are minor fixes to keylog formatting and timestamp handling.

Connection tracking and event decoding enhancements:

• Added new kernel probes and eBPF maps for tracking connection lifecycle events (connect, accept, destroy) in setupManagerText, and registered a new connect_events map with its decoder.
• Introduced the ConnDataEvent struct and associated logic in a new file (event_connect.go) to represent and decode socket connection metadata, including source/destination addresses and ports, process info, and tuple formatting.
• Implemented a new connectDecoder type for decoding connection events from the new map, and refactored the packetEventDecoder to its own section for clarity. [1] [2]

TLS event structure and decoding improvements:

• Refactored the Event struct in event.go to add fields for connection tuple, socket, and bio type, and improved the decoding logic to match the updated eBPF structure. Also added TLS version parsing and stringification utilities. [1] [2]
• Improved time accuracy for event logs by calculating the offset between CLOCK_REALTIME and CLOCK_MONOTONIC, ensuring correct absolute timestamps in event string representations. [1] [2]

Keylog formatting fixes:

• Standardized keylog line formatting by ensuring newline characters are appended only in the writer, not in the format string, to avoid duplicate newlines. [1] [2] [3] [4]

Other minor improvements:

• Added utility functions for address and command string conversion, and improved UUID generation logic for events.
• Commented out unused or deprecated decoding functions for clarity and future refactoring.

These changes collectively enhance the probe's ability to track, decode, and log both TLS data and connection metadata, laying the groundwork for more advanced analysis and troubleshooting features.

[dosubot]

Related Documentation

Checked 1 published document(s) in 1 knowledge base(s). No updates required.

^{How did I do? Any feedback?}  

[github-actions]

🔧 Debug Build Complete (PR #938)

📦 Download Links:

• View Build Artifacts

⏰ Files will be retained for 7 days, please download and test promptly.

---

This build includes debug binaries for: android/linux (arm64/amd64)

[Copilot]

Pull request overview

This PR enhances the OpenSSL probe by adding connection lifecycle event capture/decoding alongside existing TLS data events, and adjusts event/keylog formatting and timestamp handling to improve logging fidelity.

Changes:

• Registers a new connect_events perf map and decoder, and adds several kprobes/uprobes to track connection lifecycle alongside TLS read/write probes.
• Introduces ConnDataEvent for decoding connection metadata (addresses/ports/process info) and emitting it as a domain event.
• Refactors TLS event decoding/formatting, adds TLS version stringification utilities, and adjusts keylog newline handling via the writer.

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 10 comments.

Show a summary per file

File	Description
pkg/event_processor/base_event.go	Exposes TlsVersion and updates formatting to use the exported type/field names.
internal/probe/openssl/openssl_probe.go	Adds connect_events map/decoder and new probe attachments (connect/accept/destroy + SSL_set_* hooks).
internal/probe/openssl/event_connect.go	Adds ConnDataEvent and decoding/protobuf conversion for connection metadata.
internal/probe/openssl/event.go	Refactors TLS event struct/decoder and changes timestamp formatting logic.
internal/probe/base/handlers/keylog_handler.go	Changes keylog line formatting to omit trailing newline.
internal/output/writers/keylog_writer.go	Appends newline in the PCAP keylog writer.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

The probes for SSL_set_rfd/SSL_set_wfd reference eBPF section names ("uprobe/SSL_set_rfd" and "uprobe/SSL_set_wfd") that don't exist in kern/openssl.h (only SEC("uprobe/SSL_set_fd") is defined). This will cause the eBPF manager to fail to find/load these programs at startup. Either add corresponding SEC("uprobe/SSL_set_rfd")/SEC("uprobe/SSL_set_wfd") programs in the BPF object, or reuse the existing "uprobe/SSL_set_fd" section for these attachments (same program attached to multiple symbols).

[Copilot]

The doc comment says connectDecoder is "for TLS data events", but this decoder is wired to the "connect_events" map and decodes ConnDataEvent. Please update the comment to avoid confusion when scanning decoder implementations.

Suggested change

	// connectDecoder implements domain.EventDecoder for TLS data events
	// connectDecoder implements domain.EventDecoder for connection events (ConnDataEvent)

[Copilot]

connDataEvent's Saddr/Daddr are declared as [32]byte, but the kernel struct connect_event_t uses unsigned __int128 for each address (16 bytes) in kern/openssl.h. This size mismatch will misalign subsequent reads (Comm/Timestamp/etc) and likely cause decode errors or garbage data. Please change Saddr/Daddr to 16-byte fields (or a struct matching connect_event_t exactly) and update the IPv4/IPv6 extraction logic accordingly.

Suggested change

	Saddr [32]byte `json:"saddr"`
	Daddr [32]byte `json:"daddr"`
	Saddr [16]byte `json:"saddr"`
	Daddr [16]byte `json:"daddr"`

[Copilot]

IPv6 address extraction uses e.Saddr[16:32]/e.Daddr[16:32], but even if the address fields were correctly sized, the kernel stores IPv6 in a single 16-byte value (see connect_event_t in kern/openssl.h). This slice will produce the wrong address bytes. After aligning the struct, use the full 16 bytes for AF_INET6 and be careful about endianness for AF_INET (the current direct byte cast is unlikely to match network order).

Suggested change

	saddr, daddr := netip.AddrFrom4([4]byte(e.Saddr[:4])), netip.AddrFrom4([4]byte(e.Daddr[:4]))
	e.Tuple = fmt.Sprintf("[%s]:%d->[%s]:%d", saddr, e.Sport, daddr, e.Dport)
	} else {
	saddr, daddr := netip.AddrFrom16([16]byte(e.Saddr[16:32])), netip.AddrFrom16([16]byte(e.Daddr[16:32]))
	// Saddr/Daddr are read as little-endian bytes; normalize to network order for IPv4.
	var saddr4, daddr4 [4]byte
	saddrLE := binary.LittleEndian.Uint32(e.Saddr[:4])
	daddrLE := binary.LittleEndian.Uint32(e.Daddr[:4])
	binary.BigEndian.PutUint32(saddr4[:], saddrLE)
	binary.BigEndian.PutUint32(daddr4[:], daddrLE)
	saddr, daddr := netip.AddrFrom4(saddr4), netip.AddrFrom4(daddr4)
	e.Tuple = fmt.Sprintf("[%s]:%d->[%s]:%d", saddr, e.Sport, daddr, e.Dport)
	} else {
	// For IPv6, use the full 16-byte address as stored by the kernel.
	saddr, daddr := netip.AddrFrom16([16]byte(e.Saddr[:16])), netip.AddrFrom16([16]byte(e.Daddr[:16]))

[Copilot]

Keylog lines are now formatted without a trailing newline, but most OutputWriter implementations (stdout/file/tcp/ws) don't append newlines. This will concatenate multiple keylog entries onto a single line for non-PCAP outputs. Either keep the newline in the handler's formatted line(s) (recommended, since it's the canonical NSS keylog format), or ensure all keylog writers append a newline consistently.

Suggested change

	line := fmt.Sprintf("%s %x %x",
	line := fmt.Sprintf("%s %x %x\n",

[Copilot]

PcapKeylogWriter now unconditionally appends '\n'. If the keylog handler is updated to always include newlines (needed for stdout/file writers), this will produce double newlines in pcapng output. Consider making newline responsibility consistent: either have the handler always include it and have PcapKeylogWriter write bytes as-is, or have writers append it but then update all writers (not just PCAP) to do so.

Suggested change

	p = append(p, '\n')
	// Ensure each keylog entry is newline-terminated, but avoid adding
	// a second newline if the caller already provided one.
	if len(p) == 0 || p[len(p)-1] != '\n' {
	p = append(p, '\n')
	}

[Copilot]

ToProtobufEvent parses ce.Tuple by splitting on "-" and then ":", but Tuple is formatted as "[ip]:port->[ip]:port". This parsing will never populate SrcIp/DstIp/SrcPort/DstPort, and it will also break for IPv6 because addresses contain ':'. Prefer filling protobuf fields directly from the decoded numeric address/port fields (Family/Saddr/Daddr/Sport/Dport), or change Tuple to a machine-parseable format and use SplitN with proper IPv6 handling.

Suggested change

	// Parse tuple for IP addresses and ports
	ips := strings.Split(ce.Tuple, "-")
	if len(ips) == 2 {
	srcParts := strings.Split(ips[0], ":")
	destParts := strings.Split(ips[1], ":")
	if len(srcParts) == 2 && len(destParts) == 2 {
	event.SrcIp = srcParts[0]
	event.DstIp = destParts[0]
	if srcPort, err := strconv.ParseUint(srcParts[1], 10, 32); err == nil {
	event.SrcPort = uint32(srcPort)
	}
	if dstPort, err := strconv.ParseUint(destParts[1], 10, 32); err == nil {
	event.DstPort = uint32(dstPort)
	}
	}
	}
	// Populate IP addresses from numeric fields instead of parsing Tuple.
	switch ce.Family {
	case unix.AF_INET:
	// IPv4: use first 4 bytes of Saddr/Daddr.
	var src4, dst4 [4]byte
	copy(src4[:], ce.Saddr[:4])
	copy(dst4[:], ce.Daddr[:4])
	event.SrcIp = netip.AddrFrom4(src4).String()
	event.DstIp = netip.AddrFrom4(dst4).String()
	case unix.AF_INET6:
	// IPv6: use first 16 bytes of Saddr/Daddr.
	var src6, dst6 [16]byte
	copy(src6[:], ce.Saddr[:16])
	copy(dst6[:], ce.Daddr[:16])
	event.SrcIp = netip.AddrFrom16(src6).String()
	event.DstIp = netip.AddrFrom16(dst6).String()
	}
	// Ports are already decoded numeric fields.
	event.SrcPort = uint32(ce.Sport)
	event.DstPort = uint32(ce.Dport)

[Copilot]

Event.DataType is decoded into an int64, but the underlying eBPF struct field is an enum (4 bytes) followed by 4 bytes of padding before the u64 timestamp. Reading 8 bytes into int64 means the upper 32 bits come from padding, which is not guaranteed to be zero and can cause DataType comparisons/validation to fail intermittently. Decode DataType as an int32/uint32 and explicitly skip/consume the 4-byte padding (or model it as a separate field) to match the kernel struct layout.

Suggested change

	if err := binary.Read(buf, binary.LittleEndian, &e.DataType); err != nil {
	return errors.NewEventDecodeError("openssl.DataType", err)
	}
	// The underlying C struct starts with a 4-byte enum (ssl_data_event_type)
	// followed by 4 bytes of padding before the 8-byte timestamp. Decode the
	// enum as a 32-bit value and explicitly consume the padding to keep the
	// stream aligned and avoid mixing padding bits into DataType.
	var rawType uint32
	if err := binary.Read(buf, binary.LittleEndian, &rawType); err != nil {
	return errors.NewEventDecodeError("openssl.DataType", err)
	}
	e.DataType = int64(rawType)
	// Consume 4 bytes of padding between the enum and timestamp_ns.
	var padding uint32
	if err := binary.Read(buf, binary.LittleEndian, &padding); err != nil {
	return errors.NewEventDecodeError("openssl.DataTypePadding", err)
	}

[Copilot]

String() calls getClockOffset() for every event and panics on error. Calling clock_gettime twice per event is expensive in hot paths, and panicking in a Stringer can crash the whole process during logging. Consider computing/caching the offset once (e.g., sync.Once) and, on error, fall back to formatting using the raw monotonic timestamp (or omit the wall-clock time) instead of panicking.

[Copilot]

StringHex uses time.Unix(int64(e.Timestamp), 0), which treats the nanosecond monotonic timestamp as seconds and produces incorrect dates. It also doesn't apply the CLOCK_REALTIME/CLOCK_MONOTONIC offset used in String(). Please switch to time.Unix(0, absoluteTimeNs) (same approach as String()) or otherwise ensure consistent, correct timestamp units.

Suggested change

	ts := time.Unix(int64(e.Timestamp), 0)
	// Align timestamp handling with String(): apply CLOCK_REALTIME/CLOCK_MONOTONIC offset
	offsetNs, err := getClockOffset()
	if err != nil {
	panic(err)
	}
	absoluteTimeNs := int64(e.Timestamp) + offsetNs
	ts := time.Unix(0, absoluteTimeNs)

[github-actions]

✅ E2E Test Results: PASSED

Test Run: #22545374683

Tests Executed:

• TLS/OpenSSL Module (curl → github.com)
• GnuTLS Module (wget/curl → github.com)
• GoTLS Module (Go client → github.com)

✅ All e2e tests passed successfully! The TLS capture functionality is working correctly.

---

Automated e2e test results for commit 040335a

[github-actions]

🔧 Debug Build Complete (PR #938)

📦 Download Links:

• View Build Artifacts

⏰ Files will be retained for 7 days, please download and test promptly.

---

This build includes debug binaries for: android/linux (arm64/amd64)

[github-actions]

✅ E2E Test Results: PASSED

Test Run: #22545725368

Tests Executed:

• TLS/OpenSSL Module (curl → github.com)
• GnuTLS Module (wget/curl → github.com)
• GoTLS Module (Go client → github.com)

✅ All e2e tests passed successfully! The TLS capture functionality is working correctly.

---

Automated e2e test results for commit 4ec45e2