eCapture(旁观者)

Appearance

Return to top
On this page

TLS Troubleshooting ​

Relevant source files

The following files were used as context for generating this wiki page:

Purpose and Scope ​

This wiki page provides a comprehensive diagnostic checklist for troubleshooting issues encountered while using eCapture's core TLS modules (tls for OpenSSL/BoringSSL, gotls for Go native TLS, and gnutls for GnuTLS) across all three operating modes (text, keylog, and pcapng). It covers common failure domains including kernel requirements, BPF/BTF support, privilege levels, library/binary mismatches, symbol resolution, interface configuration, and event destination errors.

1. Kernel Version, BTF, and Privileges Errors ​

eCapture relies heavily on modern eBPF features, uprobes, and kernel BTF (BPF Type Format) metadata. Startup failures in this domain usually manifest during environment detection cli/cmd/env_detection.go:74-86.

Common Symptoms & Diagnostics ​

  • Kernel Version Mismatch:
    • Error message: the Linux/Android kernel version ... is not supported; require ... or newer cli/cmd/env_detection.go:36-38.
    • Cause: Host kernel is older than the architecture minimum (x86_64 requires Linux 4.18+, aarch64 requires Linux 5.5+, and LoongArch64 requires Linux 6.6+) cli/cmd/env_detection.go:43-54.
    • Solution: Upgrade the host kernel or run on a supported platform.
  • Missing BPF Privileges:
  • BTF / Kernel Config Errors:
    • Cause: Neither /sys/kernel/btf/vmlinux nor fallback ELF vmlinux files are accessible, and CONFIG_DEBUG_INFO_BTF is disabled pkg/util/ebpf/bpf.go:89-98 pkg/util/ebpf/bpf.go:118-143.
    • Solution: Ensure your kernel is compiled with BTF support (CONFIG_DEBUG_INFO_BTF=y) or install kernel debug packages providing vmlinux.
Title: "Environment and Privilege Diagnostic Flow"

graph TD
    Start["Start eCapture CLI"] --> CheckKernel["detectKernel() cli/cmd/env_detection.go"]
    CheckKernel -->|Kernel < Min| ErrKernel["Error: Kernel version unsupported"]
    CheckKernel -->|Kernel >= Min| CheckCap["detectBpfCap() cli/cmd/env_detection.go"]
    CheckCap -->|No CAP_BPF / CAP_SYS_ADMIN| ErrCap["Error: Insufficient privileges"]
    CheckCap -->|Privileges OK| CheckBTF["IsEnableBTF() pkg/util/ebpf/bpf.go"]
    CheckBTF -->|No BTF / vmlinux| FallbackNonCore["Fallback to non-CORE bytecode"]
    CheckBTF -->|BTF Enabled| LoadCore["Load CORE eBPF Bytecode"]

Sources: cli/cmd/env_detection.go:26-86, pkg/util/ebpf/bpf.go:89-143, docs/minimum-privileges.md:120-135

2. Library, Binary, and Symbol Resolution Mismatches ​

When eCapture fails to attach uprobes to target binaries or shared libraries, events will not be captured.

Common Symptoms & Diagnostics ​

  • Missing Shared Library:
    • Cause: The target OpenSSL (libssl.so) or GnuTLS library path cannot be located automatically, or the custom path supplied via --libssl does not exist.
    • Solution: Specify the absolute path to the shared library using --libssl or ensure the application is dynamically linked against a supported library version.
  • Symbol Stripping in Go Binaries (gotls):
    • Cause: The target Go binary was compiled with stripped symbol tables (-ldflags="-s"), preventing eCapture from locating internal Go TLS functions and crypto primitive offsets.
    • Solution: Recompile or inspect the Go binary without symbol stripping, or use Go module introspection flags to match function offsets.
  • Version Mismatch:
    • Cause: Bytecode assets compiled for OpenSSL 1.1.x are loaded against an OpenSSL 3.x runtime environment (or vice-versa).
    • Solution: Ensure eCapture automatically matches or explicitly selects the correct bytecode file corresponding to the target library major/minor version (e.g., openssl_3_0_0_kern_core.o) docs/example-outputs.md:38.

3. Empty Events and Missing Secrets ​

If eCapture starts successfully but produces no plaintext events or decryption keys:

Checklist ​

  1. Traffic Generation: Ensure active HTTPS/TLS traffic is flowing through the targeted process. Idle applications generate no uprobe hits.
  2. Process Targeting (--pid): If scoping capture to a specific process ID, verify that the PID is correct and that the process is actively initiating new TLS handshakes (existing established connections before eCapture startup will not be decrypted until renegotiated or restarted).
  3. Cipher Suite Support:
  • In pcapng or keylog mode, ensure the cipher suites in use are supported by eCapture's key extraction logic (e.g., non-TLS 1.3 or specific TLS 1.3 key schedule hooks). Unsupported custom crypto libraries or hardware-offloaded cryptographic engines cannot be intercepted via software uprobes.

4. Incomplete Pcapng & Interface / Traffic Control Errors ​

When running in pcapng mode (-m pcap or -m pcapng), network packet capture relies on Traffic Control (TC) attachment or network interface packet sniffing.

Common Symptoms & Diagnostics ​

  • Missing CAP_NET_ADMIN:
  • Invalid Interface Name:
    • Error message: Interface not found or unable to attach TC classifier.
    • Solution: Verify available network interfaces using ip link and pass the correct interface identifier to -i.
  • Missing Secrets Block in Wireshark:
    • Cause: Packets are captured from the network interface, but TLS handshake key extraction failed due to a symbol mismatch in libssl, resulting in a pcapng file containing raw encrypted packets without a TLS Decryption Secrets Block (DSB).
    • Solution: Confirm that console logs report successful key logger initialization (e.g., master key keylogger has been set) docs/example-outputs.md:30 and CLIENT_RANDOM save success docs/example-outputs.md:133.

5. Destination and Sinks Errors ​

Operational logs and captured events are routed via distinct configuration parameters.

Destination Rules & Troubleshooting ​

  • --eventaddr vs --logaddr:
    • --eventaddr carries captured payload events (plaintext, key logs, or pcapng byte streams) to stdout, file, TCP, or WebSocket sinks.
    • --logaddr carries operational diagnostic logs only. Do not mix up the two endpoints.
  • File Permission and Disk Space Errors:
    • Cause: Writing capture artifacts (-w output.pcapng or file-based --eventaddr) fails due to insufficient permissions or disk exhaustion.
    • Solution: Verify write permissions on the target directory and monitor available disk space, especially during high-throughput pcapng capture sessions.
Title: "Output Pipeline and Destination Error Handling"

graph TD
    EventGen["Core TLS Probe Event Generation"] --> Decoder["Event Decoder Pipeline"]
    Decoder --> SinkRoute{Select Destination Mode}
    SinkRoute -->|Stdout / Default| StdoutSink["Print to Terminal (Check FD permissions)"]
    SinkRoute -->|File Output -w / --eventaddr| FileSink["Write Artifact (Check disk space & write perms)"]
    SinkRoute -->|Network Sink TCP/WS| NetSink["Forward to --eventaddr endpoint (Check port & network)"]
    OpsLogs["Operational Logs"] --> LogAddr["--logaddr Diagnostic Sink"]

Sources: docs/example-outputs.md:23-25, docs/README.md:27-30

Sources: cli/cmd/env_detection.go:26-86, pkg/util/ebpf/bpf.go:89-143, docs/minimum-privileges.md:13-58, docs/example-outputs.md:23-38

TLS 故障排查 ​

目的与范围 ​

本页为用户和运维人员提供使用 eCapture 核心 TLS 模块（tls 对应 OpenSSL/BoringSSL、gotls 对应 Go 原生 TLS、gnutls 对应 GnuTLS）以及三种工作模式（text、keylog、pcapng）时的综合故障排查清单。涵盖内核要求、BPF/BTF 支持、权限级别、库与二进制不匹配、符号解析、网卡配置及事件目标错误。

1. 内核版本、BTF 与权限错误 ​

eCapture 严重依赖现代 eBPF 特性、uprobe 以及内核 BTF（BPF 类型格式）元数据。此领域的启动失败通常出现在环境检测阶段 cli/cmd/env_detection.go:74-86。

常见症状与诊断 ​

  • 内核版本不匹配：
    • 错误信息：the Linux/Android kernel version ... is not supported; require ... or newer cli/cmd/env_detection.go:36-38。
    • 原因：宿主机内核版本低于架构最低要求（x86_64 要求 Linux 4.18+，aarch64 要求 Linux 5.5+，LoongArch64 要求 Linux 6.6+）cli/cmd/env_detection.go:43-54。
    • 解决方法：升级宿主机内核或在受支持的平台上运行。
  • 缺少 BPF 权限：
  • BTF / 内核配置错误：
    • 原因：无法访问 /sys/kernel/btf/vmlinux 或备用 ELF vmlinux 文件，且 CONFIG_DEBUG_INFO_BTF 被禁用 pkg/util/ebpf/bpf.go:89-98 pkg/util/ebpf/bpf.go:118-143。
    • 解决方法：确保内核编译时启用了 BTF 支持（CONFIG_DEBUG_INFO_BTF=y）或安装提供 vmlinux 的内核调试包。
Title: "环境与权限诊断流程"

graph TD
    Start["启动 eCapture CLI"] --> CheckKernel["detectKernel() cli/cmd/env_detection.go"]
    CheckKernel -->|内核低于最低版本| ErrKernel["错误：内核版本不支持"]
    CheckKernel -->|内核符合要求| CheckCap["detectBpfCap() cli/cmd/env_detection.go"]
    CheckCap -->|缺少 CAP_BPF / CAP_SYS_ADMIN| ErrCap["错误：权限不足"]
    CheckCap -->|权限正常| CheckBTF["IsEnableBTF() pkg/util/ebpf/bpf.go"]
    CheckBTF -->|无 BTF / vmlinux| FallbackNonCore["回退至非 CORE 字节码"]
    CheckBTF -->|BTF 已启用| LoadCore["加载 CORE eBPF 字节码"]

Sources: cli/cmd/env_detection.go:26-86, pkg/util/ebpf/bpf.go:89-143, docs/minimum-privileges.md:120-135

2. 库、二进制与符号解析不匹配 ​

当 eCapture 无法将 uprobe 附加到目标二进制文件或共享库时，将无法捕获任何事件。

常见症状与诊断 ​

  • 缺少共享库：
    • 原因：无法自动定位目标 OpenSSL（libssl.so）或 GnuTLS 库路径，或通过 --libssl 传入的自定义路径不存在。
    • 解决方法：使用 --libssl 指定共享库的绝对路径，或确保应用程序动态链接了受支持的库版本。
  • Go 二进制文件符号被剥离 (gotls)：
    • 原因：目标 Go 二进制文件在编译时带有符号剥离参数（-ldflags="-s"），导致 eCapture 无法定位内部 Go TLS 函数和密码学原语偏移量。
    • 解决方法：重新编译或检查未剥离符号的 Go 二进制文件，或者使用 Go 模块内省标志来匹配函数偏移量。
  • 版本不匹配：
    • 原因：为 OpenSSL 1.1.x 编译的字节码资产被加载到了 OpenSSL 3.x 运行时环境中（反之亦然）。
    • 解决方法：确保 eCapture 自动匹配或显式选择与目标库主/次版本相对应的正确字节码文件（例如 openssl_3_0_0_kern_core.o）docs/example-outputs.md:38。

3. 空事件与缺失密钥 ​

如果 eCapture 启动成功，但未产生明文事件或解密密钥：

排查清单 ​

  1. 流量生成：确保有活跃的 HTTPS/TLS 流量流经目标进程。处于空闲状态的应用程序不会触发 uprobe。
  2. 进程过滤 (--pid)：如果将捕获范围限定为特定进程 ID，请验证 PID 是否正确，并且该进程是否正在积极发起新的 TLS 握手（eCapture 启动前已经建立的存量连接在重新协商或重启之前无法被解密）。
  3. 密码套件支持：
  • 在 pcapng 或 keylog 模式下，确保所使用的密码套件受 eCapture 密钥提取逻辑支持（例如非 TLS 1.3 或特定的 TLS 1.3 密钥调度钩子）。无法通过软件 uprobe 拦截不受支持的自定义加密库或硬件卸载加密引擎。

4. 不完整的 Pcapng 与网卡 / 流量控制错误 ​

在 pcapng 模式下运行（-m pcap 或 -m pcapng）时，网络抓包依赖于流量控制（TC）附加或网络接口数据包嗅探。

常见症状与诊断 ​

  • 缺少 CAP_NET_ADMIN：
  • 无效的网卡名称：
    • 错误信息：找不到网卡或无法附加 TC 分类器。
    • 解决方法：使用 ip link 检查可用的网络接口，并向 -i 传递正确的网卡标识符。
  • Wireshark 中缺少密钥块 (DSB)：
    • 原因：数据包已从网卡捕获，但由于 libssl 中的符号不匹配，导致 TLS 握手密钥提取失败，生成的 pcapng 文件仅包含原始加密数据包，而没有 TLS 解密密钥块（DSB）。
    • 解决方法：确认控制台日志报告密钥记录器初始化成功（例如 master key keylogger has been set）docs/example-outputs.md:30 且输出 CLIENT_RANDOM save success docs/example-outputs.md:133。

5. 目标地址与接收端错误 ​

操作日志和捕获的事件通过不同的配置参数进行路由。

目标规则与故障排查 ​

  • --eventaddr 与 --logaddr 的区别：
    • --eventaddr 将捕获的载荷事件（明文、密钥日志或 pcapng 字节流）传输到标准输出、文件、TCP 或 WebSocket 接收端。
    • --logaddr 仅传输操作诊断日志。切勿混淆这两个端点。
  • 文件权限与磁盘空间错误：
    • 原因：由于权限不足或磁盘写满，导致写入捕获产物（-w output.pcapng 或基于文件的 --eventaddr）失败。
    • 解决方法：验证目标目录的写权限，并监控可用磁盘空间，特别是在高吞吐量的 pcapng 捕获会话期间。
Title: "输出管道与目标错误处理"

graph TD
    EventGen["核心 TLS 探针事件生成"] --> Decoder["事件解码管道"]
    Decoder --> SinkRoute{选择目标模式}
    SinkRoute -->|Stdout / 默认| StdoutSink["打印到终端（检查文件描述符权限）"]
    SinkRoute -->|文件输出 -w / --eventaddr| FileSink["写入产物（检查磁盘空间与写权限）"]
    SinkRoute -->|网络接收端 TCP/WS| NetSink["转发至 --eventaddr 端点（检查端口与网络）"]
    OpsLogs --> LogAddr["--logaddr 诊断日志接收端"]

Sources: docs/example-outputs.md:23-25, docs/README.md:27-30

Sources: cli/cmd/env_detection.go:26-86, pkg/util/ebpf/bpf.go:89-143, docs/minimum-privileges.md:13-58, docs/example-outputs.md:23-38

Edit this page on GitHub

Download