中文介绍 | 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 git@github.com: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.

tnt4235286/ecapture