eCapture（旁观者）实战指南：基于 eBPF 的 SSL/TLS 明文捕获与安全审计工具

eCapture（旁观者）实战指南：基于 eBPF 的 SSL/TLS 明文捕获与安全审计工具

【免费下载链接】ecaptureCapturing SSL/TLS plaintext without a CA certificate using eBPF. Supported on Linux/Android kernels for amd64/arm64.项目地址: https://gitcode.com/GitHub_Trending/ec/ecapture

eCapture（旁观者）是一款基于 eBPF 技术的开源抓包工具，无需安装 CA 证书即可捕获 SSL/TLS 加密通讯的明文内容，同时内置 Bash/Zsh 命令审计、MySQL/PostgreSQL 数据库查询审计能力。本文以仓库 README.md 为主线，结合 CLI 命令实现、探针配置 与 eBPF 内核代码 等源码，系统讲解 eCapture 的安装方式、8 大功能模块、OpenSSL 的三种捕获模式、GoTLS 明文捕获方法以及命令行参数细节，帮助读者快速上手并理解其底层工作原理。

eCapture 是什么

eCapture 的中文名为旁观者，取「当局者迷，旁观者清」之意，与其"旁路、观察"的功能定位相契合。它使用 eBPF 的Uprobe（用户态探针）与Traffic Control（TC 流量控制）技术，实现各种用户空间/内核空间数据的捕获，无需改动原程序，也无需安装 CA 证书即可解密 TLS/SSL 流量。

核心能力一览（来自 README.md 的 Introduction 部分）：

• SSL/TLS 明文捕获：支持 openssl、libressl、boringssl、gnutls、nspr(nss) 类库；
• GoTLS 明文捕获：支持使用 Golang 内置 crypto/tls 库实现的 HTTPS/TLS 加密通讯；
• Bash 审计：捕获 bash 命令，用于主机安全审计；
• Zsh 审计：捕获 zsh 命令，用于主机安全审计；
• MySQL 审计：捕获 MySQL 查询 SQL，支持 mysqld 5.6/5.7/8.0 及 MariaDB；
• PostgreSQL 审计：支持 postgres 10+ 的查询语句捕获。

环境要求与适用平台

根据 README.md 顶部的重要说明，eCapture 的运行环境有明确约束：

• 支持平台：Linux / Android；
• CPU 架构与内核版本：x86_64 架构需要内核4.18+；aarch64 架构需要内核5.5+。内核版本要求按 CPU 架构区分，对 Linux 和 Android（GKI）同样适用；
• 权限要求：需要 ROOT 权限，或具备特定的 Linux capabilities；
• 不支持的平台：Windows、macOS。

从 root.go 的入口命令 可以看出，detectEnv()会在所有子命令执行前先校验运行环境，不满足条件时会直接报错退出。

快速上手：下载与安装

方式一：下载 ELF 可执行文件

从 release 页面下载对应平台的 ELF zip 压缩包（支持 Linux/Android 的 x86_64/aarch64），解压后直接执行：

sudo ecapture --help

方式二：Docker 镜像（仅限 Linux）

# 拉取镜像 docker pull gojue/ecapture:latest # 运行 docker run --rm --privileged=true --net=host -v ${HOST_PATH}:${CONTAINER_PATH} gojue/ecapture ARGS

⚠️ 安全提醒：--privileged=true会授予容器完整的宿主机访问权限。在生产环境中，建议使用特定的 capabilities 替代，详见最小权限指南。

小试身手：捕获 OpenSSL 加密的 HTTPS 明文

启动 eCapture 的 TLS 模块，自动检测系统的 OpenSSL 库并开始捕获：

sudo ecapture tls

当发起 HTTPS 请求（如curl https://google.com）时，捕获到的请求与响应会直接打印在终端。以下是 docs/example-outputs.md 中记录的完整输出片段：

... INF module started successfully. moduleName=EBPFProbeOPENSSL ??? UUID:233851_233851_curl_5_1_172.16.71.1:51837, Name:HTTP2Request, Type:2, Length:304 Frame Type => SETTINGS Frame Type => WINDOW_UPDATE Frame Type => HEADERS header field ":method" = "GET" header field ":path" = "/" header field ":scheme" = "https" header field ":authority" = "google.com" header field "user-agent" = "curl/7.81.0" header field "accept" = "*/*" ...

从输出中可以看到，eCapture 不仅还原了 HTTP/2 的伪头字段（:method、:path、:authority），还完整解析了HEADERS、SETTINGS、WINDOW_UPDATE等 HTTP/2 帧结构。更完整的输出示例请参阅 docs/example-outputs.md。

关于捕获原理：eCapture 通过uprobe挂钩 OpenSSL 的SSL_write/SSL_read等函数（具体挂钩函数集合定义在 openssl 探针 中），在明文数据写入 TLS 加密层前后将其拦截。kern/目录下的openssl_1_0_2a_kern.c、openssl_1_1_1a_kern.c、openssl_3_0_0_kern.c等文件，就是针对不同 OpenSSL 版本编译的 eBPF 内核程序。

8 大功能模块总览

eCapture 共包含 8 个模块，分别支持各类 TLS/SSL 加密类库的明文捕获与软件审计，可通过ecapture -h查看完整的子命令列表：

注意：在 Android 平台上，部分审计类模块（如 bash、mysqld）默认不启用，具体以 root.go 中的命令说明 为准。

OpenSSL 模块深度解析

动态库自动检测机制

eCapture 默认查找/etc/ld.so.conf文件，解析 SO 文件的加载目录，进而定位openssl等动态链接库的位置。也可以通过--libssl参数手动指定动态链接库路径。

从源码看，Linux 平台下的检测逻辑位于 internal/probe/openssl/config_linux.go：

• 若--libssl指定了路径，则直接校验该文件是否存在；
• 否则按顺序探测一系列常见路径（如/usr/lib/x86_64-linux-gnu/libssl.so.1.1、/usr/lib/x86_64-linux-gnu/libssl.so.3、/usr/lib64/libssl.so.3等）；
• 如果目标程序采用静态编译方式，则可以直接将--libssl参数设置为该程序本身的路径。

检测到库文件后，eCapture 会解析 ELF 文件，从.rodata段中通过正则匹配OpenSSL\s\d\.\d\.[0-9a-z]+提取版本号（见 config.go 的 detectOpenssl 函数），再据此匹配对应的 eBPF 字节码文件。若找不到完全匹配的版本，会执行版本降级匹配（如linux_default_3_0、linux_default_1_1_1），保证兼容性。

三种捕获模式

OpenSSL 模块支持 3 种捕获模式，通过-m/--model参数指定：

• pcap/pcapng模式：将捕获的明文数据以 pcap-NG 格式存储；
• keylog/key模式：保存 TLS 握手密钥到文件；
• text模式：直接捕获明文数据，输出到指定文件或打印到命令行。

各模式的默认值与校验逻辑见 openssl/config.go 的validateCaptureMode()：text 为默认模式；keylog 模式要求--keylogfile所在目录存在；pcap 模式要求--pcapfile与-i（网卡接口）同时有效，且接口必须处于 up 状态并已配置地址。

Pcap 模式

支持 TLS 加密的基于 TCP 的 http 1.0/1.1/2.0 应用层协议，以及基于 UDP 的 http3（QUIC）应用层协议。指定-m pcap或-m pcapng，配合--pcapfile、-i参数使用，--pcapfile默认值为ecapture_openssl.pcapng：

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

该命令将捕获的明文数据包保存为 pcapng 文件，之后可用 Wireshark 打开直接查看明文网络包。tcp port 443是 pcap 过滤器表达式，支持标准 BPF 过滤语法（如host 192.168.1.1 and tcp port 443），详见 tls.go 的命令示例。

Keylog 模式

指定-m keylog或-m key，配合--keylogfile参数使用，默认文件名为ecapture_masterkey.log。捕获到的 OpenSSL TLSMaster Secret信息会保存到该文件：

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

同时开启tcpdump抓包后，用 Wireshark 打开并设置Master Secret路径，即可查看明文数据包。也可以直接使用tshark软件实时解密展示：

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

Text 模式

sudo ecapture tls -m text

该模式输出所有明文数据包。（自 v0.7.0 起，text 模式不再捕获 SSLKEYLOG 信息。）

OpenSSL 模块的完整参数清单

从 cli/cmd/tls.go 中可以看到该模块支持的全部参数：

小提示：tls命令还支持别名openssl；在 pcap 模式下，命令行中剩余的未命名参数（如tcp port 443）会被拼接为 pcap 过滤表达式（见 tls.go 的 openSSLCommandFunc）。

GoTLS 模块：捕获 Go 程序的 HTTPS 明文

GoTLS 模块与 OpenSSL 模块类似，专门针对使用 Go 标准库crypto/tls编写的程序。因为 Go 程序通常将 TLS 逻辑静态编译进二进制，eCapture 通过解析 Go ELF 文件的符号表与gopclntab来定位crypto/tls关键函数的偏移地址（见 internal/probe/gotls/config.go）。

环境验证

先确认内核开启了 BTF（BTF 模式下捕获更稳定）：

uname -r # 4.18.0-305.3.1.el8.x86_64 cat /boot/config-`uname -r` | grep CONFIG_DEBUG_INFO_BTF # CONFIG_DEBUG_INFO_BTF=y

启动捕获

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

随后启动该程序（确保它会触发 HTTPS 请求）：

/home/cfc4n/go_https_client

更多帮助

sudo ecapture gotls -h

GoTLS 模块的核心参数（见 cli/cmd/gotls.go）：

从源码看，GoTLS 探针会自动检测 Go 版本与 ABI 类型（Go 1.17+ 使用寄存器 ABI），并区分 PIE 与非 PIE 构建模式来计算函数偏移地址（见 gotls/config.go 的 parserGoElf）。它还会校验目标二进制架构与当前运行环境一致（amd64/arm64）。

其他模块速览

• bash 模块：捕获 bash 命令，自动从$SHELL环境变量或/bin/bash探测目标，并通过 ELF 动态符号表选择挂钩readline或readline_internal_teardown函数（见 internal/probe/bash/config.go）。支持参数：--bash（bash 路径）、--readlineso（readline.so 路径）、-e/--errnumber（只显示执行结果为指定退出码的命令，默认 128）。
• zsh 模块：捕获 zsh 命令，对应内核程序为 kern/zsh_kern.c。
• gnutls 模块：捕获 gnutls 类库加密通讯的明文，kern/目录下有针对 gnutls 3.6.12、3.6.13、3.7.0、3.7.3、3.7.7、3.8.4、3.8.7 等多个版本的 eBPF 程序。
• nss 模块：捕获 nss/nspr 类库加密通讯的明文，对应 kern/nspr_kern.c。
• mysqld 模块：捕获 mysqld 的 SQL 查询，支持 5.6/5.7/8.0 及 MariaDB，对应 kern/mysqld_kern.c。
• postgres 模块：支持 postgres 10+ 的查询捕获，对应 kern/postgres_kern.c。

以上模块均可通过ecapture -h查看详细帮助文档。

全局命令行参数

所有子命令共享的全局参数定义在 cli/cmd/root.go，适用于各类审计与捕获场景：

例如，只审计指定进程并开启十六进制输出：

sudo ecapture tls -l save.log --pid=3423 --hex

安全与运维

eCapture 提供了完整的运维配套文档，建议在生产环境中按需阅读：

• 安全策略—— 漏洞报告流程与受支持的版本；
• 最小权限指南—— 所需的 Linux capabilities 与最小权限配置（避免直接使用 root 或--privileged=true）；
• 防御与检测—— 如何检测和防御未经授权的 eCapture 使用；
• 性能基准测试—— 性能开销测量方法与预期特征；
• 发布验证—— 如何验证发布产物的完整性。

扩展能力：远程配置、事件转发与 eCaptureQ

运行时动态修改配置

eCapture 运行后，可通过 HTTP 接口动态修改配置（使用--listen开启）。详见 HTTP API 文档。从 root.go 的实现 可以看到，收到 HTTP 配置更新请求后，探针会收到重载信号，通过probe.Initialize → probe.Start流程自动重启并应用新配置。

事件转发

eCapture 支持多种事件转发方式，可将捕获事件转发至 Burp Suite 等抓包分析软件。详见 事件转发 API 文档。

eCaptureQ 图形界面客户端

eCaptureQ 是 eCapture 的跨平台图形界面客户端，将 eBPF TLS 抓包能力可视化呈现。它采用 Rust + Tauri + React 技术栈构建，提供实时响应式界面，支持两种模式：

• 集成模式：Linux/Android 一体化运行；
• 远程模式：Windows/macOS/Linux 客户端连接远程 eCapture 服务。

关于 eCapture/eCaptureQ 使用的 Protobuf 日志模式细节，参见 protobuf/PROTOCOLS.md，对应的 eCaptureQ 客户端实现位于 pkg/ecaptureq。

编译与二次开发

自行编译

可以定制所需功能，例如为 uprobe 设置偏移地址以支持静态编译的 OpenSSL 库。编译方法参考 编译指南。

定制 eBPF 字节码

kern/目录存放了所有模块的 eBPF 内核源码（如openssl_3_0_0_kern.c、gotls_kern.c、mysqld_kern.c），bytecode/目录存放编译产物。新增 OpenSSL 版本支持时，需要补充对应的内核程序与版本映射表（sslVersionBpfMap，定义于 openssl 配置）。对于结构内部偏移的变化，仓库还提供了多种offset生成脚本（见utils/目录下的openssl_offset_*.sh与gnutls_offset.sh）。

参考文档索引

• 完整输出示例：各模块、各模式的真实运行输出；
• 最小权限指南：capabilities 与 Docker 权限配置；
• 防御与检测：蓝队视角的检测与防御方法；
• 性能基准测试：开销测量方法；
• 发布验证：产物完整性校验；
• 编译指南：自定义编译；
• 远程配置更新 API：HTTP 动态改配置；
• 事件转发 API：事件转发至 Burp 等工具。

【免费下载链接】ecaptureCapturing SSL/TLS plaintext without a CA certificate using eBPF. Supported on Linux/Android kernels for amd64/arm64.项目地址: https://gitcode.com/GitHub_Trending/ec/ecapture