中文介绍 | English | 日本語

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

Note

Supports Linux/Android kernel versions x86_64 4.18 and above, aarch64 5.5 and above. Does not support Windows and macOS system.

---

• How eCapture works
• eCapture User Manual
• Getting started
• eCapture Architecture
• What's eBPF
• How to compile
• Contributing

---

How eCapture works

• SSL/TLS plaintext capture, support openssl\libressl\boringssl\gnutls\nspr(nss) libraries.
• GoTLS plaintext support go tls library, which refers to encrypted communication in https/tls programs written in the golang language.
• bash audit, capture bash command for Host Security Audit.
• mysql query SQL audit, support mysqld 5.6\5.7\8.0, and mariadDB.

eCapture User Manual

Youtube video: How to use eCapture v0.1.0

Getting started

use ELF binary file

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

• Linux kernel version >= 4.18 is required.
• Enable BTF BPF Type Format (BTF) (Optional, 2022-04-17)

use docker image

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

Command line options

Note

Need ROOT permission.

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。

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.

• bash capture bash command
• gnutls capture gnutls text content without CA cert for gnutls libraries.
• gotls Capturing plaintext communication from Golang programs encrypted with TLS/HTTPS.
• mysqld capture sql queries from mysqld 5.6/5.7/8.0 .
• nss capture nss/nspr encrypted text content without CA cert for nss/nspr libraries.
• postgres capture sql queries from postgres 10+.
• tls use to capture tls/ssl text content without CA cert. (Support openssl 1.0.x/1.1.x/3.0.x or newer). You can use ecapture -h to view the list of subcommands.

OpenSSL Module

The OpenSSL module supports three capture modes:

• pcap/pcapng mode stores captured plaintext data in pcap-NG format.
• keylog/key mode saves the TLS handshake keys to a file.
• text mode directly captures plaintext data, either outputting to a specified file or printing to the command line.

Pcap Mode

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.

./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.

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.

./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

./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.

check your server BTF config：

cfc4n@vm-server:~$# uname -r
4.18.0-305.3.1.el8.x86_64
cfc4n@vm-server:~$# cat /boot/config-`uname -r` | grep CONFIG_DEBUG_INFO_BTF
CONFIG_DEBUG_INFO_BTF=y

gotls command

capture tls text context.

Step 1:

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

Step 2:

/home/cfc4n/go_https_client

more help

./ecapture gotls -h

bash Module

capture bash command : ecapture bash

ps -ef | grep foo

eCapture Architecture

What's eBPF

eBPF

How to compile

Linux Kernel: >= 4.18.

Tools

• golang 1.21 or newer
• clang 9.0 or newer
• cmake 3.18.4 or newer
• clang backend: llvm 9.0 or newer
• kernel config:CONFIG_DEBUG_INFO_BTF=y (Optional, 2022-04-17)

command

ubuntu

If you are using Ubuntu 20.04 or later versions, you can use a single command to complete the initialization of the compilation environment.

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/gojue/ecapture/master/builder/init_env.sh)"

other Linux

In addition to the software listed in the 'Toolchain Version' section above, the following software is also required for the compilation environment. Please install it yourself.

• linux-tools-common
• linux-tools-generic
• pkgconf
• libelf-dev

Clone the repository code and compile it

Caution: The following make command will install libpcap into the system directory if libpcap.a does not exist under /usr/local/lib. If you have installed libpcap in system without libpcap.a, it maybe break your libpcap's headers.

git clone --recurse-submodules [email protected]:gojue/ecapture.git
cd ecapture
make
bin/ecapture

compile without BTF

eCapture support BTF disabled with command make nocore to compile at 2022/04/17. It can work normally even on Linux systems that do not support BTF.

make nocore
bin/ecapture --help

cross-compilation

Kernel header files

To cross-compile the eCapture tool, you need to install the kernel header files for the target architecture. you need to install the linux-source package.

kernel_ver=`uname -r | cut -d'-' -f 1`
sudo apt-get install -y linux-source-$kernel_ver
cd /usr/src
sudo tar -xf linux-source-${kernel_ver}.tar.bz2
cd /usr/src/linux-source-${kernel_ver}
test -f .config || yes "" | sudo make oldconfig

ToolChains

To cross-compile binary files for the aarch64 architecture on an amd64 architecture system, you need to install the gcc-aarch64-linux-gnu toolchain. Similarly, to cross-compile binary files for the amd64 architecture on an aarch64 system, you need to install the gcc-x86-64-linux-gnu toolchain.

• amd64 arch: gcc-aarch64-linux-gnu
• arm64 arch: gcc-x86-64-linux-gnu

Build Commands

To build an arm64 artifact on an ubuntu amd64 system, you can set the CROSS_ARCH environment variable to achieve cross-compilation.

CROSS_ARCH=arm64 make

Stargazers over time

Contributing

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