ecapture

[!IMPORTANT] Supports Linux on x86_64 (kernel 4.18+), aarch64 (kernel 5.5+), and LoongArch64 loong64 (kernel 6.6+). Android supports x86_64 and aarch64 with the existing kernel minimums. Requires root privileges or specific Linux capabilities. Does not support Windows or macOS.

---

• Introduction
• Getting started
  • Download
    • ELF binary file
    • Docker image
  • Capture OpenSSL plaintext data
  • Modules
    • OpenSSL module
    • GoTLS module
    • Other modules
  • Videos
• Star History
• Security & operations
• Contributing
• Compilation

Introduction

• Captures plaintext TLS/SSL traffic from OpenSSL, LibreSSL, BoringSSL, GnuTLS, and NSS/NSPR libraries.
• Supports plaintext capture for Go TLS programs, including HTTPS/TLS traffic in Go applications.
• Audits bash and zsh command history for host security monitoring.
• Audits MySQL queries and supports MySQL 5.6/5.7/8.0 and MariaDB.

Run ecapture --help for the commands and flags available in your installed version.

Getting started

Download

ELF binary file

[!TIP] Supports Linux on x86_64, aarch64, and LoongArch64; Android supports x86_64 and aarch64.

Download the ELF binary package from the releases page, extract it, and run:

sudo ecapture --help

Docker image

[!TIP] Linux only.

# Pull the Docker image
docker pull gojue/ecapture:latest

# Run it
docker run --rm --privileged=true --net=host -v ${HOST_PATH}:${CONTAINER_PATH} gojue/ecapture ARGS

⚠️ Security note: --privileged=true grants full host access. For production use, prefer specific capabilities instead. See the Minimum Privileges Guide.

See Docker Hub for more information.

Capture OpenSSL plaintext data

sudo ecapture tls

eCapture automatically detects the system's OpenSSL library and starts capturing plaintext traffic. Generate an HTTPS request with an OpenSSL-linked client to see its captured reads and writes. This synthetic HTTP/1.1 example illustrates the text format:

[2026-01-01 12:00:00.000] PID:1234 TID:1234 Comm:curl FD:5 WRITE (37 bytes):
GET / HTTP/1.1
Host: example.com

📄 For output formats and verification examples, see docs/example-outputs.md.

Modules

The eCapture tool includes 8 modules that can capture plaintext data from TLS/SSL libraries such as OpenSSL, GnuTLS, NSS/NSPR, BoringSSL, and GoTLS. It also supports auditing commands and queries from Bash, MySQL, and PostgreSQL applications.

• bash: captures bash commands
• zsh: captures zsh commands
• gnutls: captures plaintext from GnuTLS libraries without needing a CA certificate
• gotls: captures plaintext communication from Go programs using TLS/HTTPS
• mysqld: captures SQL queries from MySQL 5.6/5.7/8.0 and MariaDB
• nss: captures plaintext from NSS/NSPR libraries without needing a CA certificate
• postgres: captures SQL queries from PostgreSQL 10+
• tls: captures plaintext TLS/SSL traffic without a CA certificate (supports OpenSSL 1.0.x/1.1.x/3.0.x and newer)

You can use ecapture -h to view the full list of subcommands.

OpenSSL module

eCapture searches the default library paths from /etc/ld.so.conf to locate shared libraries and detect the OpenSSL library location. You can also set the library path explicitly with the --libssl flag.

If the target program is statically linked, you can set the program path directly as the value of the --libssl flag.

The OpenSSL module supports three output modes:

• pcap/pcapng mode stores encrypted network packets and TLS secrets in pcap-NG format.
• keylog/key mode saves TLS handshake keys to a file.
• text mode captures plaintext through function hooks by default, or reconstructs complete HTTP/1.1 and HTTP/2 messages from live pcapng and DSB data with --text-source=pcapng.

For OpenSSL, GoTLS, and GnuTLS, --eventaddr is the uniform primary event destination. It accepts stdout, a plain path or file:// URI, tcp://host:port, and ws:///wss:// (ordered binary frames). The mode selects text, NSS Key Log, or pcapng representation; the address selects only the transport. --keylogfile and --pcapfile remain compatible primary-file aliases in their respective modes. Setting --eventaddr together with the corresponding alias is an error. In pcapng mode, --keylogfile is a separate optional keylog artifact.

Live decryption for text output

Use -m text --text-source=pcapng with tls, gotls, or gnutls to reconstruct complete HTTP/1.1 and HTTP/2 messages from the captured network stream. Each message includes direction, timestamp, IP/port tuple, connection identity, and an HTTP/2 stream ID when applicable. host comes from the HTTP Host header or HTTP/2 :authority; domain_source="server_ip" marks a fallback to the server IP. Output goes to --eventaddr (stdout by default). Raw pcapng and a standalone keylog are disabled by default; specify --pcapfile or --keylogfile to save either artifact.

sudo ecapture tls -m text --text-source=pcapng -i eth0 --eventaddr /tmp/http.events 'tcp port 443'
sudo ecapture gotls -m text --text-source=pcapng --elfpath /path/to/go-client -i eth0 --pcapfile /tmp/raw.pcapng 'tcp port 443'
sudo ecapture gnutls -m text --text-source=pcapng --gnutls /path/to/libgnutls.so -i eth0 'tcp port 443'

The decryptor waits for TLS secrets that may appear in a DSB after the corresponding packets. HTTP/3 over QUIC v1/v2 has GoTLS test fixtures; support depends on the TLS backend supplying the required secrets. The following options require text mode with the pcapng source:

Option	Output / selection
--text-raw	Authenticated TLS/QUIC STREAM bytes and QUIC DATAGRAM messages
--text-http-events	Incremental HTTP/1.x, HTTP/2, HTTP/3, SSE and HTTP/2 gRPC events
--text-max-decoded-body N	Per-message gzip expansion limit in bytes; requires HTTP events; zero keeps content encoding
--text-protocol dot|doh|doq|mqtt|redis	Explicit application parser; MQTT 3.1.1 and fixed-length RESP2/RESP3
--text-tls-upgrade smtp|imap|pop3|ldap|postgres|mysql|connect|https-connect	One explicit STARTTLS/SSLRequest/CONNECT negotiation; HTTPS CONNECT includes one inner TLS layer
--text-udp-protocol dtls	DTLS 1.2 ECDHE-RSA AES-128/256-GCM records; the default UDP protocol is QUIC

Structured events use lossless hex plus metadata JSON, preserving headers, trailers, message/stream IDs, early-data status and TLS depth, including events with no payload. Stream chunks carry offsets/end markers; datagrams retain message boundaries without invented stream offsets. Application selection is explicit, not automatic ALPN routing. Raw, HTTP-event and explicit application modes are mutually exclusive. HTTP reload uses the corresponding underscore JSON keys; omitted module options reset to their zero defaults. Mail/database upgrades negotiate TLS; use --text-raw for application bytes without a supported parser. gRPC events preserve schema-free Protobuf bytes. Operational logs contain payload-free diagnostics. ECH still requires ECH_SECRET/ECH_CONFIG material that current probes do not capture; upgrading the decryptor alone does not enable live ECH. DTLS/DATAGRAM do not imply WebRTC, WebTransport or MASQUE decoding. With v1.4.0, some zero-length-client-CID QUIC loopback captures still fail connection routing; the maintained DoQ/DATAGRAM baseline uses 8-byte client CIDs.

To verify the source independently, add --pcapfile /tmp/raw.pcapng to the capture command and send a request with a unique path or response token. After stopping eCapture, preload only its embedded secrets with Wireshark >= 4.4 to handle DSBs arriving after their packets, then compare TLS stream 0:

keys=$(mktemp)
editcap --extract-secrets /tmp/raw.pcapng - >"$keys"
tshark -n -r /tmp/raw.pcapng -o "tls.keylog_file:$keys" -q -z follow,tls,ascii,0
rm -f -- "$keys"

The optional file receives the same pcapng bytes as the live SDK stream.

--logaddr carries eCapture runtime logs only. Console runtime logs use stderr, while captured stdout contains only event bytes. eCaptureQ is additive: enabling it does not replace --eventaddr or --logaddr.

Pcap mode

Supports TLS-encrypted HTTP 1.0/1.1/2.0 over TCP and HTTP/3 (QUIC) over UDP.

You can specify -m pcap or -m pcapng together with --pcapfile and -i. The current compatible default value of --pcapfile is save.pcapng.

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

This command saves captured network packets and TLS secrets in a pcapng file. Wireshark uses its embedded secrets to decrypt supported TLS traffic.

📄 For pcapng verification, see docs/example-outputs.md.

Keylog mode

You can specify -m keylog or -m key together with the --keylogfile option. The current compatible default output file is ecapture_openssl_key.log.

The captured OpenSSL TLS master secret is saved to --keylogfile. You can also enable tcpdump capture and then open the file in Wireshark, setting the master secret path to view plaintext packets.

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

You can also use tshark for real-time decryption and display:

tshark -o tls.keylog_file:openssl_keylog.log -Y http -T fields -e http.file_data -f "port 443" -i eth0

Text mode

sudo ecapture tls -m text

This outputs plaintext bytes captured from the hooked TLS reads and writes.

GoTLS module

Similar to the OpenSSL module.

gotls command

Capture TLS plaintext data.

Step 1:

sudo ecapture gotls --elfpath=/path/to/go-client --hex

Step 2:

/path/to/go-client

More help

sudo ecapture gotls -h

Other modules

Modules such as bash, mysqld, and postgres can also be used. You can view the full list with ecapture -h.

Videos

• YouTube video: How to use eCapture v0.1.0
• eCapture: supports capturing plaintext of Go TLS/HTTPS traffic

eCaptureQ GUI application

eCaptureQ is a cross-platform graphical client for eCapture that visualizes eBPF-based TLS capture capabilities. Built with Rust + Tauri + React, it provides a responsive, real-time interface for analyzing encrypted traffic without needing a CA certificate. It simplifies complex eBPF capture workflows and makes them easier to use.

It supports two modes:

• Integrated mode: unified Linux/Android execution
• Remote mode: Windows/macOS/Linux clients connect to a remote eCapture service

Event forwarding

Event forwarding projects

Video demonstration

https://github.com/user-attachments/assets/c8b7a84d-58eb-4fdb-9843-f775c97bdbfb

🔗 GitHub repository

Protobuf protocols

For details of the Protobuf log schema used by eCapture/eCaptureQ, see:

• protobuf/PROTOCOLS.md

Star History

Security & operations

• Security policy — vulnerability reporting and supported versions
• Minimum privileges — required Linux capabilities and least-privilege configuration
• Defense & detection — how to detect and defend against unauthorized usage
• Performance benchmarks — repeatable overhead and event-loss measurements
• Release verification — how to verify the integrity of release artifacts

Contributing

See CONTRIBUTING for details on submitting patches and the contribution workflow.

Compilation

Custom compilation

You can customize the features you want, such as setting the uprobe offset address to support statically linked OpenSSL libraries. Refer to the compilation guide for detailed instructions.

Loong64 releases are cross-built on Ubuntu 24.04 x86_64 with LLVM 22.1.8. Use TARGET_ARCH=loong64; the sysroot, BTF, verification steps, and current runtime validation limits are documented in Loong64 build and validation.

Remote configuration updates

After eCapture is running, you can dynamically modify configurations through HTTP interfaces. Refer to the HTTP API documentation.

Event forwarding

eCapture supports multiple event-forwarding methods. You can forward events to packet capture software such as Burp Suite. For details, refer to the Event Forwarding API documentation.