Wazuh Agent Info 模块配置完全指南深入解析agent-info元数据采集与同步调优【免费下载链接】wazuhWazuh - The Open Source Security Platform. Unified XDR and SIEM protection for endpoints and cloud workloads.项目地址: https://gitcode.com/GitHub_Trending/wa/wazuhAgent Infoagent_info是 Wazuh 中负责采集、持久化并同步 Agent 身份与元数据系统信息、网络配置、组归属等的核心模块它同时运行在 Manager 与 Agent 上并为 SCA、Syscollector、FIM 等模块提供统一的 Agent 状态视图。本文以官方配置参考文档 configuration.md 为主体结合仓库内 C/C 源码与测试用例完整讲解agent-info配置段的每个参数、五类典型配置示例、元数据采集流程、模块协调同步协议以及故障排查与性能调优方法。读完本文你将能够根据实际部署环境动态云环境、低资源主机、高延迟网络精准配置 agent_info 模块。一、agent_info 模块在 Wazuh 中的角色在深入配置之前先明确该模块的定位。根据 Agent Info Module 概述 与 架构文档agent_info是 Agent 身份与组信息的权威数据源source of truth元数据采集定期收集 Agent ID、名称、版本、操作系统信息与组归属本地持久化将元数据存入本地 SQLite 数据库agent_metadata、agent_groups、db_metadata三张表从而支持跨重启的状态比对与变更检测变更检测将每次扫描结果与库中状态比对在发生插入、修改、删除时生成事件模块协调协议当 Agent 组等关键元数据发生变化时编排 FIM、SCA、Syscollector 的同步流程保证配置变更在全系统范围内一致、可靠地生效可靠同步通过AgentSyncProtocol确保元数据更新可靠地传达给 Manager。从源码结构看模块的实现分为两层C 层封装 wm_agent_info.c 负责 XML 配置解析与模块生命周期C 核心实现AgentInfoImpl位于 src/wazuh_modules/agent_info/其中 agent_info.cpp 提供了对外 C 接口如agent_info_start、agent_info_stop、agent_info_parse_response。二、配置文件与 XML 段结构Agent Info 模块的所有配置都位于 Wazuh 主配置文件配置文件/var/ossec/etc/ossec.confXML 段agent-info模块归属Agent 专属模块在 Manager 与 Agent 上的配置方式完全相同内部选项无不需要修改internal_options.conf中的任何条目一个完整的agent-info配置段结构如下agent-info interval60/interval integrity_interval86400/integrity_interval synchronization enabledyes/enabled sync_end_delay1s/sync_end_delay response_timeout30s/response_timeout retries5/retries max_eps50/max_eps /synchronization /agent-info在解析链路上wmodules-config.c 识别到WM_AGENT_INFO_CONTEXT.name即agent-info节点后调用wm_agent_info_read()随后 wm_agent_info.c 中的wm_agent_info_parse_synchronization()逐项解析synchronization的子节点并将结果填充进wm_agent_info_t结构体。三、配置参数详解3.1interval两次周期性元数据扫描之间的时间间隔秒。项目说明默认值60允许值正整数单位秒说明数值越小元数据新鲜度越高但资源消耗越大3.2integrity_interval完整性检查的时间间隔用于验证 Agent 状态与 Manager 是否保持一致。项目说明默认值8640024 小时允许值正整数单位秒说明周期性校验可确保 Agent 与 Manager 之间的状态一致3.3enabledsynchronization子项启用或禁用模块的协调与同步功能。项目说明默认值yes允许值yes、no父节点synchronization说明控制模块是否参与与其他模块的协调同步3.4sync_end_delaysynchronization子项发送同步结束消息之前的延迟时间。项目说明默认值1s允许值带后缀的时间字符串s秒、m分钟、h小时、d天父节点synchronization说明在发出同步完成信号前留出缓冲时间3.5response_timeoutsynchronization子项协调过程中等待其他模块响应的超时时间。项目说明默认值30s允许值带后缀的时间字符串s、m、h、d父节点synchronization说明控制等待协调响应的最长时间3.6retriessynchronization子项协调命令失败时的重试次数。项目说明默认值5见下方源码差异说明允许值正整数父节点synchronization说明防止瞬时故障阻断同步流程3.7max_epssynchronization子项同步期间每秒最多发送的事件数。项目说明默认值50允许值正整数父节点synchronization说明限速可防止批量更新时压垮接收端Manager四、源码中的默认值与校验逻辑配置参考文档给出了各参数的默认值而从当前仓库源码 wm_agent_info.c 可以看到模块在 C 层的默认值设定// Set default configuration values agent_info-interval 60; // Delta updates every 60 seconds agent_info-integrity_interval 86400; // Integrity check every 24 hours (86400 seconds) // Database synchronization config values agent_info-sync.enable_synchronization 1; agent_info-sync.sync_end_delay 1; agent_info-sync.sync_response_timeout 30; agent_info-sync.sync_retries 3; agent_info-sync.sync_max_eps 50;值得注意的差异配置参考文档记录的retries默认值为5但当前源码中 C 层默认值实际为3agent_info-sync.sync_retries 3;。在实际部署中最终生效值以ossec.conf中显式配置为准因此建议在配置文件中显式写明该参数避免歧义。此外源码还实现了超出文档描述的取值范围校验见 wm_agent_info.c 与同步子节点解析逻辑参数校验逻辑越界处理interval必须在60到864001 天之间记录 WARNING保留默认值integrity_interval必须在601 分钟到6048007 天之间记录 WARNING保留默认值retries必须在0到100之间记录 WARNINGmax_eps必须在0到1000000之间记录 WARNINGsync_end_delay/response_timeout通过w_parse_time()解析支持s/m/h/d后缀解析失败时记录 WARNINGenabled通过w_parse_bool()解析仅接受yes/no非法值记录 WARNING这些解析后的配置值最终通过agent_info_start()传入核心实现setSyncParameters()注入同步参数start(interval, integrity_interval)启动主循环见 agent_info.cpp。五、配置示例官方文档提供了五类典型场景的完整配置以下全部保留并补充说明适用场景。5.1 默认配置大多数部署agent-info interval60/interval integrity_interval86400/integrity_interval synchronization enabledyes/enabled sync_end_delay1s/sync_end_delay response_timeout30s/response_timeout retries5/retries max_eps50/max_eps /synchronization /agent-info5.2 高频扫描动态环境适用于云环境等元数据频繁变化的场景缩短扫描间隔并提高同步吞吐agent-info interval30/interval integrity_interval3600/integrity_interval synchronization enabledyes/enabled sync_end_delay1s/sync_end_delay response_timeout30s/response_timeout retries5/retries max_eps100/max_eps /synchronization /agent-info注意interval在源码层校验的最小值是60秒若配置小于 60 会被拒绝并回退默认值因此实际生效的“高频”下限为 60 秒。5.3 低资源系统降低扫描频率与同步速率最小化资源占用agent-info interval300/interval integrity_interval86400/integrity_interval synchronization enabledyes/enabled sync_end_delay2s/sync_end_delay response_timeout60s/response_timeout retries3/retries max_eps25/max_eps /synchronization /agent-info5.4 不可靠网络高延迟 / 丢包增大超时与重试次数容忍网络抖动agent-info interval60/interval integrity_interval86400/integrity_interval synchronization enabledyes/enabled sync_end_delay5s/sync_end_delay response_timeout120s/response_timeout retries10/retries max_eps25/max_eps /synchronization /agent-info5.5 禁用同步协调仅保留元数据采集不参与模块协调agent-info interval60/interval integrity_interval86400/integrity_interval synchronization enabledno/enabled /synchronization /agent-info注意禁用同步协调后Agent 组变更将不会触发与其他模块的一致性协调请仅在明确知晓后果的场景下使用。六、元数据采集采集内容、数据源与流程6.1 采集的信息Agent Info 模块采集四类元数据系统信息操作系统名称、版本、架构、主机名网络配置IP 地址、MAC 地址、网络接口Agent 配置组归属、标签、配置哈希资源使用情况CPU、内存、磁盘空间取决于配置。6.2 数据来源源码级根据架构文档与 agent_info_impl.hpp 中readClientKeys()、readAgentGroups()等私有方法的声明模块从三个数据源采集信息数据源提供内容SysInfo操作系统详细信息OS 名称、版本、架构、主机名client.keys文件Agent 的唯一 ID 与名称merged.mg文件Agent 的组归属列表6.3 采集流程官方文档定义的六步采集流程如下周期性扫描模块依据interval设置定时唤醒数据收集采集当前系统与 Agent 元数据变更检测与上一次扫描结果比对检测变化同步协调若检测到变更发起与其他模块的协调更新 Manager将更新后的元数据发送给 Manager仅 Agent 端完整性检查依据integrity_interval定期校验一致性。6.4 本地持久化SQLite 三张表模块通过共享组件DBSync将数据持久化到本地 SQLite 数据库。从 database-schema.md 可知数据库文件位于queue/agent_info/db/agent_info.db该路径定义在 agent_info.cpp 的AGENT_INFO_DB_DISK_PATH宏中包含三张表agent_metadata存储 Agent 身份与 OS 信息单行周期性更新字段包括agent_id、agent_name、agent_version、host_architecture、host_hostname、host_os_name、host_os_type、host_os_platform、host_os_version并映射到 ECS 字段如agent.id、host.os.nameagent_groups每行代表一条组归属记录主键为(agent_id, group_name)外键级联删除db_metadata模块内部运行状态表单行id 1记录should_sync_metadata、should_sync_groups同步标志以及last_metadata_integrity、last_groups_integrity完整性检查时间戳和首次运行标志。正是这套持久化机制使得模块在 Agent 重启后仍能基于历史状态进行变更检测而不是每次都做全量同步。七、同步协议与模块协调机制7.1 协调事件流程当 Agent 元数据发生变化如组分配、标签更新时模块按以下流程协调发起同步agent_info 模块检测到变更通知对端向其他模块发送协调消息等待响应在response_timeout时间内收集确认失败重试响应失败时最多重试retries次完成同步在sync_end_delay延迟后发送结束消息速率限制批量更新期间遵守max_eps限制。7.2 源码级协调协议从架构文档和 agent_info_impl.hpp 的coordinateModules()方法声明可以看出协调对象是FIM、SCA、Syscollector三个模块完整协调步骤为Pause向所有协调模块发送pause命令Flush指示每个模块冲刷待处理数据确保干净状态Get Version获取各模块当前同步版本号Calculate Set New Version计算新全局版本取最大值或最大值 1并设置到所有模块Synchronizeagent_info 将变更连同新版本号与受影响的模块索引列表发送给 ManagerResume向所有模块发送resume命令恢复正常运行。该协议保证与 Agent 组绑定的配置变更在整个系统内原子地生效。核心实现中coordinateModules()与pauseCoordinationModules()、calculateNewVersion()、queryModuleWithRetry()、resumePausedModules()等私有方法协同工作并通过AgentSyncProtocol实现与 Manager 的可靠消息投递initSyncProtocol()方法负责初始化。7.3 线程模型agent_info模块运行在单一主线程中start()内的主循环按interval休眠并周期性执行任务异步操作由模块协调协议处理——通过查询其他模块并在必要时轮询完成状态例如等待 FIM 完成 flush。相应地模块内部用互斥锁与条件变量保护同步标志m_shouldSyncMetadata、m_shouldSyncGroups与 DBSync 事务见头文件中的m_syncFlagsMutex、m_dbSyncMutex等成员。7.4 速率限制的意义max_eps用于防止“同步风暴”控制同步期间每秒最大事件数防止批量更新时压垮 Manager在大量 Agent 同时同步时尤其重要。从源码看max_eps的合法范围是0到1000000并通过setSyncParameters()传入同步协议实现作为事件发送的速率上限。八、性能调优指南8.1 扫描间隔的选择高频扫描30–60 秒适合动态云环境配置变更检测更快资源占用更高。标准扫描60–120 秒适合大多数部署默认推荐设置兼顾新鲜度与开销。低频扫描300 秒以上适合静态环境资源消耗最小变更检测更慢。8.2 完整性检查的选择频繁检查1–6 小时保证紧密一致性网络与处理开销更高。标准检查24 小时默认推荐设置在一致性与性能间取得平衡。低频检查48 小时以上适合稳定环境开销最小。九、故障排查9.1 Manager 上元数据不更新检查扫描间隔配置grep -A5 agent-info /var/ossec/etc/ossec.conf查看 agent-info 日志tail -f /var/ossec/logs/ossec.log | grep agent-info强制立即采集元数据重启 Agent 触发即时扫描# Restart agent to trigger immediate scan /var/ossec/bin/wazuh-control restart9.2 同步失败检查协调超时配置grep -A10 synchronization /var/ossec/etc/ossec.conf增大超时与重试次数synchronization response_timeout120s/response_timeout retries10/retries /synchronization9.3 资源占用过高降低扫描频率interval300/interval !-- 5 minutes --降低同步期间的事件速率synchronization max_eps25/max_eps /synchronization十、监控10.1 查看已采集的元数据在 Manager 上查询 Agent 信息# View agent system information /var/wazuh-manager/bin/wazuh-control info agent 001检查同步状态tail -f /var/ossec/logs/ossec.log | grep agent-info.*sync10.2 监控扫描活动# View metadata collection events tail -f /var/ossec/logs/ossec.log | grep agent-info.*scan十一、配置校验模块在启动时会执行以下校验布尔值确保布尔值只能是yes或no时间值校验时间格式支持s/m/h/d后缀与可接受范围整数值确保整数在有效范围内如interval60–86400、integrity_interval60–604800、retries0–100、max_eps0–1000000间隔约束验证interval与integrity_interval为正数。如果配置无效模块会记录警告并使用默认值若遇到严重错误模块将启动失败。这一行为可以在 wm_agent_info.c 的参数解析代码中直接看到每个越界值都会通过mwarn(XML_VALUEERR, ...)记录警告并跳过该值。十二、相关文档Agent Info 模块概述 — 模块功能与关键特性总览Agent Info 模块架构 — 组件构成、数据流与协调协议详解Agent Info 数据库 Schema — 三张 SQLite 表的字段与 ECS 映射Agent 配置参考 — 全部 Agent 配置项Manager 配置参考 — 全部 Manager 配置项核心源码wm_agent_info.c配置解析、agent_info.cppC 接口、agent_info_impl.hpp核心实现单元测试agent_info_impl/tests/含协调、完整性检查、DBSync、握手等测试用例可进一步验证本文所述的各行为【免费下载链接】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），仅供参考