eCapture 远程配置更新 API 实战指南通过 HTTP 动态调整 eBPF 探针运行参数【免费下载链接】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 的 SSL/TLS 明文捕获工具的远程配置更新 HTTP 接口展开从客户端视角讲解如何在 eCapture 进程不重启的前提下通过POST JSON动态修改 TLS、GoTLS、GnuTLS、NSS、Bash、MySQL、PostgreSQL 等探针模块的运行参数。读完本文你将掌握如何启用--listenHTTP 服务、如何构造各模块的请求体与解析统一响应、如何在 Linux 与 Android GKI 之间做平台兼容、以及如何设计可靠的错误处理与回滚策略。1. 功能定位与基本约定eCapture 的远程配置更新 API 是一组运行在内置 HTTP 服务上的管理接口用于在不重启 eCapture 进程的情况下调整探针的捕获行为。典型使用场景包括调整目标进程、端口、过滤规则等运行时参数避免重启造成的捕获空窗构建外部管理工具、控制面板或脚本按需下发并应用新配置在安全审计、数据库审计等场景中动态变更捕获范围。从源码看该 HTTP 服务由 cli/http/server.go 中的HttpServer实现它基于 Gin 框架并通过一个容量为 10 的 channelreRloadConfig与探针主循环通信一旦收到新配置探针会触发一次内部重启见 cli/cmd/root.go 中runProbe的reload逻辑。1.1 启用与禁用默认关闭eCapture 不会自动启动 HTTP 服务需要显式传参启用启用示例--listen 127.0.0.1:28256显式禁用--listen 此时运行期配置更新不可用。对应地在 cli/cmd/root.go 中init()注册了--listen全局参数默认值为空字符串runProbe中只有在globalConf.Listen ! 时才启动http.NewHttpServer。1.2 协议与请求规则项目约定协议HTTPHTTP 方法POSTContent-Typeapplication/json请求体目标模块的 JSON 配置对象结构与 eCapture 内部对应的config.*Config类型一致响应体统一的 JSON 结构包含状态码与模块名一个关键约定是端点路径没有公共前缀直接就是模块名例如/tls、/gotls、/gnutls。在 cli/http/server.go 的attachEndpoints()中可以看到全部端点注册代码未注册成功的探针因构建标签导致不可用会返回错误提示。2. 支持的 HTTP 路径与平台差异配置更新路径在 Linux 与 Android GKI 上略有不同原因是部分探针Bash、MySQL、PostgreSQL在 Android 上不支持。2.1 Linux 路径路径说明/tlsOpenSSL / TLS 模块/openssl/tls的别名/boringssl/tls的别名/gotlsGo TLS 模块/gnutlsGnuTLS 模块/nssNSS / NSPR 模块/nspr/nss的别名/bashBash 命令捕获仅 Linux/mysqldMySQLd 协议捕获仅 Linux/postgressPostgreSQL 协议捕获仅 Linux注意拼写为双s注意事项/openssl、/boringssl是/tls的别名三者共享同一套配置结构/nss与/nspr共享同一套配置结构/bash、/mysqld、/postgress在 Android GKI 上不存在。2.2 Android GKI 路径路径说明/tlsOpenSSL / TLS 模块/openssl/tls的别名/boringssl/tls的别名/gotlsGo TLS 模块/gnutlsGnuTLS 模块/nssNSS / NSPR 模块/nspr/nss的别名Android GKI不暴露/bash、/mysqld、/postgress三个配置端点如果你的管理客户端需要同时支持 Linux 与 Android请先检测平台只调用该平台支持的路径。从源码看平台差异是通过构建标签实现的Linux 构建使用 cli/http/config_factory_linux.go带!ecap_android标签Android 构建使用 cli/http/config_factory_ecandroid.go带ecap_android标签。后者对 GnuTLS、NSPR、MySQL、Postgres 的工厂函数直接返回not supported on Android错误。此外 cli/http/server.go 中同时注册了/postgres与/postgress两个路径二者都指向同一个Postgress处理函数。3. 请求与响应的统一格式3.1 请求格式所有配置更新端点使用相同的 HTTP 请求模式方法POSTURLhttp://listen-address/path例如http://127.0.0.1:28256/tls请求头Content-Type: application/json请求体JSON 对象字段取决于具体模块通常包含公共字段pid、uid、debug、hex、btf、per_cpu_map_size、truncate_size等模块特有字段目标进程名、端口、协议相关选项等。精确的字段名与类型定义在internal/probe/*/config.go以及公共的 internal/config/base_config.go中。下文示例仅用于演示客户端调用方式。服务端处理流程在 cli/http/server.go 的decodeConf中一目了然根据探针类型创建对应的domain.Configuration通过config_factory*.go的createXxxConfigc.ShouldBindJSON(conf)解析请求体失败返回code4conf.Validate()校验配置失败返回code5通过select向confChan发送配置channel 满即上次更新尚未完成时返回 HTTP 503 与code6。3.2 响应格式所有端点返回统一的 JSON 结构{ code: 0, module_type: openssl, msg: RespOK, data: null }字段说明codenumber状态码0– 成功RespOK4– 配置 JSON 解码失败RespConfigDecodeFailed5– 配置校验失败RespConfigCheckFailed6– 配置发送到内部 channel 失败RespSendToChanFailed其他值 – 预留如无效请求、内部服务器错误module_typestring本次更新对应的模块标识如openssl、gotls、gnutlsmsgstring与code对应的人类可读字符串便于日志与调试data当前未使用通常为null上述结构在 cli/http/resp.go 中定义Status枚举从RespOK(0)到RespSendToChanFailed(6)Resp结构体即响应的四个字段cli/http/status_string.go 则是由stringer生成的String()实现正是msg字段的来源。3.3 HTTP 状态与code的对应关系客户端视角HTTP 状态code含义客户端建议2000成功配置已接受并开始应用正常流程2004JSON 解码失败语法错误 / 类型不匹配修正请求体后重试2005配置校验失败缺少字段、非法值根据日志修正配置后重试2006内部更新通道已满 / 忙稍后重试2001 / 2无效请求 / 内部服务器错误记录并告警注意文档约定 HTTP 200 code0表示eCapture 已开始应用新配置通过内部重启模块HTTP 400 表示请求格式或配置内容非法code通常为 4 或 5HTTP 503 表示 eCapture 当前忙、无法接受新配置code为 6可稍后重试。4. 典型模块调用示例以下示例均假设 eCapture 运行在本机监听默认地址127.0.0.1:28256。JSON 字段仅为示例请以当前版本internal/probe/*/config.go中的实际字段为准。4.1 OpenSSL / TLS 模块/tls、/openssl、/boringssl适用于基于 OpenSSL / BoringSSL / 通用 TLS 的应用。三个路径等价任选其一即可。4.1.1 使用 curlcurl -v \ -H Content-Type: application/json \ -X POST \ --data { pid: 0, uid: 0, debug: false, hex: false, btf: 0, per_cpu_map_size: 1024, truncate_size: 0, filters: { target_process: [nginx, curl], ignore_process: [ecapture] } } \ http://127.0.0.1:28256/tls典型的成功响应{ code: 0, module_type: openssl, msg: RespOK, data: null }配置字段深度解读依据 internal/probe/openssl/config.go 与 internal/config/base_config.go所有模块共用的BaseConfig字段pid目标进程 PID0 表示所有进程uid目标用户 ID0 表示所有用户debug是否开启调试日志hex是否以十六进制输出JSON 字段名为is_hexbtfbtf_modeBTF 模式0自动检测、1core、2non-coreper_cpu_map_size每个 CPU 的 eBPF map 大小事件缓冲区默认8*1024*1024字节且校验必须为正数truncate_size文本模式下截断大小字节0 表示不截断byte_code_file_modebytecode 文件选择模式0all、1core、2non-corecgroup_path用于容器/进程过滤的 cgroup 路径perf_reorder/perf_reorder_lag_ms是否启用用户态 perf 缓冲区乱序重排及其滞后窗口毫秒0 时默认 10ms。OpenSSL 模块特有字段opensslpathlibssl.so的路径capturemode捕获模式text默认、keylog或pcapkeylog 模式必须提供keylogfilepcap 模式必须提供pcapfile与ifname且会校验网络接口存在且为 UP其余如sslversion、isboringssl、sslbpffile等为检测结果字段通常由服务端在Validate()阶段自动填充。4.1.2 使用 Gopackage main import ( bytes encoding/json log net/http ) type TlsConfig struct { Pid uint64 json:pid Uid uint64 json:uid Debug bool json:debug Hex bool json:hex Btf uint8 json:btf PerCpuMapSize int json:per_cpu_map_size TruncateSize uint64 json:truncate_size // 在此补充真实 TLS 配置字段以匹配 user/config/OpensslConfig当前版本为 internal/probe/openssl/config.go 中的 Config } type Resp struct { Code uint8 json:code ModuleType string json:module_type Msg string json:msg Data interface{} json:data } func main() { cfg : TlsConfig{ Pid: 0, Uid: 0, Debug: false, Hex: false, Btf: 0, PerCpuMapSize: 1024, TruncateSize: 0, } body, _ : json.Marshal(cfg) resp, err : http.Post( http://127.0.0.1:28256/tls, application/json, bytes.NewReader(body), ) if err ! nil { log.Fatalf(request failed: %v, err) } defer resp.Body.Close() var r Resp if err : json.NewDecoder(resp.Body).Decode(r); err ! nil { log.Fatalf(decode resp failed: %v, err) } log.Printf(status%d code%d module%s msg%s, resp.StatusCode, r.Code, r.ModuleType, r.Msg) }说明仓库中的配置类型已由文档早期提到的user/config/*.go迁移至 internal/probe 目录如 internal/probe/openssl/config.go、internal/probe/gotls/config.go客户端在定义镜像结构体时请以当前版本为准。此外文档中的filters.target_process / ignore_process字段为示例性字段实际 OpenSSL 配置的进程过滤能力请结合当前版本 internal/probe/openssl/config.go 确认。4.2 GoTLS 模块/gotls适用于使用 Go 标准 TLS 栈的 Go 应用仓库支持 Go 1.17 的 register ABI。curl -v \ -H Content-Type: application/json \ -X POST \ --data { pid: 0, uid: 0, debug: true, per_cpu_map_size: 2048 } \ http://127.0.0.1:28256/gotlsGoTLS 配置见 internal/probe/gotls/config.go在公共字段基础上还包含elf_path目标 Go 二进制 ELF 路径、capture_modetext/keylog/pcap、keylog_file、pcap_file、ifname、pcap_filter等字段。Validate()会解析目标 ELF读取 build info、提取 Go 版本Go 1.17 判定为 register ABI、定位crypto/tls关键函数如Write、master secret 函数的符号地址因此远程更新时若改动elf_path服务端会重新执行整条 ELF 解析链路。4.3 GnuTLS 模块/gnutls适用于依赖 GnuTLS 的应用LinuxAndroid 构建下不可用见 cli/http/config_factory_ecandroid.go。curl -v \ -H Content-Type: application/json \ -X POST \ --data { pid: 0, uid: 0, debug: false } \ http://127.0.0.1:28256/gnutls4.4 NSS / NSPR 模块/nss、/nspr适用于基于 NSS / NSPR 的组件如部分浏览器或系统组件。curl -v \ -H Content-Type: application/json \ -X POST \ --data { pid: 0, uid: 0, debug: false } \ http://127.0.0.1:28256/nss/nspr完全一致仅路径不同curl -v \ -H Content-Type: application/json \ -X POST \ --data { ... } \ http://127.0.0.1:28256/nspr两个路径在 cli/http/server.go 中均映射到hs.Nss最终以nspr类型创建配置。4.5 Bash 命令捕获模块仅 Linux/bashAndroid GKI 上不可用。若管理工具需跨平台请在调用前检测平台。curl -v \ -H Content-Type: application/json \ -X POST \ --data { pid: 0, uid: 0, debug: true } \ http://127.0.0.1:28256/bash4.6 MySQLd 模块仅 Linux/mysqldcurl -v \ -H Content-Type: application/json \ -X POST \ --data { pid: 0, uid: 0, debug: false } \ http://127.0.0.1:28256/mysqld4.7 PostgreSQL 模块仅 Linux/postgress注意路径拼写为/postgress双s。服务端同时注册了/postgres与/postgress两个路径均指向同一处理函数见 cli/http/server.go但文档约定的规范路径是/postgress。curl -v \ -H Content-Type: application/json \ -X POST \ --data { pid: 0, uid: 0, debug: false } \ http://127.0.0.1:28256/postgress5. 错误处理与重试策略5.1 状态码速查结合 HTTP 状态与 JSON 响应中的code字段即可定位问题HTTP 状态code含义客户端建议2000成功配置已接受并应用正常流程2004JSON 解码失败语法错误 / 类型不匹配修正请求体后重试2005配置校验失败缺少字段、非法值根据日志修正配置后重试2006内部更新通道已满 / 忙稍后重试2001 / 2无效请求 / 内部服务器错误记录并告警5.2 推荐的调用模式配置更新属于管理操作不应高频调用遇到 HTTP 503 且code 6时采用退避策略如指数退避稍后重试——该状态源于 cli/http/server.go 中向容量为 10 的 channel 发送失败select的default分支在调用方保存最近一次已知良好的配置副本若新配置导致异常行为可快速回滚——只需再次 POST 上一次的配置。从 cli/cmd/root.go 的runProbe可以看出应用链路收到新配置后探针先Stop、Close再以新配置goto reload重新factory.CreateProbe→Initialize→Start因此一次成功的更新会伴随一次模块级内部重启业务上应把该过程视为短暂重建而非无缝热切换。6. 平台兼容性Linux vs Android若工具只面向 Linux可使用上文 Linux 的全部路径若工具必须同时兼容 Linux 与 Android GKI通过 CLI 参数、环境变量或自有检测机制确定平台仅在 Linux 上调用/bash、/mysqld、/postgressAndroid 上不存在/tls、/gotls、/gnutls、/nss路径两个平台共用。源码层面平台差异由构建标签隔离cli/http/config_factory_linux.go!ecap_android提供全部模块的配置工厂cli/http/config_factory_ecandroid.goecap_android对 GnuTLS/NSPR/MySQL/Postgres 直接返回不支持错误。因此 Android 客户端即便请求/gnutls、/nss、/mysqld、/postgress服务端也会返回 400 RespConfigDecodeFailedcode4而非成功。7. 版本管理与字段对齐不同 eCapture 版本可能微调internal/probe/*/config.go中的配置结构推荐做法在客户端代码中定义与当前 eCapture 版本一致的镜像结构体字段名与类型完全对应或使用动态 JSON如map[string]any只填充确实需要的字段如需同时支持多个 eCapture 版本可自行构建兼容层如版本协商或功能开关。该思路与仓库中 ecaptureQ 客户端示例examples/ecaptureq_client/main.go所体现的客户端与服务端通过协议/版本配合的理念一致——ecaptureQ 客户端通过 WebSocket protobuf 接收事件而配置更新 API 则通过 HTTP JSON 下发两者共同构成 eCapture 的远程管理与事件消费能力。8. 变更记录版本日期说明0.1.02025-12-07远程配置 API 文档初始版本附录相关源码速查HTTP 服务与端点注册cli/http/server.go统一响应结构与状态码cli/http/resp.go、cli/http/status_string.go配置工厂Linux / Android 构建变体cli/http/config_factory.go、cli/http/config_factory_linux.go、cli/http/config_factory_ecandroid.go公共配置基类与校验规则internal/config/base_config.go各模块配置实现internal/probe/openssl/config.go、internal/probe/gotls/config.go、internal/probe/gnutls/config.go、internal/probe/nspr/config.go、internal/probe/bash/config.go、internal/probe/mysql/config.go、internal/probe/postgres/config.go探针主循环与 reload 逻辑cli/cmd/root.go配置接口定义internal/domain/configuration.go【免费下载链接】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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考