gojue/ecapture repository overview

⁠eCapture

eCapture is an eBPF-based tool for capturing plaintext TLS/SSL traffic without installing CA certificates, configuring a proxy, or modifying the target application.

It is designed for API debugging, network troubleshooting, microservice traffic analysis, and authorized security auditing.

⁠Core Modules

The tls module supports OpenSSL 1.0.x, 1.1.x, 3.x, and newer releases.

⁠Capture Modes

• text — Print captured plaintext directly to the terminal
• pcap / pcapng — Generate plaintext packet captures for Wireshark
• keylog — Export TLS session keys for Wireshark or TShark

⁠Requirements

• Linux host
• linux/amd64 or linux/arm64
• x86_64: Linux kernel 4.18+
• aarch64: Linux kernel 5.5+
• Root privileges or the required Linux capabilities

⁠Quick Start

⁠Pull the image

docker pull gojue/ecapture:latest

⁠Capture OpenSSL/BoringSSL plaintext

For Linux 5.8 and newer:

docker run --rm -it \
  --cap-add=BPF \
  --cap-add=PERFMON \
  --cap-add=SYS_PTRACE \
  --pid=host \
  -v /sys/kernel/debug:/sys/kernel/debug:ro \
  -v /sys/fs/bpf:/sys/fs/bpf \
  -v /etc:/etc:ro \
  -v /usr:/usr:ro \
  -v /lib:/lib:ro \
  gojue/ecapture:latest tls

Then make an HTTPS request on the host:

curl https://example.com

eCapture will display the captured plaintext request and response.

The host library directories are mounted so eCapture can locate the target TLS libraries. If a library is stored elsewhere, mount its directory and specify it explicitly:

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

⁠Capture GnuTLS plaintext

docker run --rm -it \
  --cap-add=BPF \
  --cap-add=PERFMON \
  --cap-add=SYS_PTRACE \
  --pid=host \
  -v /sys/kernel/debug:/sys/kernel/debug:ro \
  -v /sys/fs/bpf:/sys/fs/bpf \
  -v /etc:/etc:ro \
  -v /usr:/usr:ro \
  -v /lib:/lib:ro \
  gojue/ecapture:latest gnutls

Use --gnutls when the library cannot be detected automatically:

gnutls --gnutls=/path/to/libgnutls.so

⁠Capture GoTLS plaintext

Mount the target Go ELF binary into the container:

docker run --rm -it \
  --cap-add=BPF \
  --cap-add=PERFMON \
  --cap-add=SYS_PTRACE \
  --pid=host \
  -v /sys/kernel/debug:/sys/kernel/debug:ro \
  -v /sys/fs/bpf:/sys/fs/bpf \
  -v /path/to/application:/app:ro \
  gojue/ecapture:latest \
  gotls --elfpath=/app/server

Use --pid to capture a specific process:

gotls --elfpath=/app/server --pid=1234

⁠Save Plaintext Traffic as PCAPNG

PCAP mode uses Linux Traffic Control and therefore requires CAP_NET_ADMIN and access to the host network namespace:

docker run --rm -it \
  --cap-add=BPF \
  --cap-add=PERFMON \
  --cap-add=SYS_PTRACE \
  --cap-add=NET_ADMIN \
  --pid=host \
  --net=host \
  -v /sys/kernel/debug:/sys/kernel/debug:ro \
  -v /sys/fs/bpf:/sys/fs/bpf \
  -v /etc:/etc:ro \
  -v /usr:/usr:ro \
  -v /lib:/lib:ro \
  -v "$PWD":/output \
  gojue/ecapture:latest \
  tls -m pcap -i eth0 \
  --pcapfile=/output/ecapture.pcapng \
  tcp port 443

Replace eth0 with the correct host network interface. The resulting ecapture.pcapng file can be opened directly in Wireshark.

⁠Older Kernels

Linux kernels older than 5.8 do not provide separate CAP_BPF and CAP_PERFMON capabilities. Use CAP_SYS_ADMIN instead:

docker run --rm -it \
  --cap-add=SYS_ADMIN \
  --cap-add=SYS_PTRACE \
  --pid=host \
  -v /sys/kernel/debug:/sys/kernel/debug:ro \
  -v /sys/fs/bpf:/sys/fs/bpf \
  -v /etc:/etc:ro \
  -v /usr:/usr:ro \
  -v /lib:/lib:ro \
  gojue/ecapture:latest tls

Add --cap-add=NET_ADMIN --net=host when using PCAP mode.

⁠Privileged Compatibility Mode

If the Docker Engine, libcap version, or host security policy does not support the required capabilities, privileged mode can be used as a compatibility option:

docker run --rm -it \
  --privileged=true \
  --pid=host \
  --net=host \
  -v /sys/kernel/debug:/sys/kernel/debug \
  -v /sys/fs/bpf:/sys/fs/bpf \
  -v /etc:/etc:ro \
  -v /usr:/usr:ro \
  -v /lib:/lib:ro \
  gojue/ecapture:latest tls

⁠Security Notice

Captured traffic may contain credentials, cookies, access tokens, personal information, and other sensitive data.

Use eCapture only on systems and networks you are authorized to inspect. Limit the capture scope with process, user, or cgroup filters whenever possible.

⁠Learn More

Advanced features include PID and UID filtering, cgroup filtering, TLS key export, event forwarding, remote configuration, shell command auditing, database query auditing, and the eCaptureQ graphical client.

• Official Website⁠
• GitHub Repository⁠
• Documentation⁠
• Minimum Privileges Guide⁠