ecapture README

The project's README from github.com/gojue/ecapture. As one markdown file: README.md.

eCapture Logo

汉字 | English

GitHub stars GitHub forks CI Github Version

eCapture(旁观者): capture SSL/TLS text content without a CA certificate using eBPF.

[!IMPORTANT]
Supports Linux/Android on x86_64 (kernel 4.18+) and aarch64 (kernel 5.5+). Kernel version requirements apply per CPU architecture for both Linux and Android. Need ROOT permission or specific Linux capabilities. Does not support Windows and macOS system.

Introduction

Getting started

Download

ELF binary file

[!TIP] support Linux/Android x86_64/aarch64.

Download ELF zip file release , unzip and use by command sudo ecapture --help.

Docker image

[!TIP] Linux only.

# pull docker image
docker pull gojue/ecapture:latest
# run
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, consider specific capabilities instead. See Minimum Privileges Guide.

see Docker Hub for more information.

Capture openssl text content.

sudo ecapture tls

eCapture will automatically detect the system's OpenSSL library and start capturing plaintext. When you make an HTTPS request (e.g., curl https://google.com), the captured request and response will be displayed:

...
INF module started successfully. moduleName=EBPFProbeOPENSSL
??? UUID:233851_233851_curl_5_1_172.16.71.1:51837, Name:HTTP2Request, Type:2, Length:304
header field ":method" = "GET"
header field ":path" = "/"
header field ":authority" = "google.com"
...

📄 For complete output examples, see docs/example-outputs.md.

Modules

The eCapture tool comprises 8 modules that respectively support plaintext capture for TLS/SSL encryption libraries like OpenSSL, GnuTLS, NSPR, BoringSSL, and GoTLS. Additionally, it facilitates software audits for Bash, MySQL, and PostgreSQL applications.

OpenSSL Module

eCapture search /etc/ld.so.conf file default, to search load directories of SO file, and search openssl shard libraries location. or you can use --libssl flag to set shard library path.

If target program is compile statically, you can set program path as --libssl flag value directly。

The OpenSSL module supports three capture modes:

Pcap Mode

Supported TLS encrypted http 1.0/1.1/2.0 over TCP, and http3 QUIC protocol over UDP. You can specify -m pcap or -m pcapng and use it in conjunction with --pcapfile and -i parameters. The default value for --pcapfile is ecapture_openssl.pcapng.

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

This command saves captured plaintext data packets as a pcapng file, which can be viewed using Wireshark.

📄 For complete pcapng mode output, see docs/example-outputs.md.

Keylog Mode

You can specify -m keylog or -m key and use it in conjunction with the --keylogfile parameter, which defaults to ecapture_masterkey.log.

The captured OpenSSL TLS Master Secret information is saved to --keylogfile. You can also enable tcpdump packet capture and then use Wireshark to open the file and set the Master Secret path to view plaintext data packets.

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

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

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

Text Mode

sudo ecapture tls -m text will output all plaintext data packets. (Starting from v0.7.0, it no longer captures SSLKEYLOG information.)

GoTLS Module

Similar to the OpenSSL module.

gotls command

capture tls text context.

Step 1:

sudo ecapture gotls --elfpath=/home/cfc4n/go_https_client --hex

Step 2:

/home/cfc4n/go_https_client

more help

sudo ecapture gotls -h

Other Modules

such as bash\mysqld\postgres modules, you can use ecapture -h to view the list of subcommands.

Videos

eCaptureQ GUI Application

eCaptureQ is a cross-platform graphical user interface client for eCapture, visualizing eBPF TLS capture capabilities. Built using the Rust + Tauri + React technology stack, it provides a real-time, responsive interface, enabling easy analysis of encrypted traffic without the need for CA certificates. It simplifies complex eBPF capture techniques, making them easy to use. Supports two modes:

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:

Stargazers over time

Stargazers over time

Security & Operations

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 offset address for uprobe to support statically compiled OpenSSL libraries. Refer to the compilation guide for compilation instructions.

Configurations Remote Update

After eCapture is running, you can dynamically modify the 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.

ecapture (gojue/ecapture)

Searching Database…

15.5K ·GitHub
Ecapture
Что это такое?Опенсорсный консольный инструмент для безопасности, который с помощью eBPF перехватывает SSL/TLS-трафик в открытом виде — без установки CA-сертификатов и MITM-прокси. Он также может проверять команды в shell и запросы к базам данных на хосте.
Это библиотека, которую я подключаю к своему коду, или отдельный инструмент?Отдельный консольный инструмент, который вы запускаете через sudo на машине, которую хотите наблюдать, — это не библиотека. Есть ещё eCaptureQ — отдельный кроссплатформенный GUI-клиент на Rust, Tauri и React.
Как его запустить?Скачайте ELF-архив под свою архитектуру с GitHub Releases, распакуйте и выполните 'sudo ecapture --help'. На Linux можно также использовать Docker-образ; инструмент сам находит системную библиотеку OpenSSL и начинает захват открытого трафика.
Нужны ли мне root-права или какие-то сертификаты для работы?Root нужен обязательно — либо права ROOT, либо определённые Linux capabilities; в гайде Minimum Privileges описана настройка с минимальными правами. Сертификаты устанавливать не надо: OpenSSL, LibreSSL, BoringSSL, GnuTLS, NSS/NSPR и TLS-библиотека Go поддерживаются из коробки.
О каких главных подводных камнях стоит знать заранее?Windows и macOS не поддерживаются, а Docker-образ работает только на Linux — он запускается с привилегиями, о чём README предупреждает как о моменте безопасности. Для программ, скомпилированных со статическим OpenSSL, передайте путь к бинарнику через флаг --libssl.
На каких системах он работает?Linux и Android, на x86_64 (ядро 4.18 или новее) и aarch64/arm64 (ядро 5.5 или новее); требования к ядру зависят от архитектуры процессора.
Что ещё он может перехватывать, кроме HTTPS-трафика?Всего восемь модулей. Помимо TLS-библиотек (OpenSSL, GnuTLS, NSS, Go TLS) он проверяет команды bash и zsh для аудита безопасности хоста, а также захватывает SQL-запросы из mysqld 5.6/5.7/8.0 и MariaDB, плюс PostgreSQL 10+.
Как выгрузить перехваченные данные?У модуля OpenSSL три режима: text выводит открытый текст в терминал или файл; pcap/pcapng сохраняет файл pcapng, который можно открыть в Wireshark (HTTP/1.x, HTTP/2 поверх TCP и HTTP/3 QUIC поверх UDP); keylog записывает мастер-ключи TLS для расшифровки в Wireshark или tshark. События также можно пересылать в такие инструменты, как Burp Suite.
Есть ли GUI, или это только терминал?Есть eCaptureQ — кроссплатформенный GUI-клиент на Rust + Tauri + React. В режиме Integrated он работает на Linux/Android, а в режиме Remote клиенты на Windows, macOS или Linux подключаются к сервису eCapture, запущенному на другой машине.
Как он расшифровывает TLS без CA-сертификата?Он не перехватывает сеть, а подключает eBPF uprobes к функциям SSL/TLS-библиотеки внутри целевого процесса и читает открытый текст и TLS-ключи напрямую — поэтому сертификата, которому должны доверять клиенты, просто нет. Смещение uprobe можно даже задать вручную, чтобы поддержать программы со статически слинкованным OpenSSL.
What are similar projects?kubeshark, brook, openssl, cilium, scapy, openvpn, smartdns, vps-security-enhancement-scripts
Which topics is it in?packet-capture, network-analysis, ebpf, ssl, network-security, tls, mysql, observability, encryption, golang, security-tools, c
Creator
gojue
Size
16.7 MB
Stars
15.5K
Updated
CommitOct 19Releasev2.8.2Oct 19
Age
4y
Commits · 90 Days