gojue/ecaptureCapture SSL/TLS plaintext with eBPF—no MITM proxy or custom CA installation. Supports Linux and Android on x86_64 and arm64.
<p align="center">
<img src="https://assets.kitploit.com/production/public/readmes/6909/d8c1e57110e6b78645e08be93bca888b988d3c7ae7580e14f2e7c20b034cc21a.png" alt="eCapture logo" width="180" />
</p>
<p align="center">
<strong>eCapture (旁观者)</strong><br />
Capture SSL/TLS plaintext with eBPF—no MITM proxy or custom CA installation.
</p>
<p align="center">
<strong>English</strong> · <a href="https://github.com/gojue/ecapture/blob/master/README-zh_Hans.md">汉字</a><br />
<a href="https://github.com/gojue/ecapture/actions/workflows/codeql-analysis.yml"><img alt="CodeQL" src="https://github.com/gojue/ecapture/actions/workflows/codeql-analysis.yml/badge.svg" /></a>
<a href="https://github.com/gojue/ecapture/releases"><img alt="Latest release" src="https://img.shields.io/github/v/release/gojue/ecapture?display_name=tag&include_prereleases&sort=semver" /></a>
<a href="https://ecapture.cc"><img alt="HomePage" src="https://img.shields.io/badge/Home_Page-e0ad15" /></a>
</p>
<p align="center">
<a href="https://www.star-history.com/gojue/ecapture">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/badge?repo=gojue/ecapture&type=rank&theme=dark" />
<source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/badge?repo=gojue/ecapture&type=rank" />
<img alt="Star History Rank" src="https://api.star-history.com/badge?repo=gojue/ecapture&type=rank" />
</picture>
</a>
<a href="https://www.star-history.com/gojue/ecapture">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/badge?repo=gojue/ecapture&type=trending&theme=dark" />
<source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/badge?repo=gojue/ecapture&type=trending" />
<img alt="GitHub Trending Repository of the Day" src="https://api.star-history.com/badge?repo=gojue/ecapture&type=trending" />
</picture>
</a>
</p>
> [!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](https://github.com/gojue/ecapture/blob/master/docs/minimum-privileges.md).
> Does not support Windows or macOS.
----
<!-- MarkdownTOC autolink="true" -->
- [Introduction](#introduction)
- [Getting started](#getting-started)
- [Download](#download)
- [ELF binary file](#elf-binary-file)
- [Docker image](#docker-image)
- [Capture OpenSSL plaintext data](#capture-openssl-plaintext-data)
- [Modules](#modules)
- [OpenSSL module](#openssl-module)
- [GoTLS module](#gotls-module)
- [Other modules](#other-modules)
- [Videos](#videos)
- [Star History](#star-history)
- [Security & operations](#security--operations)
- [Contributing](#contributing)
- [Compilation](#compilation)
<!-- /MarkdownTOC -->
# 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.
# 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](https://github.com/gojue/ecapture/releases), extract it, and run:
```shell
sudo ecapture --help
```
### Docker image
> [!TIP]
> Linux only.
```shell
# 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](https://github.com/gojue/ecapture/blob/master/docs/minimum-privileges.md#method-3-docker-with-specific-capabilities).
See [Docker Hub](https://hub.docker.com/r/gojue/ecapture) for more information.
## Capture OpenSSL plaintext data
```shell
sudo ecapture tls
```
eCapture automatically detects the system's OpenSSL library and starts capturing plaintext traffic. When you make an HTTPS request, such as `curl https://google.com`, the captured request and response are 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](https://github.com/gojue/ecapture/blob/master/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.
```shell
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. The pcapng text source supports TCP TLS with HTTP/1.1 or HTTP/2
payloads; it does not emit generic TLS records or QUIC/HTTP/3.
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, run `tshark -n -r /tmp/raw.pcapng -o tls.keylog_file: -q -z
follow,tls,ascii,0` and compare the request and response with the text output.
The empty keylog setting makes tshark use the DSB embedded in that pcapng.
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`.
```shell
sudo ecapture tls -m pcap -i eth0 --pcapfile=ecapture.pcapng tcp port 443
```
This command saves captured plaintext packets as a pcapng file, which can be opened with Wireshark.
> 📄 For complete pcapng mode output, see [docs/example-outputs.md](https://github.com/gojue/ecapture/blob/master/docs/example-outputs.md#tls-module--pcapng-mode).
#### 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.
```shell
sudo ecapture tls -m keylog -keylogfile=openssl_keylog.log
```
You can also use `tshark` for real-time decryption and display:
```shell
tshark -o tls.keylog_file:ecapture_masterkey.log -Y http -T fields -e http.file_data -f "port 443" -i eth0
```
#### Text mode
```shell
sudo ecapture tls -m text
```
This outputs all plaintext data packets.
### GoTLS module
Similar to the OpenSSL module.
#### `gotls` command
Capture TLS plaintext data.
Step 1:
```shell
sudo ecapture gotls --elfpath=/home/cfc4n/go_https_client --hex
```
Step 2:
```shell
/home/cfc4n/go_https_client
```
#### More help
```shell
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](https://www.youtube.com/watch?v=CoDIjEQCvvA "eCapture User Manual")
* [eCapture: supports capturing plaintext of Go TLS/HTTPS traffic](https://medium.com/@cfc4ncs/ecapture-supports-capturing-plaintext-of-golang-tls-https-traffic-f16874048269)
## eCaptureQ GUI application
[eCaptureQ](https://github.com/gojue/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](https://github.com/gojue/ecapture/blob/master/EVENT_FORWARD.md)
### Video demonstration
https://github.com/user-attachments/assets/c8b7a84d-58eb-4fdb-9843-f775c97bdbfb
🔗 [GitHub repository](https://github.com/gojue/ecaptureq)
### Protobuf protocols
For details of the Protobuf log schema used by eCapture/eCaptureQ, see:
- [protobuf/PROTOCOLS.md](https://github.com/gojue/ecapture/blob/master/protobuf/PROTOCOLS.md)
## Star History
<a href="https://www.star-history.com/?repos=gojue%2Fecapture&type=date&legend=top-left">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/chart?repos=gojue/ecapture&type=date&theme=dark&legend=top-left" />
<source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/chart?repos=gojue/ecapture&type=date&legend=top-left" />
<img alt="Star History Chart" src="https://api.star-history.com/chart?repos=gojue/ecapture&type=date&legend=top-left" />
</picture>
</a>
# Security & operations
- [**Security policy**](https://github.com/gojue/ecapture/blob/master/SECURITY.md) — vulnerability reporting and supported versions
- [**Minimum privileges**](https://github.com/gojue/ecapture/blob/master/docs/minimum-privileges.md) — required Linux capabilities and least-privilege configuration
- [**Defense & detection**](https://github.com/gojue/ecapture/blob/master/docs/defense-detection.md) — how to detect and defend against unauthorized usage
- [**Performance benchmarks**](https://github.com/gojue/ecapture/blob/master/docs/performance-benchmarks.md) — repeatable overhead and event-loss measurements
- [**Release verification**](https://github.com/gojue/ecapture/blob/master/docs/release-verification.md) — how to verify the integrity of release artifacts
# Contributing
See [CONTRIBUTING](https://github.com/gojue/ecapture/blob/master/CONTRIBUTING.md) 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](https://github.com/gojue/ecapture/blob/master/docs/compilation.md) for detailed instructions.
Loong64 releases are cross-built on Ubuntu 24.04 x86_64 with LLVM 18. Use
`TARGET_ARCH=loong64`; the sysroot, BTF, verification steps, and current runtime
validation limits are documented in [Loong64 build and validation](https://github.com/gojue/ecapture/blob/master/docs/loong64-support.md).
## Remote configuration updates
After eCapture is running, you can dynamically modify configurations through HTTP interfaces. Refer to the [HTTP API documentation](https://github.com/gojue/ecapture/blob/master/docs/remote-config-update-api.md).
## 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](https://github.com/gojue/ecapture/blob/master/docs/event-forward-api.md).