捕获模块 ​

概述 ​

eCapture 实现了八个捕获模块，为不同的协议、库和应用程序提供专门的数据拦截能力。每个模块使用 eBPF uprobe 来钩住特定函数，在加密前或解密后捕获明文数据。这些模块通过 Cobra 注册为 CLI 子命令，并通过模块注册表模式实例化。

模块分类：

可用命令：

ecapture tls      # OpenSSL/BoringSSL TLS/SSL 捕获
ecapture gotls    # Go TLS 捕获
ecapture gnutls   # GnuTLS 捕获
ecapture nspr     # NSPR/NSS 捕获
ecapture bash     # Bash 命令审计
ecapture zsh      # Zsh 命令审计
ecapture mysqld   # MySQL 查询审计
ecapture postgres # PostgreSQL 查询审计

所有模块都实现了 IModule 接口，并通过 Module 基础结构体共享通用功能。详细实现信息请参见：

• TLS/SSL 模块：参见 [3.1 - TLS/SSL 捕获模块]
• 系统审计模块：参见 [3.2 - 系统审计模块]
• 网络数据包捕获：参见 [3.3 - 基于 TC 的网络数据包捕获]
• 模块架构：参见 [2.5 - 模块系统与生命周期]
• 事件处理：参见 [2.2 - 事件处理流程]

来源：README.md:152-161, cli/cmd/tls.go:29-48, cli/cmd/gotls.go:29-40, cli/cmd/bash.go:27-33, cli/cmd/mysqld.go:30-36

模块注册架构 ​

CLI 命令注册流程

每个模块遵循一致的注册模式：

1. 命令定义：每个 cli/cmd/*.go 文件定义一个 cobra.Command 结构体，包含 Use、Aliases、Short、Long 和 RunE 字段
2. 配置对象：通过 config.New*Config() 构造函数创建包级别变量（例如 oc、goc）
3. 命令函数：RunE 处理函数（例如 openSSLCommandFunc）处理 CLI 标志并调用 runModule()
4. 模块常量：字符串常量（如 module.ModuleNameOpenssl）标识模块实现
5. 注册：init() 函数将命令添加到 rootCmd 并将标志绑定到配置对象

来源：cli/cmd/tls.go:26-67, cli/cmd/gotls.go:26-58, cli/cmd/bash.go:24-55, cli/cmd/mysqld.go:27-49, cli/cmd/postgres.go:27-45, cli/cmd/nspr.go:27-51, cli/cmd/gnutls.go:29-64, cli/cmd/zsh.go:27-57

模块类别与能力 ​

eCapture 的八个模块被组织为三个功能类别：

TLS/SSL 加密库 ​

五个模块拦截加密库函数以在加密前或解密后捕获明文：

捕获模式：TLS/SSL 模块通过 -m 标志支持三种模式：

• text：直接明文输出，支持 HTTP/1.x/HTTP2 解析
• pcap/pcapng：网络数据包，在 PCAPNG DSB 中嵌入 TLS 密钥
• keylog/key：以 SSLKEYLOGFILE 格式提取主密钥

来源：cli/cmd/tls.go:32-33, cli/cmd/gotls.go:32-33, cli/cmd/gnutls.go:35-36, cli/cmd/nspr.go:32-33, README.md:163-176

系统审计模块 ​

四个模块钩住命令解释器和数据库服务器：

过滤：Bash 和 Zsh 支持 -e/--errnumber 标志以按命令退出状态过滤。

来源：cli/cmd/bash.go:28-32, cli/cmd/zsh.go:31-35, cli/cmd/mysqld.go:31-36, cli/cmd/postgres.go:31-33

网络数据包捕获 ​

TLS/SSL 模块在使用 pcap 模式时与 Traffic Control (TC) eBPF 分类器集成：

• TC 探针：通过 -i/--ifname 标志附加到网络接口
• BPF 过滤：支持 pcap 过滤表达式（例如 tcp port 443）
• 连接跟踪：使用 kprobe 在 tcp_sendmsg/udp_sendmsg 上进行 PID/UID 映射
• 协议支持：IPv4/IPv6、TCP/UDP、ICMP

详情请参见 [3.3 - 基于 TC 的网络数据包捕获]。

来源：cli/cmd/tls.go:56, cli/cmd/gotls.go:47, CHANGELOG.md:153

模块钩子点与目标 ​

模块目标函数与捕获的数据

IModule 接口方法

user/module/ 中的所有模块实现必须实现以下方法：

Module 基础结构体提供 eBPF 映射管理、事件读取和配置处理的共享功能。详细实现请参见 [2.5 - 模块系统与生命周期]。

来源：cli/cmd/tls.go:29-48, cli/cmd/gotls.go:29-40, cli/cmd/bash.go:27-33, cli/cmd/mysqld.go:30-36

模块概述 ​

TLS/SSL 捕获模块 ​

eCapture 提供五个模块用于捕获来自不同加密库的加密 TLS/SSL 流量。所有 TLS/SSL 模块支持三种捕获模式（-m text|pcap|keylog），并可以提取主密钥用于离线解密。详细信息请参见 [3.1 - TLS/SSL 捕获模块]。

OpenSSL/BoringSSL 模块（tls、openssl）

捕获使用 OpenSSL（1.0.2-3.5.x）或 BoringSSL（Android 12-16）的应用程序的 TLS/SSL 流量。自动检测库版本并选择适当的 eBPF 字节码。钩住 SSL_read()、SSL_write()、SSL_do_handshake() 和主密钥提取函数。参见 [3.1.1 - OpenSSL 模块]。

ecapture tls -m pcap -i eth0 -w capture.pcapng tcp port 443

Go TLS 模块（gotls、tlsgo）

捕获使用 crypto/tls 标准库的 Go 程序的 TLS 流量。需要 --elfpath 标志指向 Go 二进制文件。解析 ELF .gopclntab 段以定位函数偏移，支持基于寄存器（Go ≥1.17）和基于栈（Go <1.17）的 ABI。参见 [3.1.3 - Go TLS 模块]。

ecapture gotls --elfpath=/usr/bin/myapp -m keylog -k keys.log

GnuTLS 模块（gnutls、gnu）

捕获使用 libgnutls.so 的应用程序（例如 wget、curl）的流量。支持 TLS 1.3 早期密钥提取用于 0-RTT 数据。钩住 gnutls_record_recv()、gnutls_record_send() 和 gnutls_handshake()。参见 [3.1.4 - GnuTLS 与 NSS 模块]。

ecapture gnutls -m keylog -k gnutls_keys.log --gnutls=/lib/x86_64-linux-gnu/libgnutls.so

NSPR/NSS 模块（nspr、nss）

捕获使用 libnspr4.so/libnss3.so 的 Mozilla 应用程序（Firefox、Thunderbird）的流量。钩住 NSPR I/O 层的 PR_Read() 和 PR_Write()。当前仅支持文本模式。参见 [3.1.4 - GnuTLS 与 NSS 模块]。

ecapture nspr --nspr=/lib/x86_64-linux-gnu/libnspr4.so

来源：cli/cmd/tls.go:29-67, cli/cmd/gotls.go:29-58, cli/cmd/gnutls.go:32-64, cli/cmd/nspr.go:30-51

系统审计模块 ​

eCapture 提供四个模块用于审计系统命令和数据库查询。这些模块捕获命令行输入和 SQL 查询以用于安全审计目的。详细信息请参见 [3.2 - 系统审计模块]。

Bash 模块（bash）

通过钩住 libreadline.so 的 readline() 审计 Bash shell 中输入的命令。捕获命令文本、退出状态和 errno。支持使用 -e 标志按退出代码过滤。参见 [3.2.1 - Shell 命令审计]。

ecapture bash --errnumber=0  # 仅显示成功的命令

Zsh 模块（zsh）

通过钩住 Zsh 行编辑器的 zle_line_finish() 审计 Zsh 命令。类似于 Bash 模块，但针对 Zsh 特定函数。仅限 Linux。参见 [3.2.1 - Shell 命令审计]。

ecapture zsh --zsh=/bin/zsh

MySQL 模块（mysqld）

通过钩住 dispatch_command() 函数审计 MySQL/MariaDB 查询。支持 MySQL 5.6/5.7/8.0 和 MariaDB 10.5+。捕获 SQL 查询文本和连接元数据。参见 [3.2.2 - 数据库查询审计]。

ecapture mysqld --mysqld=/usr/sbin/mysqld --funcname=dispatch_command

PostgreSQL 模块（postgres）

通过钩住 exec_simple_query() 审计 PostgreSQL 查询。支持 PostgreSQL 10 及更新版本。捕获 SQL 语句和连接信息。参见 [3.2.2 - 数据库查询审计]。

ecapture postgres --postgres=/usr/bin/postgres

来源：cli/cmd/bash.go:27-55, cli/cmd/zsh.go:30-57, cli/cmd/mysqld.go:30-49, cli/cmd/postgres.go:30-45

通用配置参数 ​

所有模块都接受在 BaseConfig 中定义的这些共享标志：

TLS/SSL 模块特定标志：

系统审计模块特定标志：

来源：cli/cmd/tls.go:50-58, cli/cmd/gotls.go:42-48, cli/cmd/bash.go:36-38, cli/cmd/mysqld.go:40-42

TLS/SSL 模块输出模式 ​

TLS/SSL 模块（tls、gotls、gnutls）通过 -m/--model 标志支持三种输出模式：

文本模式（-m text） ​

默认模式。直接将明文数据捕获并显示到控制台或文件。

特性：

• HTTP/1.x 请求/响应解析（带标头）
• HTTP/2 帧解析（带 HPACK 标头解压缩）
• 自动 gzip 解压缩（Content-Encoding: gzip）
• 彩色输出（请求为绿色，响应为蓝色）
• 基于 UUID 的连接跟踪

输出目标：stdout 或由 -l 标志指定的文件。

PCAP 模式（-m pcap） ​

捕获网络数据包并以 PCAPNG 格式保存，其中嵌入 TLS 密钥。

特性：

• 需要 -i/--ifname 指定网络接口
• 在解密密钥块（DSB）中嵌入 TLS 主密钥
• 支持可选的 BPF 过滤表达式（例如 tcp port 443）
• 兼容 Wireshark 直接解密
• IPv4/IPv6 支持

输出：由 -w/--pcapfile 标志指定的文件。

示例：

ecapture tls -m pcap -i eth0 -w capture.pcapng host 192.168.1.100 and tcp port 443

Keylog 模式（-m keylog） ​

仅提取 TLS 主密钥，不捕获数据有效负载。

特性：

• 以与 Wireshark/tshark 兼容的 SSLKEYLOGFILE 格式保存密钥
• TLS 1.2：带主密钥的 CLIENT_RANDOM
• TLS 1.3：多个密钥（早期、握手、流量）
• 可与 tcpdump 结合用于离线解密

输出：由 -k/--keylogfile 标志指定的文件。

示例：

# 终端 1：捕获密钥
ecapture tls -m keylog -k keys.log

# 终端 2：使用 tshark 解密
tshark -o tls.keylog_file:keys.log -Y http -T fields -e http.file_data -i eth0

来源：cli/cmd/tls.go:53-56, README.md:171-247, CHANGELOG.md:687-743

模块生命周期与执行流程 ​

模块调用序列图

执行步骤：

1. 入口点：main.main() 调用 cli.Start() → main.go:9-11
2. 命令路由：Cobra 框架执行匹配子命令的 RunE 函数
3. 配置准备：命令函数解析标志，创建配置对象（例如 OpensslConfig）
4. 模块查找：runModule() 从注册表中检索模块工厂函数
5. 模块构造：工厂创建模块实例（例如 MOpenSSLProbe）
6. 初始化：Init() 方法检测目标二进制文件，选择 eBPF 字节码
7. 探针附加：Start() 加载 eBPF 程序并附加到钩子点
8. 事件循环：Run() 处理事件直到收到信号
9. 清理：Close() 分离探针并释放资源

来源：main.go:1-11, cli/cmd/tls.go:62-67, cli/cmd/gotls.go:52-58

平台特定模块可用性 ​

模块使用 Go 构建标签控制平台编译：

构建标签：//go:build !androidgki

五个模块从 Android GKI（通用内核映像）构建中排除：

通用模块（Linux + Android）：

• OpenSSL/BoringSSL（tls）：在 Linux 上支持 OpenSSL，在 Android 上支持 BoringSSL
• Go TLS（gotls）：Go 二进制文件在两个平台上运行
• Bash（bash）：在 Linux 和 Android（通过 Termux）上均可用

平台检测：构建系统根据编译期间指定的目标平台自动选择适当的模块。

来源：cli/cmd/gnutls.go:1-2, cli/cmd/nspr.go:1-2, cli/cmd/mysqld.go:1-2, cli/cmd/postgres.go:1-2, cli/cmd/zsh.go:1-2

何时使用各模块 ​

模块选择指南

输出模式选择（TLS 模块）

来源：README.md:152-161, README.md:163-247, cli/cmd/tls.go:32-46

模块版本支持 ​

TLS/SSL 库版本

数据库版本

大多数模块的版本检测和字节码选择是自动的。实现详情请参见 [2.6 - 版本检测与字节码选择]。

来源：CHANGELOG.md:14-108, cli/cmd/tls.go:39-40, cli/cmd/mysqld.go:33-35