Wazuh Syscollector 数据库架构深度解析dbsync 表设计与 Agent 同步协议的数据基础【免费下载链接】wazuhWazuh - The Open Source Security Platform. Unified XDR and SIEM protection for endpoints and cloud workloads.项目地址: https://gitcode.com/GitHub_Trending/wa/wazuhWazuh 的 SyscollectorInventory模块负责采集端点的操作系统、硬件、软件包、网络、进程、用户、服务等资产数据其持久层是一套基于 SQLite 的dbsync_*表结构同时承担着 Agent Sync Protocol 与 Manager 之间增量/全量同步的数据底座。本文基于 Syscollector 数据库架构文档 与 表定义源码 展开你将完整掌握 13 张库存表的字段语义与主键设计、table_metadata恢复机制的工作原理以及每张表如何映射到同步索引与 Wazuh indexer 中的 WCS 模式从而理解资产数据从扫描落库到索引存储的全链路。架构总览SQLite 本地库 WCS 远端模式Syscollector 使用 SQLite 数据库存储不同类型的系统库存数据每张表追踪一类系统组件及其随时间的变化。文档明确指出的实现要点本地表结构定义在 syscollectorTablesDef.hpp——每个CREATE TABLE语句以constexpr auto常量形式嵌入 C 代码数据库随模块初始化自动创建Wazuh Common SchemaWCS送往 Wazuh indexer 的标准模式文件位于src/external/indexer-plugins外部依赖通过make deps在 Agent 构建过程中下载包括inventory-system.json/inventory-groups.json/inventory-browser-extensions.jsoninventory-hardware.json/inventory-hotfixes.json/inventory-interfaces.jsoninventory-networks.json/inventory-packages.json/inventory-ports.jsoninventory-processes.json/inventory-protocols.json/inventory-services.json/inventory-users.json这些 WCS 文件定义了发往 Wazuh indexer 的标准化数据格式。一个从源码结构可以印证的设计细节syscollectorImp.cpp 中维护了两张映射表——INDEX_MAP将本地 SQLite 表名如dbsync_osinfo映射到同步索引名AGENTD_TO_INDEX_MAP则将 agentd 上报的短名如os_info、hardware、packages映射到完整索引名。这些同步索引名定义在 syscollector.h均为wazuh-states-inventory-*前缀SQLite 表agentd 上报名同步索引WCS 数据流dbsync_osinfoos_infowazuh-states-inventory-systemdbsync_hwinfohardwarewazuh-states-inventory-hardwaredbsync_hotfixeshotfixeswazuh-states-inventory-hotfixesdbsync_packagespackageswazuh-states-inventory-packagesdbsync_processesprocesseswazuh-states-inventory-processesdbsync_portsportswazuh-states-inventory-portsdbsync_network_ifacenetwork_ifacewazuh-states-inventory-interfacesdbsync_network_protocolnetwork_protocolwazuh-states-inventory-protocolsdbsync_network_addressnetwork_addresswazuh-states-inventory-networksdbsync_usersuserswazuh-states-inventory-usersdbsync_groupsgroupswazuh-states-inventory-groupsdbsync_servicesserviceswazuh-states-inventory-servicesdbsync_browser_extensionsbrowser_extensionswazuh-states-inventory-browser-extensions所有业务表都使用WITHOUT ROWID键即行并将每张表的主键字段与排序字段以常量集中声明syscollectorTablesDef.hpp 中的*_PK_FIELDS与*_ORDER_BY常量用于分页遍历与增量比对时的稳定排序。表清单与 DDL 详解以下逐表给出文档中的完整 DDL并结合 syscollectorTablesDef.hpp 的实际定义做源码级核对。操作系统信息dbsync_osinfo存储操作系统的详细信息与特征CREATE TABLE dbsync_osinfo ( hostname TEXT, architecture TEXT, os_name TEXT, os_version TEXT, os_codename TEXT, os_major TEXT, os_minor TEXT, os_patch TEXT, os_build TEXT, os_type TEXT, os_platform TEXT, os_kernel_name TEXT, os_kernel_release TEXT, os_kernel_version TEXT, os_distribution_release TEXT, os_full TEXT, checksum TEXT, PRIMARY KEY (os_name, os_version) ) WITHOUT ROWID;复合主键(os_name, os_version)唯一标识一台主机的操作系统checksum用于变更检测版本号os_major/os_minor/os_patch、构建号os_build、内核三元组等字段支撑漏洞扫描与合规检测对精确 OS 版本的依赖。硬件信息dbsync_hwinfo存储硬件规格与配置CREATE TABLE dbsync_hwinfo ( serial_number TEXT, cpu_name TEXT, cpu_cores INTEGER, cpu_speed DOUBLE, memory_total INTEGER, memory_free INTEGER, memory_used INTEGER, checksum TEXT, PRIMARY KEY (serial_number) ) WITHOUT ROWID;serial_number是主键唯一标识硬件系统cpu_*为 CPU 规格memory_*以字节为单位记录内存总量/空闲/已用。软件包dbsync_packages存储已安装软件包及其元数据CREATE TABLE dbsync_packages( name TEXT, version TEXT, vendor TEXT, installed TEXT, path TEXT, architecture TEXT, category TEXT, description TEXT, size BIGINT, priority TEXT, multiarch TEXT, source TEXT, type TEXT, checksum TEXT, PRIMARY KEY (name,version,architecture,type,path) ) WITHOUT ROWID;复合主键(name, version, architecture, type, path)同一软件包在不同架构、来源或路径下允许共存size以字节为单位installed为安装时间戳type标识包管理器类型rpm、deb、msi 等。网络接口dbsync_network_iface存储网络接口配置与流量统计CREATE TABLE dbsync_network_iface ( interface_name TEXT, interface_alias TEXT, interface_type TEXT, interface_state TEXT, interface_mtu INTEGER, host_mac TEXT, host_network_egress_packages INTEGER, host_network_ingress_packages INTEGER, host_network_egress_bytes INTEGER, host_network_ingress_bytes INTEGER, host_network_egress_errors INTEGER, host_network_ingress_errors INTEGER, host_network_egress_drops INTEGER, host_network_ingress_drops INTEGER, checksum TEXT, PRIMARY KEY (interface_name,interface_alias,interface_type) ) WITHOUT ROWID;复合主键(interface_name, interface_alias, interface_type)八组流量统计字段覆盖入/出方向的包数、字节数、错误与丢包是端点网络画像的重要数据来源。网络协议配置dbsync_network_protocol存储每个接口的协议层配置网关、DHCP、路由度量等CREATE TABLE dbsync_network_protocol ( interface_name TEXT, network_type TEXT, network_gateway TEXT, network_dhcp INTEGER, network_metric TEXT, checksum TEXT, PRIMARY KEY (interface_name,network_type) ) WITHOUT ROWID;网络地址dbsync_network_address存储每个接口上的 IP 地址分配CREATE TABLE dbsync_network_address ( interface_name TEXT, network_type INTEGER, network_ip TEXT, network_netmask TEXT, network_broadcast TEXT, checksum TEXT, PRIMARY KEY (interface_name,network_type,network_ip) ) WITHOUT ROWID;三个网络相关表iface / protocol / address均以interface_name为关联锚点在 indexer 侧组合成完整的网络画像。开放端口dbsync_ports存储开放端口与监听服务信息CREATE TABLE dbsync_ports ( network_transport TEXT, source_ip TEXT, source_port BIGINT, destination_ip TEXT, destination_port BIGINT, host_network_egress_queue BIGINT, host_network_ingress_queue BIGINT, file_inode BIGINT, interface_state TEXT, process_pid BIGINT, process_name TEXT, checksum TEXT, PRIMARY KEY (file_inode, network_transport, source_ip, source_port) ) WITHOUT ROWID;复合主键(file_inode, network_transport, source_ip, source_port)通过process_pid与process_name将端口关联到具体进程是攻击面分析哪个进程在监听哪个地址的关键关联。运行进程dbsync_processesCREATE TABLE dbsync_processes ( pid TEXT, name TEXT, state TEXT, parent_pid BIGINT, utime BIGINT, stime BIGINT, command_line TEXT, args TEXT, args_count BIGINT, start BIGINT, checksum TEXT, PRIMARY KEY (pid) ) WITHOUT ROWID;pid为主键utime/stime记录用户态/内核态 CPU 时间start为进程启动时间戳parent_pid支撑进程树还原。系统用户dbsync_users存储用户账户与认证信息字段覆盖面最广之一横跨 POSIXLinux/macOS与 Windows 账户语义CREATE TABLE dbsync_users ( user_name TEXT, user_full_name TEXT, user_home TEXT, user_id BIGINT, user_uid_signed BIGINT, user_uuid TEXT, user_groups TEXT, user_group_id BIGINT, user_group_id_signed BIGINT, user_created DOUBLE, user_roles TEXT, user_shell TEXT, user_type TEXT, user_is_hidden INTEGER, user_is_remote INTEGER, user_last_login BIGINT, user_auth_failed_count BIGINT, user_auth_failed_timestamp DOUBLE, user_password_last_change DOUBLE, user_password_expiration_date INTEGER, user_password_hash_algorithm TEXT, user_password_inactive_days INTEGER, user_password_max_days_between_changes INTEGER, user_password_min_days_between_changes INTEGER, user_password_status TEXT, user_password_warning_days_before_expiration INTEGER, process_pid BIGINT, host_ip TEXT, login_status INTEGER, login_tty TEXT, login_type TEXT, checksum TEXT, PRIMARY KEY (user_name) ) WITHOUT ROWID;user_name为主键三组语义簇值得注意账户基本属性名称/主目录/组/Shell、密码策略与认证跟踪最近改密时间、过期日期、哈希算法、最大/最小改密间隔、失败认证次数与时间戳、登录会话信息login_status、login_tty、login_type、process_pid/host_ip可定位当前登录来自哪台主机哪个进程。系统组dbsync_groupsCREATE TABLE dbsync_groups ( group_id BIGINT, group_name TEXT, group_description TEXT, group_id_signed BIGINT, group_uuid TEXT, group_is_hidden INTEGER, group_users TEXT, checksum TEXT, PRIMARY KEY (group_name) ) WITHOUT ROWID;group_name为主键group_users为逗号分隔的组成员列表group_id_signed用于处理 32 位无符号 ID 在 64 位有符号列中的溢出表示Windows SID 场景常见。系统服务dbsync_services存储服务配置与运行时状态同样覆盖 POSIX 与 Windows 服务语义CREATE TABLE dbsync_services ( service_id TEXT, service_name TEXT, service_description TEXT, service_type TEXT, service_state TEXT, service_sub_state TEXT, service_enabled TEXT, service_start_type TEXT, service_restart TEXT, service_frequency BIGINT, service_starts_on_mount INTEGER, service_starts_on_path_modified TEXT, service_starts_on_not_empty_directory TEXT, service_inetd_compatibility INTEGER, process_pid BIGINT, process_executable TEXT, process_args TEXT, process_user_name TEXT, process_group_name TEXT, process_working_dir TEXT, process_root_dir TEXT, file_path TEXT, service_address TEXT, log_file_path TEXT, error_log_file_path TEXT, service_exit_code INTEGER, service_win32_exit_code INTEGER, service_following TEXT, service_object_path TEXT, service_target_ephemeral_id BIGINT, service_target_type TEXT, service_target_address TEXT, checksum TEXT, PRIMARY KEY (service_id, file_path) ) WITHOUT ROWID;复合主键(service_id, file_path)process_*字段簇记录服务运行实例执行文件、运行用户/组、工作目录service_win32_exit_code等字段为 Windows 专用POSIX 侧则通过service_type如 inotify 触发的mount/path_modified类型表达。浏览器扩展dbsync_browser_extensions跨浏览器、跨用户档案存储扩展信息CREATE TABLE dbsync_browser_extensions ( browser_name TEXT, user_id TEXT, package_name TEXT, package_id TEXT, package_version TEXT, package_description TEXT, package_vendor TEXT, package_build_version TEXT, package_path TEXT, browser_profile_name TEXT, browser_profile_path TEXT, package_reference TEXT, package_permissions TEXT, package_type TEXT, package_enabled INTEGER, package_visible INTEGER, package_autoupdate INTEGER, package_persistent INTEGER, package_from_webstore INTEGER, browser_profile_referenced INTEGER, package_installed TEXT, file_hash_sha256 TEXT, checksum TEXT, PRIMARY KEY (browser_name,user_id,browser_profile_name,package_name,package_version) ) WITHOUT ROWID;复合主键(browser_name, user_id, browser_profile_name, package_name, package_version)安全关键字段package_permissions权限清单、package_from_webstore是否来自商店、file_hash_sha256文件指纹——这三项直接服务于是否安装了可疑扩展类安全检测。Windows 热修复dbsync_hotfixesCREATE TABLE dbsync_hotfixes( hotfix_name TEXT, checksum TEXT, PRIMARY KEY (hotfix_name) ) WITHOUT ROWID;hotfix_name为主键存放 KB 编号或补丁标识这是典型的只存键名稀疏表补丁状态由漏洞扫描流程结合 KB 号进一步消费。表元数据table_metadata——恢复机制的状态机CREATE TABLE table_metadata ( table_name TEXT PRIMARY KEY, last_sync_time INTEGER DEFAULT 0 ) WITHOUT ROWID;table_name主键标识被跟踪的库存表last_sync_time最近一次完整性校验/恢复完成的 Unix 时间戳。该表支撑 Syscollector 的恢复机制当某表的integrity_interval到期后Syscollector 会1从该库存表计算 checksum-of-checksums2发送给 Manager 校验3校验完成后更新last_sync_time。源码印证syscollectorImp.cppgetMetadataValue/updateMetadataValue通过 DBSync 的selectRows与DBSyncTxn事务读写table_metadataupdateMetadataValue先读取全表、修改对应键、再整表回写recoveryIntervalHasEllapsed(tableName, integrityInterval)以当前时间 − last_sync_time ≥ integrity_interval判断是否触发校验syscollectorImp.cpp校验结果驱动同步模式选择源端计算final_checksum与 Manager 持有值比对日志明确区分两种分支——Checksum mismatch detected for index ... full sync required失配→全量同步与 Checksum valid for index ..., delta sync sufficient一致→增量同步syscollectorImp.cpp默认integrity_interval在代码中初始化为86400秒1 天syscollectorImp.cpp该值来自 Syscollector 配置 中的integrity_interval项文档中给出的示例值包括86400、3600、43200、172800等用于控制各表与 Manager 的完整性复核频率。源码与文档的差异sync、version 列与保留字转义文档给出的是面向使用者的逻辑模式而 syscollectorTablesDef.hpp 的实际 DDL 额外携带了同步协议需要的列读源码时需注意以下事实差异sync与version系统列除table_metadata外的每张业务表都包含sync INTEGER DEFAULT 0, version INTEGER NOT NULL DEFAULT 1sync标记行的同步状态供增量/延迟清理逻辑使用version是文档/数据版本列。文档中省略了这两列实际建库时以源码定义为准。SQLite 保留字处理dbsync_packages与dbsync_browser_extensions的实际列名是version_/package_version_对应 PK 为(name, version_, architecture, type, path)与(browser_name, user_id, browser_profile_path, package_name, package_version_)因为version已被系统列占用同时规避 SQLite 保留字冲突。对外WCS/indexer呈现时仍写作version。类型与字段细节dbsync_processes.start实际为TEXTsyscollectorTablesDef.hppdbsync_users中user_created、user_last_login、user_auth_failed_timestamp为TEXTuser_password_last_change为BIGINTtable_metadata的实际定义为last_sync_time INTEGER NOT NULL无DEFAULT 0syscollectorTablesDef.hpp。变更抑制机制syscollectorImp.cpp 中维护了从 DBSync diff 中排除的单调计数器集合——对流量统计这类只会增长、不代表真实变更的计数器字段DBSync 的 ignore 逻辑只在这些字段是唯一变化项时抑制 diff 回调从而避免端口/网卡流量统计触发无意义的 modified 事件。这些差异不影响文档 DDL 的参考价值但在写 SQL 查询本地库存库、或调试同步行为时应以 syscollectorTablesDef.hpp 的常量定义为准。校验与变更检测checksum 字段的实现每张表都带checksum列且行级 checksum 由行 JSON 的 MD5 计算得到——syscollectorImp.cpp 中getItemChecksum对item.dump()的完整序列化内容做HashData哈希并转十六进制。扫描结果入库前还会经sanitizeJsonValue递归修剪字符串空白保证同一物理状态产生稳定 hash。整表级则通过前述checksum-of-checksums与 Manager 比对决定触发增量delta还是全量full同步——这正是table_metadata.last_sync_time与integrity_interval配置共同构成的一致性保障闭环。小结Syscollector 的数据库架构可以概括为三层本地持久层13 张dbsync_*表 table_metadata全部WITHOUT ROWID、主键即业务标识、行级checksumsync/version系统列同步层INDEX_MAP/AGENTD_TO_INDEX_MAP将本地表与 agentd 上报名映射到wazuh-states-inventory-*同步索引integrity_interval到期的 checksum 比对决定增量或全量同步索引层src/external/indexer-plugins下的inventory-*.jsonWCS 模式定义发往 Wazuh indexer 的标准字段格式。进一步阅读建议configuration.mdintegrity_interval、扫描频率等参数、events.md各表数据对应的告警/事件格式、architecture.md模块整体架构与 api-reference.md查询接口源码入口为 syscollectorImp.cpp单元测试见 syscollectorImp_test.cpp。【免费下载链接】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），仅供参考