eCapture Event Forwarding API 实战指南WebSocket Protobuf 实时事件流与明文日志输出【免费下载链接】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 明文捕获工具无需安装 CA 证书支持 Linux/Android 内核的 amd64/arm64 架构。本篇文章围绕仓库中的 docs/event-forward-api.md 展开系统讲解 eCapture 的三类事件/日志输出通道--logaddr运行时日志、--eventaddr文本事件日志、--ecaptureqWebSocket Protobuf 结构化事件流。读完本文你将掌握 eCapture 事件转发 API 的完整协议结构、输出优先级规则并能用 Go 或其他语言快速实现一个实时接收 TLS/HTTP 明文事件的客户端将其接入自己的存储、消息队列或分析系统。一、三个输出参数与优先级eCapture 对外暴露了三个与日志/事件输出相关的参数分别覆盖运行时日志与捕获事件两类数据流参数输出内容格式典型场景--logaddreCapture 自身运行时日志初始化信息、模块启动、配置详情、错误等纯文本记录 eCapture 运行状态--eventaddr捕获的事件日志纯文本直接写入文件 / TCP 流 / 已有日志管道--ecaptureq运行时日志 捕获事件WebSocket ProtobufLogEntry结构化、程序化消费实时事件流1.1--logaddr运行时日志文本作用指定 eCapture 自身运行时日志的写入位置。支持的输出目标文件路径例如/var/log/ecapture.logtcp://host:portws://host:port/path或wss://host:port/path。内容初始化信息、模块启动、配置详情、错误等格式为纯文本。在源码层面该参数对应 cli/cmd/root.go 中的持久化标志定义rootCmd.PersistentFlags().StringVarP(globalConf.LoggerAddr, logaddr, l, , send logs to this server. -l /tmp/ecapture.log or -l ws://127.0.0.1:8090/ecapture or -l tcp://127.0.0.1:8080)initLogger见 cli/cmd/root.go会依据地址前缀自动分派 writertcp://走net.Dial建立 TCP 连接ws:///wss://走 WebSocket 客户端其余视为本地文件日志同时写入控制台与目标 writerzerolog.MultiLevelWriter。1.2--eventaddr捕获事件文本作用指定捕获事件日志的写入位置。支持的目标与--logaddr类似文件 / TCP / WebSocket但输出内容是文本格式的事件日志。典型使用场景将事件直接写入文件、TCP 流或已有日志管道下游系统只接受纯文本日志、暂不需要 Protobuf 解析时。对应标志定义见 cli/cmd/root.gorootCmd.PersistentFlags().StringVar(globalConf.EventCollectorAddr, eventaddr, , the server address that receives the captured event. --eventaddr ws://127.0.0.1:8090/ecapture or tcp://127.0.0.1:8090, default: same as logaddr)注意该参数默认与logaddr相同即不单独指定时事件日志会跟随运行时日志一起输出。此外当--eventaddr指向本地文件时还可以用两个附加参数控制日志轮转见 cli/cmd/root.go--eventroratesize轮转大小MB范围 1~65535例如--eventaddrtls.log --eventroratesize1--eventroratetime轮转时间秒范围 1~65535例如--eventroratetime30。该轮转逻辑由 pkg/util/roratelog/rorate.go 实现仅在--eventaddr为文件时生效。1.3--ecaptureq统一事件转发WebSocket Protobuf作用启动一个WebSocket 服务器eCaptureQ将运行时日志与捕获事件以结构化的LogEntryProtobuf 消息流式推送给连接进来的客户端。示例# 在 localhost:28257 启动 eCaptureQ sudo ./ecapture tls --ecaptureqws://127.0.0.1:28257/特性客户端通过 WebSocket 连接每条消息都是二进制 Protobuf 编码的LogEntry通过log_type字段区分心跳 / 进程日志 / 事件。从源码看--ecaptureq的处理位于 cli/cmd/root.go解析 URL 后调用ecaptureq.NewServer(parsedURL.Host, os.Stdout)创建服务端并将ecaptureQLogWriter注入 zerolog承接运行时日志、将ecaptureQEventWriter通过probeConfig.SetEventWriter(eqEventWriter)注入探针配置承接捕获事件。这两个 writer 定义在 cli/cmd/ecaptureq.go分别调用es.WriteLog与es.WriteEvent。1.4eventaddr与ecaptureq的关系与优先级两者都定义事件输出通道区别在于格式与传输方式--eventaddr纯文本格式的事件日志--ecaptureq通过 WebSocket 以Protobuf(LogEntry) 格式推送事件与日志。优先级规则若--ecaptureq与--eventaddr同时设置eCapture优先使用--ecaptureq流式推送事件简言之需要结构化、可程序化消费的事件流 → 使用--ecaptureq只需要纯文本日志输出→ 使用--eventaddr。这一优先级在探针输出 writer 的选择逻辑中得到印证见 internal/probe/base/base_probe.go先判断cfg.GetEventWriter()eCaptureQ 注入的 writer是否为空非空则优先使用否则再根据eventAddr创建文件/TCP/WebSocket writer 或回退到 logger writer。二、使用 eCaptureQ WebSocket推荐方案若需要实时、结构化的 WebSocket Protobuf 事件流请使用--ecaptureq并参考仓库内的协议文档与官方 demo 客户端。2.1 协议与消息结构核心参考文件Protobuf 定义protobuf/proto/v1/ecaptureq.proto协议总览protobuf/PROTOCOLS.md命名空间与生成代码Proto 包名eventGo 包路径./pboption go_package ./pb;源文件位置protobuf/proto/v1/ecaptureq.proto生成代码位置protobuf/gen/v1/ecaptureq.pb.go顶层消息LogEntrymessage LogEntry { LogType log_type 1; oneof payload { Event event_payload 2; Heartbeat heartbeat_payload 3; string run_log 4; } }LogType枚举枚举值数值含义LOG_TYPE_HEARTBEAT0心跳消息用于健康检查与连接保活LOG_TYPE_PROCESS_LOG1eCapture 运行时日志进程执行日志、错误消息等LOG_TYPE_EVENT2捕获的业务事件如 TLS/HTTP 数据Event字段统一表示 eCapture 捕获的单条事件即报文/会话片段字段类型说明timestampint64事件时间戳uuidstring唯一事件标识用于关联与去重src_ip/src_portstring / uint32源 IP 与端口dst_ip/dst_portstring / uint32目的 IP 与端口pidint64进程 IDpnamestring进程名例如curl、nginxtypeuint32事件/协议类型枚举值见下表lengthuint32payload的有效长度字节payloadbytes实际载荷数据type字段取值含义0Unknown1HTTP/1.x Request2HTTP/2 Request3HTTP/1.x Response4HTTP/2 Response说明在 eCaptureQ 内部后端模型中is_binary、payload_utf8、payload_binary等字段是服务端与 UI 内部使用的派生扩展字段用于区分文本/二进制展示不直接出现在 Protobuf 的Event消息中见 protobuf/PROTOCOLS.md。Heartbeat字段字段类型说明timestampint64心跳发送时间戳countint64心跳计数或累计事件数等统计值messagestring附加信息如版本号、状态描述等2.2 官方 Go Demo 客户端若使用 Go最快捷的方式是直接复用官方 demo目录examples/ecaptureq_client/代码examples/ecaptureq_client/main.go使用说明examples/ecaptureq_client/README.mddemo 已实现完整链路连接--ecaptureq指定的 WebSocket 服务器持续读取二进制消息解码为pb.LogEntry位于 protobuf/gen/v1按LogType分发处理打印运行时日志以人类可读方式展示捕获事件payload 支持文本 / hex / base64可选 verbose 模式展示心跳。Demo 快速上手# 1. 启动带 eCaptureQ 的 eCapture sudo ./ecapture tls --ecaptureqws://127.0.0.1:28257/ # 2. 构建客户端 cd examples/ecaptureq_client go build -o ecaptureq_client main.go # 3. 连接并观察事件 ./ecaptureq_client -server ws://127.0.0.1:28257/ # 或者 ./ecaptureq_client -server ws://192.168.1.100:28257/ -verbose也可以在仓库根目录直接构建go build -o ecaptureq_client ./examples/ecaptureq_client。Demo 客户端命令行参数参数默认值说明-serverws://127.0.0.1:28257/WebSocket 服务器 URL-verbosefalse启用 verbose 日志显示心跳消息示例输出节选自 examples/ecaptureq_client/README.mdConnecting to eCapture WebSocket server at ws://127.0.0.1:28257/ Connected successfully! 2025-01-15T10:30:45Z INF AppNameeCapture(旁观者) 2025-01-15T10:30:45Z INF HomePagehttps://v2.ecapture.cc 2025-01-15T10:30:45Z INF Versionlinux_amd64:v1.4.3-20250115:5.15.0 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Captured Event ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ UUID: 12345_12345_curl_5_1_192.168.1.100:54870-180.101.49.44:443 PID: 12345 Process: curl Source: 192.168.1.100:54870 Destination: 180.101.49.44:443 Type: 1 Length: 104 bytes ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Payload: ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ GET / HTTP/1.1 Host: www.baidu.com Accept: */* User-Agent: curl/7.81.0 Base64 encoded: R0VUIC8gSFRUUC8xLjENCkhvc3Q6IHd3dy5iYWlkdS5jb20NCkFjY2VwdDogKi8qDQpVc2VyLUFnZW50OiBjdXJsLzcuODEuMA0KDQo ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━将 demo 集成到自有系统从main.go复制接收 解码 分发的核心逻辑把打印到终端替换为写入你自己的存储、消息队列或分析引擎。从源码看demo 的可打印性判定采用 90% 阈值当可打印字符ASCII 32~126 及\n、\r、\t占比超过printableThreshold 0.9时按文本展示否则输出 hex dump并同时给出 base64 编码见 examples/ecaptureq_client/main.go 与isPrintable/printHexDump实现。最小集成示例Go摘自 protobuf/PROTOCOLS.mdimport ( pb github.com/gojue/ecapture/protobuf/gen/v1 golang.org/x/net/websocket google.golang.org/protobuf/proto ) // Connect ws, err : websocket.Dial(ws://127.0.0.1:28257/, , http://localhost/) if err ! nil { // Handle error } defer ws.Close() // Receive messages for { var msgData []byte err : websocket.Message.Receive(ws, msgData) if err ! nil { break } var logEntry pb.LogEntry err proto.Unmarshal(msgData, logEntry) if err ! nil { continue } // Process logEntry based on logEntry.LogType }2.3 服务端行为心跳、缓冲与广播从服务端实现可以进一步理解协议行为源码见 pkg/ecaptureq/server.go、pkg/ecaptureq/hub.go、pkg/ecaptureq/client.go心跳每个客户端连接建立后立即发送一次心跳之后每 15 秒由writePump中的time.NewTicker(15 * time.Second)触发心跳消息的message字段形如heartbeat:countcount为累计心跳次数见 pkg/ecaptureq/client.go。日志缓冲Server内置容量为LogBuffLen 128的日志缓冲区新客户端连接时会通过sendLogBuff收到此前预存的运行日志避免错过早期启动信息见 pkg/ecaptureq/server.go。广播机制Hub维护客户端注册表broadcast通道将消息推送给所有在线客户端发送缓冲区写满的慢客户端会被摘除见 pkg/ecaptureq/hub.go。编码细节WriteEvent构造LogEntry时以Event的payload直接承载原始字节并同步填充length字段见 pkg/ecaptureq/server.go。2.4 从其他语言集成对于其他语言Python / Java / Node.js / Rust 等接入模式完全一致使用该语言的 Protobuf 工具基于 protobuf/proto/v1/ecaptureq.proto 生成类型使用该语言的 WebSocket 客户端库连接ws://HOST:PORT/注意URL 必须以/结尾循环处理从 WebSocket 读取一条二进制消息解码为LogEntry根据log_type心跳 / 进程日志 / 事件分发处理。可以先运行 examples/ecaptureq_client 观察真实流量再在目标语言中复刻相同逻辑。三、使用eventaddr/logaddr输出纯文本日志如果不想处理 Protobuf只需要纯文本日志用--logaddr输出 eCapture 运行时日志用--eventaddr输出捕获的事件日志文本。示例一运行时日志与事件日志分别写入不同文件./ecapture tls \ --logaddr/var/log/ecapture.log \ --eventaddr/var/log/ecapture-events.log示例二通过 TCP 将事件日志发送到远端服务./ecapture tls \ --eventaddrtcp://192.168.1.100:9000在这种模式下作为客户端你只需要从配置好的文件或 TCP 流中读取按行或所选文本格式解析日志/事件。再次提醒若同时设置--ecaptureq与--eventaddr事件将优先通过--ecaptureq推送WebSocket Protobuf。eventaddr主要适用于未启用 eCaptureQ、仅需文本日志的场景。常见问题排查参考 examples/ecaptureq_client/README.md 中的 Troubleshooting 章节连接被拒connection refused确认 eCapture 已带--ecaptureq参数运行检查客户端-serverURL 与 eCapture 命令中的地址一致确认端口未被防火墙拦截确保使用具体 IP如127.0.0.1或本机 IP而非0.0.0.0。已连接但收不到事件确认 eCapture 正在捕获流量可用-d调试标志检查生成一些 SSL/TLS 流量例如curl https://www.baidu.com用./ecaptureq_client -verbose观察心跳以确认连接活性。Bad Handshake确认 URL 格式为ws://HOST:PORT/带尾部斜杠用netstat -tlnp | grep PORT检查 eCapture 是否真正在监听确认连接的是正确端口。四、总结需要结构化、程序化消费事件时使用--ecaptureq并参考protobuf/proto/v1/ecaptureq.proto协议定义protobuf/PROTOCOLS.md协议总览与字段语义examples/ecaptureq_client/官方 Go demo 客户端需要纯文本日志时用--logaddr输出运行时日志用--eventaddr输出事件日志无需 Protobuf。两者同时配置时--ecaptureq优先级最高优先通过 WebSocket Protobuf 推送事件与日志。相关的中文文档还可在 docs/event-forward-api-zh_Hans.md 查看事件前向Event Forward的整体说明见 docs/event-forward.md。通过本文所述的 API 与协议你可以将 eCapture 捕获的 HTTPS/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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考