Wazuh Inventory Sync API 参考模块接口、FlatBuffer 协议与索引状态数据的完整解析【免费下载链接】wazuhWazuh - The Open Source Security Platform. Unified XDR and SIEM protection for endpoints and cloud workloads.项目地址: https://gitcode.com/GitHub_Trending/wa/wazuhInventory Sync 是 Wazuh Manager 侧的 Agent 状态同步服务负责接收 Agent 经 Router 主题inventory-states发送的 FlatBuffer 消息、将会话数据暂存到 RocksDB并最终把状态文档写入 Wazuh Indexer 的wazuh-states-*索引族。本文基于 api-reference.md 展开完整覆盖该模块的两类 API 表面模块 start/stop 接口与索引状态数据面、FlatBuffer 运行时协议、全部支持的状态索引、Indexer 查询方式以及索引文档的真实结构并结合仓库源码说明每个接口背后的实现细节帮助你在部署、调试或二次开发 Inventory Sync 时快速定位其行为边界。一、Inventory Sync 暴露的两类 API 表面按照 api-reference.md 的定义Inventory Sync 对外暴露两个 API 表面模块 start/stop 接口由 Wazuh 模块加载器Manager 进程中的模块框架调用用于启动和停止整个同步服务索引状态数据面Indexed state data surface通过 Wazuh Indexer 暴露即同步完成后落入wazuh-states-*索引族的文档可通过 OpenSearch 风格的搜索 API 查询。需要强调的是Inventory Sync 只运行在Manager 端。Agent 是同步消息的生产者Manager 拥有会话状态、RocksDB 持久化、Indexer 操作与响应分发的全部职责。协议围绕Start开会话、数据消息DataValue/DataBatch等、End关会话三个阶段组织支持全量、增量、完整性校验、元数据与分组对账等模式详见 architecture.md。二、模块接口C 入口点与 C 门面2.1 C 入口点共享库导出两个符号声明位于 inventory_sync.hEXPORTED void inventory_sync_start(full_log_fnc_t callbackLog, const cJSON* configuration); EXPORTED void inventory_sync_stop();inventory_sync_start接收一个日志回调callbackLog类型为full_log_fnc_t签名定义为(int, const char*, const char*, int, const char*, const char*, va_list)和一份 cJSON 配置inventory_sync_stop无参数负责停止模块。在 GNU 编译器GCC 4 及以上下EXPORTED宏展开为__attribute__((visibility(default)))保证这两个符号在动态库中可见见 inventory_sync.h#L15-L21。头文件还定义了inventory_sync_start_func/inventory_sync_stop_func两个函数指针类型供 C 侧包装器以“类型化指针”方式持有动态解析出的符号。Manager 侧的包装器 wm_inventory_sync.c 在模块启动时通过so_get_module_handle(inventory_sync)动态加载共享库再用so_get_function_sym分别解析出inventory_sync_start与inventory_sync_stopwm_inventory_sync.c#L57-L60并在模块start与stop生命周期钩子中调用它们。如果解析失败模块仅打印Unable to start/stop inventory_sync module警告并退出。2.2 C 门面FacadeC 入口最终转入 C 单例门面 InventorySync其公开接口为class InventorySync final : public SingletonInventorySync { public: void start(const std::functionvoid(...) logFunction, const nlohmann::json configuration) const; void stop() const; };从 inventorySync.cpp 的实现可以看到完整的 C → C 桥接链路inventory_sync_start将 cJSON 配置序列化为字符串再解析为nlohmann::json把原生日志回调callbackLog包装为std::function形式的日志函数调用InventorySync::instance().start(...)其内部再委托给InventorySyncFacade::instance().start(...)inventorySync.cpp#L22-L34。即真实的编排逻辑RocksDB 会话存储、Router 订阅、消息校验分发、索引执行等落在InventorySyncFacade中InventorySync单例只是对外稳定的 C 入口stop()同理委托给 Facade。2.3 模块启动时注入的配置从 wm_inventory_sync.c#L54-L106 可以确认模块框架在调用inventory_sync_start前会构造如下 JSON 配置配置键及其取值来源配置键来源默认值/取值范围indexer全局indexer_config为空时传空对象—clusterNameget_cluster_name()5.x 起集群默认启用—clusterNodeNameget_node_name()—maxSessions内部选项wazuh_modules.max_sessions默认 1000范围 1–100000queueSize内部选项wazuh_modules.inventory_sync_queue_size默认 1000范围 100–1000000dataValueQuota内部选项wazuh_modules.inventory_sync_data_value_quota默认 250000范围 1–1000000000indexerBulkSize内部选项wazuh_modules.inventory_sync_indexer_bulk_size_bytes默认 10 MB范围 4 KB–100 MBindexerFlushInterval内部选项wazuh_modules.inventory_sync_indexer_flush_interval秒默认 20范围 1–3600这些参数正是后续会话上限控制、输入队列长度、DataValue 配额以及批量索引大小/刷新节奏的调节旋钮可结合 configuration.md 一并参考。三、运行时协议面FlatBuffer 消息类型Inventory Sync 接受的 FlatBuffer 协议消息来自 flatbuffers.md对应线上模式文件 inventorySync.fbs包括消息方向作用StartAgent → Manager开会话携带模块名、模式、目标索引、Agent 身份与集群字段DataValueAgent → Manager主要的可索引负载单条 upsert/delete 文档DataBatchAgent → Manager一条消息内携带多个DataValueManager 内部拆包为独立会话记录DataContextAgent → Manager辅助上下文数据存 RocksDB_context后缀参与断点跟踪但不直接索引DataCleanAgent → Manager请求对指定 Agent 与索引执行deleteByQueryChecksumModuleAgent → ManagerModuleCheck模式下携带 Agent 侧校验和EndAgent → Manager关闭会话的上传侧Manager 确认收到End且所有序列消息齐备后才完成会话ReqRet双向重传请求携带缺失的序列区间Pair{begin, end}列表Manager 侧产生的响应包括StartAckStart成功后返回分配的 64 位会话 ID 与StatusEndAck返回会话的最终处理结果ReqRet当GapSet检测到缺失序列区间时Manager 主动请求 Agent 重传。所有消息都封装在Message根表中通过MessageType联合类型union区分具体负载table Message { content: MessageType; } union MessageType { DataValue, DataClean, ChecksumModule, Start, StartAck, End, EndAck, ReqRet, DataContext, DataBatch }关键的枚举定义也值得在排查问题时对照ModeModuleFull、ModuleDelta、ModuleCheck、MetadataDelta、MetadataCheck、GroupDelta、GroupCheckOperationUpsert/DeleteStatusOk、Error、Offline、ChecksumMismatch、ProcessingOptionSync、VDFirst、VDSync后两者用于在会话持久化后触发 Vulnerability Scanner 扫描。实用细节引自 flatbuffers.md 的 “Practical notes”对MetadataDelta、MetadataCheck、GroupDelta、GroupCheck和ModuleCheck会话Start.size可以为 0这类会话没有需要序列跟踪的数据消息DataContext属于活协议的一部分即使不会被回放进 Indexer生成或校验 Inventory Sync 流量的工具仍应支持它DataBatch同样属于活协议工具链必须支持。四、索引状态数据面wazuh-states-*索引族Inventory Sync 针对wazuh-states-*索引族工作。当前支持的库存inventory族包括4.1 Syscollector 索引13 个wazuh-states-inventory-systemwazuh-states-inventory-hardwarewazuh-states-inventory-hotfixeswazuh-states-inventory-packageswazuh-states-inventory-processeswazuh-states-inventory-portswazuh-states-inventory-interfaceswazuh-states-inventory-protocolswazuh-states-inventory-networkswazuh-states-inventory-userswazuh-states-inventory-groupswazuh-states-inventory-serviceswazuh-states-inventory-browser-extensions4.2 FIM 索引3 个wazuh-states-fim-fileswazuh-states-fim-registry-keyswazuh-states-fim-registry-values4.3 SCA 索引1 个wazuh-states-sca4.4 相关的下游索引wazuh-states-vulnerabilities需要特别注意wazuh-states-vulnerabilities不是Inventory Sync 直接写入的但它属于当前 Manager 侧流程的一部分因为 Inventory Sync 可以在同一个同步会话中当Start的option为VDFirst或VDSync时触发漏洞扫描最终文档由 Vulnerability Scanner 产出。五、查询同步后的状态数据状态数据通过 Wazuh Indexer 的搜索 API 查询。以下示例与 api-reference.md 保持一致5.1 搜索全部状态索引GET /wazuh-states-*/_search5.2 跨所有状态索引搜索某一个 AgentGET /wazuh-states-*/_search { query: { term: { wazuh.agent.id: 001 } } }5.3 搜索某一个 Agent 的 SCA 文档GET /wazuh-states-sca/_search { query: { term: { wazuh.agent.id: 001 } } }5.4 搜索某一个 Agent 的库存软件包组合过滤GET /wazuh-states-inventory-packages/_search { query: { bool: { filter: [ { term: { wazuh.agent.id: 001 } }, { exists: { field: package.name } } ] } } }从 architecture.md 的组件说明可以推断wazuh.agent.id这一字段正是 Manager 在 End 阶段富化文档时注入的元数据之一因此按 Agent 维度查询是排查单个 Agent 同步状态最常用的入口而exists过滤可用于排除字段缺失的半成品文档。六、索引文档的真实结构Document ShapeInventory Sync 在向 Indexer 发送文档前会先注入 Manager 侧元数据。实际 upsert 的文档至少包含以下字段wazuh.agent.idwazuh.agent.namewazuh.agent.versionwazuh.agent.groupswazuh.agent.host.architecturewazuh.agent.host.hostnamewazuh.agent.host.os.*wazuh.cluster.nameAgent 侧的领域负载随后附加在这些元数据之后。以一个软件包文档为例{ wazuh: { agent: { id: 001, name: ubuntu22, version: v5.0.0, groups: [default], host: { architecture: x86_64, hostname: ubuntu22, os: { name: Ubuntu, platform: ubuntu, type: linux, version: 22.04.5 LTS } } }, cluster: { name: cluster } }, package: { name: openssl, version: 3.0.2, type: deb }, checksum: { hash: { sha1: ... } }, state: { modified_at: 2026-04-20T10:00:00.000Z } }这一结构解释了两个设计事实其一wazuh.cluster.name来自模块启动时由 wm_inventory_sync.c 注入的clusterName配置随会话上下文传播其二state.modified_at与checksum字段为ModuleCheck校验和和状态对账提供了比对基础。七、小结与延伸阅读接口层inventory_sync_start/inventory_sync_stop两个 C 符号由 wm_inventory_sync.c 动态加载经 InventorySync 单例 委托给InventorySyncFacade完成真正的编排协议层以Message根表 MessageTypeunion 为核心的 FlatBuffer 会话协议支持批量、断点重传、校验和对DataContext旁路存储数据层13 个 Syscollector 索引 3 个 FIM 索引 SCA 索引 下游wazuh-states-vulnerabilities文档统一携带wazuh.agent.*与wazuh.cluster.name元数据可通过 Indexer 搜索 API 按 Agent 维度查询。如需继续深入可参考同一文档目录下的 架构说明、FlatBuffer 模式细节、配置参考 与 测试工具以及线上协议模式源文件 inventorySync.fbs。【免费下载链接】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），仅供参考 
长河君 · 2026/9/14 6:18:45 · 阅读 1.2k Wazuh Inventory Sync API 参考：模块接口、FlatBuffer 协议与索引状态数据的完整解析
Wazuh Inventory Sync API 参考模块接口、FlatBuffer 协议与索引状态数据的完整解析【免费下载链接】wazuhWazuh - The Open Source Security Platform. Unified XDR and SIEM protection for endpoints and cloud workloads.项目地址: https://gitcode.com/GitHub_Trending/wa/wazuhInventory Sync 是 Wazuh Manager 侧的 Agent 状态同步服务负责接收 Agent 经 Router 主题inventory-states发送的 FlatBuffer 消息、将会话数据暂存到 RocksDB并最终把状态文档写入 Wazuh Indexer 的wazuh-states-*索引族。本文基于 api-reference.md 展开完整覆盖该模块的两类 API 表面模块 start/stop 接口与索引状态数据面、FlatBuffer 运行时协议、全部支持的状态索引、Indexer 查询方式以及索引文档的真实结构并结合仓库源码说明每个接口背后的实现细节帮助你在部署、调试或二次开发 Inventory Sync 时快速定位其行为边界。一、Inventory Sync 暴露的两类 API 表面按照 api-reference.md 的定义Inventory Sync 对外暴露两个 API 表面模块 start/stop 接口由 Wazuh 模块加载器Manager 进程中的模块框架调用用于启动和停止整个同步服务索引状态数据面Indexed state data surface通过 Wazuh Indexer 暴露即同步完成后落入wazuh-states-*索引族的文档可通过 OpenSearch 风格的搜索 API 查询。需要强调的是Inventory Sync 只运行在Manager 端。Agent 是同步消息的生产者Manager 拥有会话状态、RocksDB 持久化、Indexer 操作与响应分发的全部职责。协议围绕Start开会话、数据消息DataValue/DataBatch等、End关会话三个阶段组织支持全量、增量、完整性校验、元数据与分组对账等模式详见 architecture.md。二、模块接口C 入口点与 C 门面2.1 C 入口点共享库导出两个符号声明位于 inventory_sync.hEXPORTED void inventory_sync_start(full_log_fnc_t callbackLog, const cJSON* configuration); EXPORTED void inventory_sync_stop();inventory_sync_start接收一个日志回调callbackLog类型为full_log_fnc_t签名定义为(int, const char*, const char*, int, const char*, const char*, va_list)和一份 cJSON 配置inventory_sync_stop无参数负责停止模块。在 GNU 编译器GCC 4 及以上下EXPORTED宏展开为__attribute__((visibility(default)))保证这两个符号在动态库中可见见 inventory_sync.h#L15-L21。头文件还定义了inventory_sync_start_func/inventory_sync_stop_func两个函数指针类型供 C 侧包装器以“类型化指针”方式持有动态解析出的符号。Manager 侧的包装器 wm_inventory_sync.c 在模块启动时通过so_get_module_handle(inventory_sync)动态加载共享库再用so_get_function_sym分别解析出inventory_sync_start与inventory_sync_stopwm_inventory_sync.c#L57-L60并在模块start与stop生命周期钩子中调用它们。如果解析失败模块仅打印Unable to start/stop inventory_sync module警告并退出。2.2 C 门面FacadeC 入口最终转入 C 单例门面 InventorySync其公开接口为class InventorySync final : public SingletonInventorySync { public: void start(const std::functionvoid(...) logFunction, const nlohmann::json configuration) const; void stop() const; };从 inventorySync.cpp 的实现可以看到完整的 C → C 桥接链路inventory_sync_start将 cJSON 配置序列化为字符串再解析为nlohmann::json把原生日志回调callbackLog包装为std::function形式的日志函数调用InventorySync::instance().start(...)其内部再委托给InventorySyncFacade::instance().start(...)inventorySync.cpp#L22-L34。即真实的编排逻辑RocksDB 会话存储、Router 订阅、消息校验分发、索引执行等落在InventorySyncFacade中InventorySync单例只是对外稳定的 C 入口stop()同理委托给 Facade。2.3 模块启动时注入的配置从 wm_inventory_sync.c#L54-L106 可以确认模块框架在调用inventory_sync_start前会构造如下 JSON 配置配置键及其取值来源配置键来源默认值/取值范围indexer全局indexer_config为空时传空对象—clusterNameget_cluster_name()5.x 起集群默认启用—clusterNodeNameget_node_name()—maxSessions内部选项wazuh_modules.max_sessions默认 1000范围 1–100000queueSize内部选项wazuh_modules.inventory_sync_queue_size默认 1000范围 100–1000000dataValueQuota内部选项wazuh_modules.inventory_sync_data_value_quota默认 250000范围 1–1000000000indexerBulkSize内部选项wazuh_modules.inventory_sync_indexer_bulk_size_bytes默认 10 MB范围 4 KB–100 MBindexerFlushInterval内部选项wazuh_modules.inventory_sync_indexer_flush_interval秒默认 20范围 1–3600这些参数正是后续会话上限控制、输入队列长度、DataValue 配额以及批量索引大小/刷新节奏的调节旋钮可结合 configuration.md 一并参考。三、运行时协议面FlatBuffer 消息类型Inventory Sync 接受的 FlatBuffer 协议消息来自 flatbuffers.md对应线上模式文件 inventorySync.fbs包括消息方向作用StartAgent → Manager开会话携带模块名、模式、目标索引、Agent 身份与集群字段DataValueAgent → Manager主要的可索引负载单条 upsert/delete 文档DataBatchAgent → Manager一条消息内携带多个DataValueManager 内部拆包为独立会话记录DataContextAgent → Manager辅助上下文数据存 RocksDB_context后缀参与断点跟踪但不直接索引DataCleanAgent → Manager请求对指定 Agent 与索引执行deleteByQueryChecksumModuleAgent → ManagerModuleCheck模式下携带 Agent 侧校验和EndAgent → Manager关闭会话的上传侧Manager 确认收到End且所有序列消息齐备后才完成会话ReqRet双向重传请求携带缺失的序列区间Pair{begin, end}列表Manager 侧产生的响应包括StartAckStart成功后返回分配的 64 位会话 ID 与StatusEndAck返回会话的最终处理结果ReqRet当GapSet检测到缺失序列区间时Manager 主动请求 Agent 重传。所有消息都封装在Message根表中通过MessageType联合类型union区分具体负载table Message { content: MessageType; } union MessageType { DataValue, DataClean, ChecksumModule, Start, StartAck, End, EndAck, ReqRet, DataContext, DataBatch }关键的枚举定义也值得在排查问题时对照ModeModuleFull、ModuleDelta、ModuleCheck、MetadataDelta、MetadataCheck、GroupDelta、GroupCheckOperationUpsert/DeleteStatusOk、Error、Offline、ChecksumMismatch、ProcessingOptionSync、VDFirst、VDSync后两者用于在会话持久化后触发 Vulnerability Scanner 扫描。实用细节引自 flatbuffers.md 的 “Practical notes”对MetadataDelta、MetadataCheck、GroupDelta、GroupCheck和ModuleCheck会话Start.size可以为 0这类会话没有需要序列跟踪的数据消息DataContext属于活协议的一部分即使不会被回放进 Indexer生成或校验 Inventory Sync 流量的工具仍应支持它DataBatch同样属于活协议工具链必须支持。四、索引状态数据面wazuh-states-*索引族Inventory Sync 针对wazuh-states-*索引族工作。当前支持的库存inventory族包括4.1 Syscollector 索引13 个wazuh-states-inventory-systemwazuh-states-inventory-hardwarewazuh-states-inventory-hotfixeswazuh-states-inventory-packageswazuh-states-inventory-processeswazuh-states-inventory-portswazuh-states-inventory-interfaceswazuh-states-inventory-protocolswazuh-states-inventory-networkswazuh-states-inventory-userswazuh-states-inventory-groupswazuh-states-inventory-serviceswazuh-states-inventory-browser-extensions4.2 FIM 索引3 个wazuh-states-fim-fileswazuh-states-fim-registry-keyswazuh-states-fim-registry-values4.3 SCA 索引1 个wazuh-states-sca4.4 相关的下游索引wazuh-states-vulnerabilities需要特别注意wazuh-states-vulnerabilities不是Inventory Sync 直接写入的但它属于当前 Manager 侧流程的一部分因为 Inventory Sync 可以在同一个同步会话中当Start的option为VDFirst或VDSync时触发漏洞扫描最终文档由 Vulnerability Scanner 产出。五、查询同步后的状态数据状态数据通过 Wazuh Indexer 的搜索 API 查询。以下示例与 api-reference.md 保持一致5.1 搜索全部状态索引GET /wazuh-states-*/_search5.2 跨所有状态索引搜索某一个 AgentGET /wazuh-states-*/_search { query: { term: { wazuh.agent.id: 001 } } }5.3 搜索某一个 Agent 的 SCA 文档GET /wazuh-states-sca/_search { query: { term: { wazuh.agent.id: 001 } } }5.4 搜索某一个 Agent 的库存软件包组合过滤GET /wazuh-states-inventory-packages/_search { query: { bool: { filter: [ { term: { wazuh.agent.id: 001 } }, { exists: { field: package.name } } ] } } }从 architecture.md 的组件说明可以推断wazuh.agent.id这一字段正是 Manager 在 End 阶段富化文档时注入的元数据之一因此按 Agent 维度查询是排查单个 Agent 同步状态最常用的入口而exists过滤可用于排除字段缺失的半成品文档。六、索引文档的真实结构Document ShapeInventory Sync 在向 Indexer 发送文档前会先注入 Manager 侧元数据。实际 upsert 的文档至少包含以下字段wazuh.agent.idwazuh.agent.namewazuh.agent.versionwazuh.agent.groupswazuh.agent.host.architecturewazuh.agent.host.hostnamewazuh.agent.host.os.*wazuh.cluster.nameAgent 侧的领域负载随后附加在这些元数据之后。以一个软件包文档为例{ wazuh: { agent: { id: 001, name: ubuntu22, version: v5.0.0, groups: [default], host: { architecture: x86_64, hostname: ubuntu22, os: { name: Ubuntu, platform: ubuntu, type: linux, version: 22.04.5 LTS } } }, cluster: { name: cluster } }, package: { name: openssl, version: 3.0.2, type: deb }, checksum: { hash: { sha1: ... } }, state: { modified_at: 2026-04-20T10:00:00.000Z } }这一结构解释了两个设计事实其一wazuh.cluster.name来自模块启动时由 wm_inventory_sync.c 注入的clusterName配置随会话上下文传播其二state.modified_at与checksum字段为ModuleCheck校验和和状态对账提供了比对基础。七、小结与延伸阅读接口层inventory_sync_start/inventory_sync_stop两个 C 符号由 wm_inventory_sync.c 动态加载经 InventorySync 单例 委托给InventorySyncFacade完成真正的编排协议层以Message根表 MessageTypeunion 为核心的 FlatBuffer 会话协议支持批量、断点重传、校验和对DataContext旁路存储数据层13 个 Syscollector 索引 3 个 FIM 索引 SCA 索引 下游wazuh-states-vulnerabilities文档统一携带wazuh.agent.*与wazuh.cluster.name元数据可通过 Indexer 搜索 API 按 Agent 维度查询。如需继续深入可参考同一文档目录下的 架构说明、FlatBuffer 模式细节、配置参考 与 测试工具以及线上协议模式源文件 inventorySync.fbs。【免费下载链接】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），仅供参考