Troubleshooting and FAQ ​

This document provides solutions to common issues encountered when using eCapture, debugging techniques, and answers to frequently asked questions. For system architecture details, see Architecture. For installation instructions, see Installation and Quick Start. For build-related issues, see Build System.

Common Issues and Solutions ​

System Requirements and Compatibility ​

BTF (BPF Type Format) Not Available ​

Symptom:

ERROR: BTF information not found
ERROR: Kernel does not support BTF

Diagnosis Flow:

Solution:

1. Check kernel version:

   bash

   uname -r

   • x86_64: Requires 4.18+
   • aarch64: Requires 5.5+

2. Verify BTF support:

   bash

   cat /boot/config-$(uname -r) | grep CONFIG_DEBUG_INFO_BTF

   Should output: CONFIG_DEBUG_INFO_BTF=y

3. Check BTF file:

   bash

   ls -l /sys/kernel/btf/vmlinux

4. Automatic fallback: eCapture v0.8.0+ automatically detects BTF availability and selects the appropriate bytecode mode (CO-RE or non-CO-RE). This logic is handled in user/module/probe_ebpf.go:240-280.

Related fixes:

• v0.8.0: Unified CO-RE and non-CO-RE support in single binary
• v1.4.3: Fixed kernel 4.19 compatibility issue with .rodata maps

Sources: README.md:14-16, CHANGELOG.md:50, CHANGELOG.md:560-577

Permission Denied ​

Symptom:

ERROR: Permission denied
ERROR: Operation not permitted

Root Cause Analysis:

Solution:

1. Run with sudo:

   bash

   sudo ecapture tls

2. Check capabilities (Linux 5.8+):

   bash

   # Check if CAP_BPF is available
   capsh --print | grep cap_bpf

3. Grant specific capabilities:

   bash

   sudo setcap cap_bpf,cap_net_admin,cap_sys_admin+ep ./ecapture

4. Capability detection: eCapture v0.9.0+ detects CAP_BPF capability automatically via user/module/probe_ebpf.go:150-180 using the capget syscall.

Related fixes:

• v0.9.0: Added CAP_BPF detection
• v0.9.3: Fixed incorrect CAP_BPF check method

Sources: CHANGELOG.md:331, CHANGELOG.md:379, cli/cmd/root.go:80-120

Library Version Detection Issues ​

OpenSSL/BoringSSL Version Not Found ​

Symptom:

WARN OpenSSL/BoringSSL version not found from shared library file, used default version

Version Detection Process:

Solution:

1. Automatic detection: eCapture scans /etc/ld.so.conf for library paths. This is implemented in user/module/probe_openssl.go:180-250.

2. Specify library manually:

   bash

   sudo ecapture tls --libssl=/path/to/libssl.so

3. For statically compiled binaries:

   bash

   sudo ecapture tls --libssl=/path/to/application

4. Version downgrade logic: If exact version bytecode is not found, eCapture uses downgradeOpensslVersion() in user/config/openssl_version.go:120-200 to find the nearest compatible version.

5. Supported versions:

   • OpenSSL: 1.0.2x, 1.1.0x, 1.1.1x, 3.0.x, 3.1.x, 3.2.x, 3.3.x, 3.4.x, 3.5.x
   • BoringSSL: Android 12-16
   • Check user/config/openssl_version.go:40-100 for full version mapping

Default fallback behavior: When version cannot be detected, eCapture uses linux_default_3_0 as the default version, which works with most modern OpenSSL 3.x installations.

Related fixes:

• v0.8.11: Read version from libcrypto.so when libssl.so version string not found
• v0.8.12: Fixed version string detection in BoringSSL dynamic libraries
• v1.4.0: Implemented version downgrade logic

Sources: CHANGELOG.md:105-108, CHANGELOG.md:400-402, CHANGELOG.md:409, user/module/probe_openssl.go:180-250

Go TLS Version Detection Failure ​

Symptom:

ERROR: cant found RET offset in gotls mode
ERROR: failed to parse pclntab

Go Binary Analysis:

Solution:

1. Check Go version:

   bash

   go version /path/to/binary

2. Specify binary explicitly:

   bash

   sudo ecapture gotls --elfpath=/path/to/go/binary

3. ABI detection: eCapture automatically detects Go ABI (register vs stack) in user/module/probe_gotls.go:150-200.

4. Handle stripped binaries: v0.7.0+ supports stripped Go binaries by parsing .gopclntab section. Implementation in user/module/probe_gotls.go:250-350.

5. PIE (Position Independent Executable) support: v0.7.7 fixed offset calculation for PIE executables in user/module/probe_gotls.go:400-450.

Related fixes:

• v0.7.0: Added support for stripped Go binaries
• v0.7.6: Fixed RET offset calculation
• v0.7.7: Fixed PIE executable offset errors

Sources: CHANGELOG.md:431, CHANGELOG.md:581-583, CHANGELOG.md:602

Capture Failures ​

No Data Captured ​

Diagnostic Flowchart:

Solution checklist:

1. Verify module is running:

   bash

   # Should see "module started successfully"
   sudo ecapture tls 2>&1 | grep "module started"

2. Check process filter:

   bash

   # Capture specific process
   sudo ecapture tls --pid=1234
   
   # Capture all processes (default)
   sudo ecapture tls

3. Check user filter:

   bash

   # Capture specific user
   sudo ecapture tls --uid=1000
   
   # Capture all users (default)
   sudo ecapture tls

4. Verify output mode:

   • Text mode: sudo ecapture tls -m text
   • Pcap mode: sudo ecapture tls -m pcap -i eth0 --pcapfile=out.pcapng
   • Keylog mode: sudo ecapture tls -m keylog --keylogfile=keys.log

5. Generate test traffic:

   bash

   # In another terminal
   curl https://example.com

6. Check event processor: v0.7.3+ uses EventProcessor with worker pools. If you see "incoming chan is full", increase --mapsize:

   bash

   sudo ecapture tls --mapsize=10240  # 10MB

Sources: cli/cmd/tls.go:80-150, user/event/event_processor.go:100-200

Incomplete or Truncated Data ​

Symptom:

• Partial HTTP requests/responses
• Missing SSL data
• Truncated payloads

Data Flow and Truncation Points:

Solutions:

1. Increase map size:

   bash

   sudo ecapture tls --mapsize=10240  # 10MB

   Map size controls per-CPU buffer size in user/module/probe_ebpf.go:300-350.

2. For text mode truncation (v1.1.0+):

   bash

   # Adjust truncate size (default: 1024 bytes)
   sudo ecapture tls -m text --truncate=4096

   Implemented in user/event/event_worker.go:150-200.

3. Use pcap mode for complete data:

   bash

   sudo ecapture tls -m pcap -i eth0 --pcapfile=complete.pcapng

   Pcap mode captures full packets without truncation.

4. Check for long connections: v0.9.5 fixed incomplete SSL data for excessively long data lengths in kern/openssl_kern.c:800-900.

5. Event rotation (v1.2.0+):

   bash

   # Rotate output files
   sudo ecapture tls --eventrotatesize=100 --eventrotatetime=3600

Related fixes:

• v0.9.5: Fixed incomplete SSL data bug for long lengths
• v1.1.0: Added --truncate flag to reduce memory cost
• v1.2.0: Added file rotation support

Sources: CHANGELOG.md:298, CHANGELOG.md:163-164, CHANGELOG.md:147-148

Module-Specific Issues ​

Bash/Zsh Command Capture Failures ​

Symptom:

ERROR: failed to attach uprobe to readline
WARN: bash path detection failed

Solution:

1. Verify bash/zsh path:

   bash

   which bash  # Usually /bin/bash or /usr/bin/bash
   which zsh   # Usually /bin/zsh or /usr/bin/zsh

2. Manual path specification:

   bash

   sudo ecapture bash --bashpath=/bin/bash

3. Check readline library:

   bash

   ldd /bin/bash | grep readline

4. Path detection improvement: v1.3.1 improved bash path detection in user/module/probe_bash.go:100-150.

Related fixes:

• v0.9.0: Added zsh command capture support
• v1.3.1: Improved bash path detection and probe attachment

Sources: CHANGELOG.md:378, CHANGELOG.md:123-124

MySQL/PostgreSQL Query Capture Issues ​

Symptom:

• No SQL queries captured
• Connection but no query data

Solution:

1. Verify database version:

   • MySQL: Supports 5.6, 5.7, 8.0, and MariaDB
   • PostgreSQL: Supports 10+

2. Check process name:

   bash

   ps aux | grep mysqld
   ps aux | grep postgres

3. Capture with specific PID:

   bash

   sudo ecapture mysqld --pid=$(pidof mysqld)
   sudo ecapture postgres --pid=$(pidof postgres)

4. Generate test queries:

   bash

   mysql -u root -p -e "SELECT 'test' FROM dual;"
   psql -U postgres -c "SELECT 'test';"

Sources: cli/cmd/mysqld.go:40-80, cli/cmd/postgres.go:40-80

Performance and Resource Issues ​

High Memory Usage ​

Memory Usage Components:

Solutions:

1. Adjust map size (v0.7.0+):

   bash

   # Default is 5120KB, reduce if needed
   sudo ecapture tls --mapsize=2048

   Configured in cli/cmd/root.go:200-230.

2. Use text mode with truncation:

   bash

   sudo ecapture tls -m text --truncate=512

   Reduces memory by limiting captured payload size.

3. Worker lifecycle optimization (v1.2.0):

   • Default workers: Self-destruct after 1s inactivity
   • Socket-bound workers: Persist until connection close
   • Implementation in user/event/event_worker.go:250-350

4. Limit target processes:

   bash

   sudo ecapture tls --pid=1234 --uid=1000

Related fixes:

• v0.7.0: Added --mapsize flag (default 5120KB)
• v1.1.0: Redesigned truncate logic to reduce memory cost
• v1.2.0: Dual lifecycle management for eventWorker

Sources: CHANGELOG.md:435, CHANGELOG.md:163-164, CHANGELOG.md:146

High CPU Usage ​

Solution:

1. Reduce event processing frequency:

   • Use targeted filters (--pid, --uid)
   • Use pcap filter expressions (v0.7.4+)

2. Pcap filter example:

   bash

   sudo ecapture tls -m pcap -i eth0 host 192.168.1.1 and port 443

   Filter syntax: Pcap Filter Syntax

3. Disable unnecessary hooks:

   • Connect hook is optional (v0.6.6+)
   • Implemented in user/module/probe_openssl.go:500-550

4. Check event loop: If logs show "incoming chan is full", the system cannot keep up:

   bash

   # Increase workers or reduce capture scope
   sudo ecapture tls --pid=1234

Related fixes:

• v0.6.6: Made connect hook optional
• v0.7.4: Added pcap filter support
• v1.4.3: Improved performance with impact reduction on target programs

Sources: CHANGELOG.md:774, CHANGELOG.md:644, CHANGELOG.md:661-662

Network and Output Issues ​

PCAP File Issues ​

Symptom:

• Cannot open pcap file in Wireshark
• Decryption not working
• Empty or corrupted file

PCAP Pipeline:

Solutions:

1. Specify interface:

   bash

   sudo ecapture tls -m pcap -i eth0 --pcapfile=capture.pcapng

2. Verify file is being written:

   bash

   # Watch file grow
   watch -n 1 ls -lh capture.pcapng

3. Flush interval: Pcap files are flushed every 2 seconds (v0.7.2+) in user/module/probe_openssl.go:800-850.

4. Check for empty DSB: v1.1.0 fixed writing empty Decryption Secrets Block:

   bash

   # Verify DSB exists
   tshark -r capture.pcapng -V | grep "Decryption Secrets"

5. Use with tshark:

   bash

   tshark -r capture.pcapng -Y tls -V

6. Master key multiple writes fix: v0.8.1 fixed master keys being written multiple times to pcapng.

Related fixes:

• v0.7.2: Pcapng writer flushes every 2s
• v0.8.1: Fixed masterkey being written multiple times
• v1.1.0: Fixed empty DSB writing

Sources: CHANGELOG.md:673, CHANGELOG.md:551, CHANGELOG.md:170-171

Keylog Mode Issues ​

Symptom:

• Empty keylog file
• Tshark cannot decrypt
• Missing keys for some connections

Keylog Format:

CLIENT_RANDOM <client_random_hex> <master_secret_hex>
CLIENT_HANDSHAKE_TRAFFIC_SECRET <client_random_hex> <secret_hex>
SERVER_HANDSHAKE_TRAFFIC_SECRET <client_random_hex> <secret_hex>

Solutions:

1. Generate keylog file:

   bash

   sudo ecapture tls -m keylog --keylogfile=keys.log

2. Use with tshark:

   bash

   # Capture packets separately
   sudo tcpdump -i eth0 -w packets.pcap port 443 &
   
   # Capture keys
   sudo ecapture tls -m keylog --keylogfile=keys.log &
   
   # Decrypt and view
   tshark -o tls.keylog_file:keys.log -r packets.pcap -Y http -V

3. Check TLS version:

   • TLS 1.2: Single CLIENT_RANDOM line
   • TLS 1.3: Multiple TRAFFIC_SECRET lines

4. Verify key extraction: Keylog support added in v0.7.0 for OpenSSL, v1.3.0 for GnuTLS.

5. Check handshake timing: Keys must be captured during handshake. Implemented in kern/openssl_masterkey.c:100-300.

6. Fix for Go TLS: v1.4.0 fixed missing trailing bytes in Go TLS keylog.

Related fixes:

• v0.7.0: Added keylog mode support
• v1.3.0: Added GnuTLS keylog support
• v1.4.0: Fixed missing trailing bytes in gotls keylog
• v1.4.1: Fixed keylog mode for OpenSSL 3.0.12

Sources: CHANGELOG.md:699-700, CHANGELOG.md:135, CHANGELOG.md:94, CHANGELOG.md:78

WebSocket Connection Issues (eCaptureQ) ​

Symptom:

• Cannot connect to WebSocket server
• Connection drops frequently
• No events received

WebSocket Architecture:

Solutions:

1. Check server is running:

   bash

   # Server starts automatically with eCapture
   sudo ecapture tls
   
   # Should see: "Listen=localhost:28256"
   # WebSocket: :28257, HTTP API: :28256

2. Test connection:

   bash

   # Use protobuf visualizer
   cd utils/protobuf_visualizer
   go build -o pb_debugger pb_debugger.go
   ./pb_debugger -url ws://127.0.0.1:28257

3. Heartbeat timing: v1.5.0 adjusted heartbeat frequency and immediate ping triggering in user/module/probe_ebpf.go:600-650.

4. Protobuf protocol: See protobuf/PROTOCOLS.md for message format details.

5. Example client code:

   go

   import (
       pb "github.com/gojue/ecapture/protobuf/gen/v1"
       "golang.org/x/net/websocket"
       "google.golang.org/protobuf/proto"
   )
   
   ws, err := websocket.Dial("ws://127.0.0.1:28257/", "", "http://localhost/")
   // Read and decode LogEntry messages

Related fixes:

• v1.4.0: Implemented WebSocket server
• v1.5.0: Adjusted heartbeat frequency

Sources: CHANGELOG.md:91-96, CHANGELOG.md:31, protobuf/PROTOCOLS.md:1-97

HTTP/HTTP2 Parsing Issues ​

HTTP/2 Parser Errors ​

Symptom:

ERROR: unexpected EOF
WARN: COMPRESSION_ERROR
ERROR: incorrect stream id

Solutions:

1. Handle fragmented frames: v1.5.0 fixed HTTP/2 parser logging spurious EOF errors during TLS capture.

2. Compression errors: v0.9.5 improved handling of COMPRESSION_ERROR to reduce error logs.

3. Stream ID issues: v0.9.4 fixed incorrect stream ID in HTTP/2 protocol data frames.

4. HPACK decoder: v1.3.1 fixed sharing same HPACK decoder for one tuple connection:

   go

   // One decoder per connection
   decoder := hpack.NewDecoder(dynamicTableSize, nil)

5. Frame length: v0.9.5 added frame length tracking for better parsing.

Related fixes:

• v0.9.4: Fixed incorrect stream ID
• v0.9.5: Improved COMPRESSION_ERROR handling
• v1.3.1: Fixed HPACK decoder sharing
• v1.5.0: Fixed HTTP/2 parser EOF errors

Sources: CHANGELOG.md:33, CHANGELOG.md:302-303, CHANGELOG.md:305, CHANGELOG.md:316, CHANGELOG.md:122

HTTP/1.x Body Truncation ​

Symptom:

• Truncated response bodies
• Incorrect Content-Length

Solutions:

1. HEAD request handling: v0.8.4 fixed DumpResponse error in HEAD requests.

2. Compressed responses: v0.7.5 updates ContentLength for uncompressed response body.

3. Use pcap mode for complete bodies:

   bash

   sudo ecapture tls -m pcap -i eth0 --pcapfile=full.pcapng

Related fixes:

• v0.7.5: Fixed ContentLength for uncompressed responses
• v0.8.4: Fixed DumpResponse error in HEAD requests

Sources: CHANGELOG.md:614, CHANGELOG.md:512

Runtime Configuration Issues ​

Configuration Updates via HTTP API ​

eCapture v0.8.1+ supports runtime configuration updates via HTTP API on port 28256.

Available endpoints:

Example usage:

# Get current configuration
curl http://localhost:28256/config

# Update PID filter
curl -X POST http://localhost:28256/config \
  -H "Content-Type: application/json" \
  -d '{"pid": 1234}'

# Reload module with new config
curl -X POST http://localhost:28256/reload

Documentation: See docs/remote-config-update-api.md for full API reference.

Sources: README.md:326, user/module/imodule.go:150-200

FAQ ​

General Questions ​

Q: Does eCapture work on Windows or macOS?

A: No. eCapture requires Linux eBPF support and is only compatible with:

• Linux x86_64: Kernel 4.18+
• Linux aarch64: Kernel 5.5+
• Android (with appropriate kernel support)

Sources: README.md:14-16

Q: Can I use eCapture in a container?

A: Yes, with privileged mode and host network:

docker run --rm --privileged=true --net=host \
  -v /path/on/host:/data \
  gojue/ecapture tls -m pcap --pcapfile=/data/capture.pcapng

Requirements:

• --privileged=true for eBPF operations
• --net=host to access host network interfaces
• Volume mount for output files

See Docker Hub for pre-built images.

Sources: README.md:63-68

Q: What's the difference between CO-RE and non-CO-RE modes?

A:

eCapture v0.8.0+ automatically detects and selects the appropriate mode.

Sources: CHANGELOG.md:560-566

Q: How do I know which bytecode file is being used?

A: Check the startup logs:

INFO BPF bytecode file is matched. bpfFileName=user/bytecode/openssl_3_0_0_kern_core.o
INFO BTF bytecode mode: CORE. btfMode=0

Or use non-CO-RE:

INFO BPF bytecode file is matched. bpfFileName=user/bytecode/openssl_3_0_0_kern_noncore.o
INFO BTF bytecode mode: NON-CORE. btfMode=1

Sources: README.md:99, README.md:213

Capture Scope Questions ​

Q: Can I capture all HTTPS traffic on the system?

A: Yes, by default eCapture captures all processes and users:

# Capture everything
sudo ecapture tls

# Filter by process
sudo ecapture tls --pid=1234

# Filter by user
sudo ecapture tls --uid=1000

# Filter by network (pcap mode)
sudo ecapture tls -m pcap -i eth0 host 192.168.1.1

Sources: cli/cmd/tls.go:100-150

Q: Does eCapture work with statically compiled OpenSSL?

A: Yes, specify the binary path directly:

sudo ecapture tls --libssl=/path/to/static/binary

This works for statically linked nginx, curl, or custom applications.

Sources: README.md:169

Q: Can I capture multiple protocols simultaneously?

A: No, each eCapture instance runs one module. To capture multiple protocols, run multiple instances:

# Terminal 1: Capture TLS
sudo ecapture tls -m pcap --pcapfile=tls.pcapng &

# Terminal 2: Capture MySQL
sudo ecapture mysqld &

# Terminal 3: Capture bash
sudo ecapture bash &

Sources: cli/cmd/root.go:150-200

Performance Questions ​

Q: What is the performance impact on target applications?

A: Minimal in most cases:

• CPU overhead: 1-5% typically
• Memory overhead: Depends on --mapsize setting
• Latency impact: Microseconds per function call

v1.4.3 specifically improved performance to reduce impact on target programs.

To minimize impact:

• Use targeted filters (--pid, --uid)
• Adjust --mapsize conservatively
• Use pcap mode instead of text mode for high-throughput scenarios

Sources: CHANGELOG.md:661-662

Q: How much disk space will pcap files use?

A: Depends on traffic volume:

• Typical HTTPS browsing: 10-50 MB/hour
• Heavy API traffic: 100-500 MB/hour
• High-throughput scenarios: GB/hour

Use file rotation (v1.2.0+):

sudo ecapture tls -m pcap --pcapfile=capture.pcapng \
  --eventrotatesize=100 --eventrotatetime=3600

Rotates when file reaches 100MB or every 3600 seconds.

Sources: CHANGELOG.md:147-148

Decryption Questions ​

Q: Can eCapture decrypt TLS 1.3 traffic?

A: Yes, for all supported libraries:

• OpenSSL: TLS 1.2 and 1.3
• BoringSSL: TLS 1.2 and 1.3
• Go TLS: TLS 1.2 and 1.3
• GnuTLS: TLS 1.2 and 1.3 (v1.3.0+)

TLS 1.3 uses multiple traffic secrets (CLIENT_HANDSHAKE_TRAFFIC_SECRET, etc.) instead of a single master secret.

Sources: kern/openssl_masterkey.c:50-150

Q: Why aren't some connections being decrypted?

A: Possible reasons:

1. Handshake not captured: eCapture must see the TLS handshake

   • Start eCapture before establishing connections
   • Or use connection pooling/keep-alive

2. Non-standard cipher: Some ciphers may not be supported

   • Check cipher suite in Wireshark

3. Key exchange method: Some key exchange methods are not supported

   • DHE/ECDHE work fine
   • RSA key exchange requires different approach

4. Resumed sessions: Session resumption may not capture new keys

   • Clear session cache and reconnect

Sources: kern/openssl_masterkey.c:200-400

Q: Can I use eCapture with Wireshark simultaneously?

A: Yes, two approaches:

Approach 1: Real-time with keys

# Terminal 1: Capture keys
sudo ecapture tls -m keylog --keylogfile=keys.log

# Terminal 2: Capture packets
sudo tcpdump -i eth0 -w - port 443 | wireshark -k -i -

Then in Wireshark: Edit → Preferences → Protocols → TLS → (Pre)-Master-Secret log filename → Browse to keys.log

Approach 2: Pcap mode

# Capture with eCapture
sudo ecapture tls -m pcap -i eth0 --pcapfile=capture.pcapng

# Open in Wireshark (keys embedded in DSB)
wireshark capture.pcapng

Sources: README.md:236-248

Protocol-Specific Questions ​

Q: Does eCapture support HTTP/3 (QUIC)?

A: Yes, pcap mode supports UDP-based protocols including QUIC/HTTP3:

sudo ecapture tls -m pcap -i eth0 --pcapfile=http3.pcapng udp port 443

Sources: README.md:179

Q: Can I capture gRPC traffic?

A: Yes, gRPC uses HTTP/2 over TLS, which eCapture supports:

# Text mode (parsed)
sudo ecapture tls -m text

# Pcap mode (for Wireshark analysis)
sudo ecapture tls -m pcap -i eth0 --pcapfile=grpc.pcapng

Sources: user/event/event_http2.go:50-200

Q: What about WebSocket traffic?

A: WebSocket over TLS is captured as HTTP upgrade request:

sudo ecapture tls -m text

You'll see the initial HTTP upgrade request and subsequent WebSocket frames.

Sources: user/event/event_http.go:100-200

Output Format Questions ​

Q: What's the difference between pcap and pcapng?

A:

eCapture uses pcapng format for Decryption Secrets Block (DSB) support.

Sources: user/module/probe_openssl.go:900-1000

Q: Can I export to other formats?

A: Yes, use external tools:

# Convert pcapng to pcap
editcap capture.pcapng capture.pcap

# Extract HTTP objects
tshark -r capture.pcapng --export-objects http,output_dir/

# Convert to JSON
tshark -r capture.pcapng -T json > capture.json

# Convert to CSV
tshark -r capture.pcapng -T fields -E separator=, > capture.csv

Sources: README.md:232

Integration Questions ​

Q: How do I integrate eCapture with my monitoring system?

A: Several options:

1. WebSocket interface (v1.4.0+):

   go

   // Connect to ws://localhost:28257
   // Receive protobuf LogEntry messages

   See protobuf/PROTOCOLS.md for protocol details.

2. Parse text output:

   bash

   sudo ecapture tls 2>&1 | your-parser

3. Monitor pcap files:

   bash

   sudo ecapture tls -m pcap --pcapfile=/var/log/capture.pcapng
   # Process with tshark or pyshark

4. Forward events: See docs/event-forward-api.md for forwarding to Burp Suite and other tools.

Sources: README.md:299-331, CHANGELOG.md:91-96

Q: Can I use eCapture in CI/CD pipelines?

A: Yes, for testing TLS implementations:

#!/bin/bash
# Start eCapture in background
sudo ecapture gotls --elfpath=/app/binary --hex > capture.log 2>&1 &
ECAP_PID=$!

# Run tests
./run-tests.sh

# Stop eCapture
sudo kill $ECAP_PID

# Verify captured data
grep "GET /api/test" capture.log || exit 1

See .github/workflows/go-c-cpp.yml for CI examples.

Sources: CHANGELOG.md:34-37

Security and Compliance Questions ​

Q: Is eCapture safe to use in production?

A: eCapture is designed for debugging and security analysis. Consider:

Pros:

• Read-only operations (no data modification)
• Minimal performance impact
• Can be restricted by pid/uid filters

Cons:

• Requires root/CAP_BPF
• Captures sensitive data (credentials, tokens)
• Creates audit trail implications

Recommendations:

• Use in non-production first
• Implement access controls
• Review data retention policies
• Consider regulatory compliance (GDPR, HIPAA, etc.)

Sources: README.md:14-16

Q: How do I securely store captured data?

A: Best practices:

1. Encrypt at rest:

   bash

   sudo ecapture tls -m keylog --keylogfile=keys.log
   gpg --encrypt keys.log
   shred -u keys.log  # Securely delete original

2. Use temporary directories:

   bash

   sudo ecapture tls -m pcap --pcapfile=/tmp/capture.pcapng
   # Process immediately and delete

3. Implement retention policies:

   bash

   # Delete captures older than 7 days
   find /var/log/ecapture -name "*.pcapng" -mtime +7 -delete

4. Audit access:

   bash

   # Log who accesses captured data
   sudo auditctl -w /var/log/ecapture -p r -k ecapture_access

Q: Does eCapture bypass certificate pinning?

A: No, eCapture doesn't bypass or modify any security mechanisms. It captures:

• Plaintext data after SSL/TLS decryption in the application's memory
• Master secrets from the TLS handshake

This is fundamentally different from MITM attacks. eCapture observes what the application already has access to.

Sources: kern/openssl_kern.c:100-200

Additional Resources ​

Diagnostic Commands ​

System information:

# Kernel version
uname -r

# BTF support
ls -l /sys/kernel/btf/vmlinux
cat /boot/config-$(uname -r) | grep BTF

# eBPF features
cat /proc/sys/kernel/unprivileged_bpf_disabled

# Capabilities
capsh --print

Library detection:

# Find OpenSSL libraries
ldconfig -p | grep libssl

# Check OpenSSL version
openssl version

# List loaded libraries for a process
lsof -p $(pidof nginx) | grep libssl

# Check ELF symbols
nm -D /usr/lib/libssl.so | grep SSL_write

Network interfaces:

# List interfaces
ip link show

# Check interface traffic
ip -s link show eth0

# Verify packet capture
tcpdump -i eth0 -c 1 port 443

Sources: README.md:228-232

Debug Logging ​

Enable verbose logging:

# Set log level
sudo ecapture tls --loglevel=debug

# Or use environment variable
export ECAPTURE_LOG_LEVEL=debug
sudo -E ecapture tls

Log files location:

• stdout: Real-time logs
• --logger flag: Write logs to file

Sources: cli/cmd/root.go:250-300

Getting Help ​

1. GitHub Issues: https://github.com/gojue/ecapture/issues
2. Documentation: https://ecapture.cc
3. Changelog: CHANGELOG.md for version-specific issues
4. Compilation guide: COMPILATION.md for build issues

When reporting issues, include:

• eCapture version: ecapture version
• Kernel version: uname -r
• BTF support: ls /sys/kernel/btf/vmlinux
• Library version: openssl version or go version
• Complete command and output
• Relevant log snippet

Sources: README.md:317