Protobuf 与外部集成 ​

目的与范围 ​

本文档描述 ecapture 基于 protobuf 的事件序列化格式和外部集成能力。从版本 0.8.0 开始，ecapture 通过 Protocol Buffers 提供结构化事件流，支持与外部工具、图形界面和分析平台的实时集成。有关基于文本的控制台输出信息，请参阅 4.1 文本输出模式。有关 PCAP 文件生成，请参阅 4.2 PCAP 集成。

protobuf 格式支持：

• 结构化事件序列化，便于程序化处理
• WebSocket 流式传输，用于实时事件交付
• 与 eCaptureQ 图形界面集成
• HTTP API 用于远程配置和事件转发
• 与 Burp Suite 等工具的兼容性，用于安全分析

Protobuf 事件结构 ​

LogEntry 和 Event 模式 ​

ecapture 使用在 protobuf/proto/v1/ecaptureq.proto 中定义的分层 protobuf 模式，所有输出都封装在 LogEntry 消息中。该模式通过 LogType 枚举支持三种类型的日志条目：

Protobuf 消息结构层次

来源：protobuf/PROTOCOLS.md:14-62, pkg/event_processor/iworker.go:214-227, user/event/ievent.go:41-52

事件类型枚举 ​

Event 消息中的 type 字段对应于 pkg/event_processor/iparser.go:25-47 中定义的 ParserType 枚举，指示应如何解释载荷：

解析器类型在 NewParser() 函数 pkg/event_processor/iparser.go:85-115 中通过内容检测动态确定。对载荷调用每个注册解析器的 detect() 方法，第一个成功匹配的解析器决定解析器类型。如果没有解析器匹配，则使用 DefaultParser 并设置 ParserTypeNull。

来源：pkg/event_processor/iparser.go:25-115, pkg/event_processor/iworker.go:203-218, protobuf/PROTOCOLS.md:34-40

流水线中的事件序列化 ​

EventProcessor 到 Protobuf 的转换 ​

当事件流经事件处理流水线时，它们在输出阶段被转换为 protobuf 格式。转换发生在 eventWorker.Display() 方法中：

事件到 Protobuf 的转换序列

关键区别在于配置的 logger 是否实现了 CollectorWriter 接口。如果没有，事件将被序列化为 protobuf；否则，它们被格式化为人类可读的文本。

来源：pkg/event_processor/iworker.go:174-228, user/event/ievent.go:54-70

Protobuf 与文本模式选择 ​

输出模式由传递给 NewEventProcessor() 的 logger 类型决定：

Logger 类型决定序列化格式

这种设计允许相同的事件处理流水线同时服务于人类可读的控制台输出和结构化的 protobuf 流式传输，而无需代码重复。

来源：pkg/event_processor/iworker.go:198-228, pkg/event_processor/processor.go:206-215

WebSocket 流式传输服务器 ​

服务器架构 ​

从版本 0.8.0 开始，ecapture 包含一个嵌入式 HTTPS 服务器，提供 WebSocket 端点用于实时事件流式传输。服务器与捕获模块并发运行，监听两个端口：

嵌入式 HTTPS 服务器架构

服务器默认监听 localhost:28256 用于配置，localhost:28257 用于事件流式传输（可通过 --listen 标志配置）。关注点分离允许 HTTP API 访问而不会干扰高吞吐量的事件流。

来源：README_JA.md:83-89, pkg/event_processor/processor.go:30-50, pkg/event_processor/iworker.go:164-172

WebSocket 协议 ​

客户端连接到端口 28257 的 WebSocket 端点，并接收 protobuf 序列化的 LogEntry 消息的连续流。每个 WebSocket 消息包含恰好一个作为二进制数据封送的 pb.LogEntry：

客户端集成步骤：

1. 建立到 ws://localhost:28257/ 的 WebSocket 连接（或 wss:// 用于 TLS）
2. 持续读取二进制 WebSocket 消息
3. 使用 proto.Unmarshal() 将每条消息解组为 pb.LogEntry
4. 根据 log_type 切换以确定哪个载荷字段包含数据
5. 对于 LOG_TYPE_EVENT，访问 event_payload 以获取捕获的数据

protobuf 封送发生在 pkg/event_processor/iworker.go:222-226，其中 proto.Marshal(le) 在发送到 outComing 通道之前序列化 LogEntry。

来源：pkg/event_processor/iworker.go:214-227, protobuf/PROTOCOLS.md:54-62, protobuf/PROTOCOLS.md:68-96

连接生命周期 ​

WebSocket 连接生命周期

来源：CHANGELOG.md:82-89

eCaptureQ GUI 集成 ​

远程模式架构 ​

eCaptureQ 是 ecapture 的官方跨平台 GUI 客户端。它连接到 ecapture 的 WebSocket 端点以接收事件并提供实时可视化。远程模式架构使 Windows/macOS 客户端能够连接到 Linux 服务器：

eCaptureQ 远程模式集成

来源：README.md:287-302, README_CN.md:267-281

集成模式与远程模式 ​

eCaptureQ 支持两种部署模型：

在集成模式下，eCaptureQ 生成 ecapture 进程并通过 localhost 连接到其 WebSocket 端点。在远程模式下，用户配置远程服务器地址，eCaptureQ 通过网络建立 WebSocket 连接。

来源：README.md:293-296, README_CN.md:273-276

HTTP 配置 API ​

远程配置更新 ​

ecapture 在端口 28256 上公开 HTTP 接口，用于在不重启捕获进程的情况下进行运行时配置更新。根据 README_JA.md:88 中的启动日志，服务器显示："You can update the configuration file via the HTTP interface."

HTTP 配置接口

HTTP 配置接口架构

HTTP 接口允许在捕获运行时进行动态配置更新。特定的 API 端点和请求格式可能因版本而异。

来源：README_JA.md:88, README_JA.md:83-89

外部工具集成 ​

自定义事件消费者 ​

基于 protobuf 的事件流支持与自定义分析工具的集成。端口 28257 上的 WebSocket 端点提供了一个与语言无关的接口来消费捕获的事件：

通过 WebSocket 的外部工具集成

任何可以建立 WebSocket 连接并解析 protobuf 消息的工具都可以消费 ecapture 事件。utils/protobuf_visualizer/ 中的参考实现演示了基本的消费模式。

来源：utils/protobuf_visualizer/README.md:1-42, pkg/event_processor/iworker.go:214-227

WebSocket 客户端示例 ​

对于自定义集成，客户端可以直接连接到 ecapture 在端口 28257 上的 WebSocket 端点。utils/protobuf_visualizer/pb_debugger.go 中存在一个参考客户端实现，演示了集成模式：

示例客户端流程（伪代码）

import websocket
import protobuf_gen.ecaptureq_pb2 as pb

# 连接到事件流
ws = websocket.connect("ws://127.0.0.1:28257/")

while True:
    # 接收二进制消息
    message = ws.recv()
    
    # 解组 protobuf
    log_entry = pb.LogEntry()
    log_entry.ParseFromString(message)
    
    # 根据类型处理
    if log_entry.log_type == pb.LOG_TYPE_EVENT:
        event = log_entry.event_payload
        print(f"UUID: {event.uuid}")
        print(f"协议类型: {event.type}")
        print(f"PID: {event.pid} ({event.pname})")
        print(f"载荷长度: {event.length}")
        print(f"数据: {event.payload[:100]}...")
    elif log_entry.log_type == pb.LOG_TYPE_HEARTBEAT:
        hb = log_entry.heartbeat_payload
        print(f"心跳: count={hb.count}, msg={hb.message}")

utils/protobuf_visualizer/pb_debugger.go 中的 Go 参考实现展示了紧凑模式、十六进制显示和载荷截断的命令行选项。protobuf 模式定义记录在 protobuf/PROTOCOLS.md 中。

来源：utils/protobuf_visualizer/README.md:1-42, protobuf/PROTOCOLS.md:68-96

Protobuf 模式生成 ​

客户端必须从 protobuf/proto/v1/ecaptureq.proto 中的模式定义生成特定语言的 protobuf 绑定：

多语言的 Protobuf 代码生成

仓库在 protobuf/gen/v1/ecaptureq.pb.go 中包含预生成的 Go 绑定。要重新生成或为其他语言创建绑定，请使用 protobuf/README.md:24-42 中记录的 protoc 编译器：

protoc --proto_path=protobuf/proto \
       --go_out=protobuf/gen --go_opt=paths=source_relative \
       --go-grpc_out=protobuf/gen --go-grpc_opt=paths=source_relative \
       protobuf/proto/v1/ecaptureq.proto

对于其他语言，将 --go_out 替换为适当的插件（例如 --python_out, --java_out 等）。

来源：protobuf/README.md:1-42, protobuf/PROTOCOLS.md:3-10, pkg/event_processor/iworker.go:29

集成安全考虑 ​

网络绑定与访问控制 ​

WebSocket 和 HTTP 服务器默认绑定到 localhost，将访问限制在本地机器：

远程访问的安全最佳实践

1. 仅本地绑定：默认的 localhost 绑定防止网络暴露 README_JA.md:83
2. SSH 隧道：对于远程访问，使用 SSH 端口转发：
   bash

   ssh -L 28257:localhost:28257 user@remote-server

3. root 权限要求：ecapture 需要 root/CAP_BPF，提供操作系统级别的访问控制
4. 无内置身份验证：截至当前版本，WebSocket 接口不实现身份验证
5. 网络隔离：当需要远程访问时，在隔离或受信任的网络上部署 ecapture

来源：README_JA.md:83-89, README.md:82-86

数据隐私考虑 ​

protobuf 事件流包含来自捕获的 SSL/TLS 连接的明文载荷数据：

安全建议：

• 将 WebSocket 流视为与原始数据包捕获在敏感度方面等同
• 如果通过网络传输，为 WebSocket 连接实现 TLS（wss://）
• 确保符合组织数据处理策略
• 考虑在静态存储中加密存储的 protobuf 日志
• 在长期存储中轮换或编辑敏感数据

来源：protobuf/PROTOCOLS.md:24-42, pkg/event_processor/iworker.go:214-227