Wazuh 漏洞扫描器的 FlatBuffers 数据契约：InventorySync 同步协议与 CVE5 内容解析

Wazuh 漏洞扫描器的 FlatBuffers 数据契约InventorySync 同步协议与 CVE5 内容解析【免费下载链接】wazuhWazuh - The Open Source Security Platform. Unified XDR and SIEM protection for endpoints and cloud workloads.项目地址: https://gitcode.com/GitHub_Trending/wa/wazuh本文基于 Wazuh 仓库中的 Flatbuffers 模块文档深入讲解 Vulnerability Scanner下称 VD对 FlatBuffers 的两处关键用途InventorySync 会话的序列化传输以及 CVE5 CTI 内容的本地化解析。读完后你能完整理解SyncSchema各表字段与消息时序、Start.option如何决定扫描链路的分支以及 FlatBuffer 感知的解析器如何降低扫描过程中的 JSON 开销。FlatBuffers 在 VD 中的两个用途按照模块文档的定义VD 使用 FlatBuffers 解决两个不同层面的问题InventorySync 传输InventorySync 会话以 FlatBuffers 消息序列发送Start / DataValue / DataContext / End。Agent 侧 Syscollector 采集的 OS、软件包、hotfixes 等清单数据经此协议在 Manager 侧按会话session组织落库并驱动 VD 扫描。CTI 内容处理从 Indexer 下载的 CVE5 内容通过 FlatBuffer 感知的解析器FlatBuffer-aware parsers加工进本地数据库从而减少扫描阶段的 JSON 开销——高频的扫描路径直接读取二进制结构而非反复解析 JSON。这两条路径分别对应仓库中的两套.fbs定义文件共享同步协议定义在 inventorySync.fbsCTI 内容 schema 位于 schemas 目录包括cve5.fbs、vulnerabilityCandidate.fbs、vulnerabilityDescription.fbs、vulnerabilityRemediations.fbs与packageTranslation.fbs。SyncSchema共享的库存同步协议Schema 定义与命名空间协议 schema 定义在 inventorySync.fbs声明于Wazuh.SyncSchema命名空间并被所有参与库存同步的模块共享——VD 只是消费方之一InventorySync 模块、Syscollector 以及基准测试模拟器都依赖同一份定义。文件尾部定义了唯一的根类型与消息联合unioninventorySync.fbs#L111-L128union MessageType { DataValue, DataClean, ChecksumModule, Start, StartAck, End, EndAck, ReqRet, DataContext, DataBatch } table Message { content: MessageType; } root_type Message;所有线上消息统一封装为Message表其content字段是一个 tagged union接收方先判断MessageType类型再向下转型。这种设计使得一套根类型即可承载整个会话生命周期的全部报文。枚举定义schema 中定义了四个枚举inventorySync.fbs#L3-L30枚举取值说明ModeModuleFull、ModuleDelta、ModuleCheck、MetadataDelta、MetadataCheck、GroupDelta、GroupCheck同步模式描述会话是模块全量/增量/校验还是元数据或分组维度的同步OptionSync、VDFirst、VDSyncVD 关心的模式选择普通同步、VD 首次全量、VD 增量同步OperationUpsert、Delete单条库存文档的操作类型StatusOk、Error、Offline、ChecksumMismatch握手/结束确认Ack的返回状态。从源码结构看当前 schema 的Status枚举还包含第 5 个值ProcessinginventorySync.fbs#L18-L24用于表示仍在处理中的状态其中Option是 VD 的“分支开关”Sync表示该会话不需要触发漏洞扫描VDFirst与VDSync则会触发 VD 的后处理运行。消息序列InventorySync 会话遵循固定的握手与数据流模式Start - StartAck - DataValue/DataContext - End - EndAckStart打开会话并携带 Agent 上下文Manager 以StartAck返回session标识后续所有数据报文都引用该标识。DataValue/DataContext携带逐条库存文档。End关闭会话Manager 以EndAck确认。文档特别指出End会触发后处理包括对VDFirst/VDSync会话执行 VD 扫描。DataClean与ChecksumModule两张表同样存在于 schema 中inventorySync.fbs#L95-L105但它们服务于其他同步模式清理与校验和核对VD 只消费 Start / DataValue / DataContext / End 四种消息。这一点在源码中得到印证scanOrchestrator.hpp 中的批处理逻辑先通过Wazuh::SyncSchema::GetMessage(value.data())解包根消息然后仅对MessageType_DataValue与MessageType_DataContext两种content_type()分支做处理分别调用content_as_DataValue()/content_as_DataContext()取出具体表。核心表字段详解Start携带会话元数据与初始 OS/Agent 上下文用于初始化ScanContext。文档列出的字段与 inventorySync.fbs#L50-L69 的表定义一致字段说明module发送会话的模块名mode同步模式Mode枚举size会话内条目总数index由会话中 DataValue 条目推导出的索引列表如wazuh-states-inventory-system等optionVD 模式VDFirst或VDSyncarchitecture、hostname、osname、osplatform、ostype、osversionAgent OS 元数据对应agent.host.osagentversion、agentname、agentidAgent 元数据groupsAgent 所属分组global_version可选用于库存状态更新的全球版本号补充一点schema 中Start表还定义了cluster_name与cluster_node两个字段用于标识会话来源的集群节点属于文档未单列但可查实的字段。Start.index字段尤为关键它决定了会话中会出现哪些库存索引而 scanOrchestrator.hpp 中Start.option与索引集合的组合直接决定走哪条编排链详见下文。DataValue表示库存增量delta以 JSON 承载库存文档内容字段说明seq会话内的序列号session会话标识来自StartAckoperationUpsert或Deleteid库存文档标识符VD 将其用作 item id / 检测基准index库存索引名version库存文档版本dataJSON 库存文档host/package schema注意 schema 中data的类型是[byte]inventorySync.fbs#L32-L40FlatBuffers 负责高效的结构化传输而单条文档内容本身仍保持 JSON 文本在 VD 侧由 simdjson 解析——scanOrchestrator.hpp#L466-L485 可以看到DataValue的 JSON 解析失败时会记录Failed to parse DataValue JSON告警。DataContext为增量会话提供库存上下文context。它复用DataValue的dataJSON schema但没有operation和version字段inventorySync.fbs#L42-L48字段说明seq会话内的序列号session会话标识来自StartAckid库存文档标识符index库存索引名dataJSON 库存文档host/package schema在 VD 实现中DataContext始终按 Upsert 处理——scanOrchestrator.hpp#L513-L529 的注释明确写道 DataContext is always treated as an Upsert of details即它用于补充细节例如包增量会话中携带 OS 上下文而不产生删除语义。End仅携带session字段inventorySync.fbs#L76-L78标记会话结束并触发后处理——对VDFirst/VDSync会话即触发一次 VD 运行。源码视角Start.option 如何驱动扫描编排Start.option不仅是协议字段更是 VD 编排器的路由依据。scanOrchestrator.hpp#L42-L47 中的getOptionName()将Wazuh::SyncSchema::Option_VDFirst/Option_VDSync枚举映射为日志名随后runScan按枚举分支选择处理路径scanOrchestrator.hpp#L125-L167。结合 架构文档 的描述三种触发形态与 FlatBuffers 会话内容的对应关系为VDFirst全量清单全部放在DataValue中OS、包、hotfixes走FirstFullScan编排链OsScanner - PackageScanner - EventDetailsBuilder - EventSendReport - ResultIndexer。VDSyncFullScanWithDiffDataValue含 OS 包的 upsert/delete且会话同时包含 OS/hotfix 索引走FullScan链前置EventGetContext节点。VDSync包增量DataValue仅含包的 upsert/deleteOS 上下文改由DataContext携带走PackagesDelta链PackageScanner - EventGetCve - EventDetailsBuilder - EventSendReport - ResultIndexer。会话数据本身由 InventorySync 按 session 存入 RocksDBVD 侧的ScanContext再从中重建每会话状态。库存索引名在 scanContext.hpp#L33-L35 中硬编码为常量constexpr std::string_view OS_INDEX wazuh-states-inventory-system; constexpr std::string_view HOTFIX_INDEX wazuh-states-inventory-hotfixes; constexpr std::string_view PACKAGE_INDEX wazuh-states-inventory-packages;这正是DataValue.index/Start.index字段中出现的取值也是判断“会话中出现了哪些索引”的依据。CTI 内容处理CVE5 的 FlatBuffer 化解析文档的第二条用途是“用 FlatBuffer 感知的解析器把 CVE5 内容处理进本地数据库减少扫描阶段的 JSON 开销”。在仓库中这条路径落在 VD 的databaseFeedManager子模块databaseFeedManager 目录schema 定义cve5.fbs 按 CVSS 版本拆分了CVSS_V4_0、CVSS_V3_1、CVSS_V3_0、CVSS_V2_0等表将矢量字符串、分数、严重度等 CVE5 字段结构化同目录下的vulnerabilityCandidate.fbs、vulnerabilityDescription.fbs、vulnerabilityRemediations.fbs、packageTranslation.fbs分别描述候选漏洞、描述、修复建议与包翻译OS/包名映射。生成的解析器databaseFeedManager.hpp#L24-L26 直接包含vulnerabilityCandidate_generated.h、vulnerabilityDescription_generated.h、vulnerabilityRemediations_generated.h等 FlatBuffers 生成头文件eventDecoder.hpp#L21-L27 则引入packageTranslation_generated.h并注册packageTranslation_SCHEMA作为翻译类资源类型。落地处理updateCVEDescription、updateCVERemediations、updateCVECandidates、updateHotfixes各自消费一种 FlatBuffer 结构将解析结果写入本地 RocksDB feed 数据库。例如 updateCVEDescription.hpp#L264-L284 中通过vulnerabilityDescriptionFB构造器Finish完成 FlatBuffer 组装。这样feed 更新时完成一次性的 JSON→FlatBuffer 结构转换而扫描热路径版本匹配、CVE 检索读取的是紧凑的二进制结构避免了每次扫描重复解析大体积 JSON——这正是文档所说“reduce JSON overhead during scans”的实现落点。相关测试与工具scanOrchestrator 单元测试 与 scanContext 单元测试 覆盖了从 FlatBuffers 批数据构建ScanContext的路径inventory_sync 基准测试的会话样例 提供了VDFirst/VDSync两种 option 的真实会话 payload可用于离线回放理解线上消息形态姊妹文档 InventorySync 模块的 Flatbuffers 说明 从发送方视角描述了同一份协议可与本文的消费方视角对照阅读。小结flatbuffers.md所描述的协议契约可以概括为两点其一Wazuh.SyncSchema以Message根类型 union 的方式统一封装 Start/StartAck/DataValue/DataContext/End/EndAck 全生命周期消息Option枚举与index列表共同决定 VD 走哪条编排链其二CVE5 等 CTI 内容通过同目录下的.fbsschema 预编译为 FlatBuffer 本地数据库把 JSON 解析成本从扫描热路径转移到 feed 更新冷路径。两者结合构成了 Wazuh 5.x 中“Agent 清单 → 库存同步 → 漏洞检测”链路的序列化基础。【免费下载链接】wazuhWazuh - The Open Source Security Platform. Unified XDR and SIEM protection for endpoints and cloud workloads.项目地址: https://gitcode.com/GitHub_Trending/wa/wazuh创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考