Wazuh 客户端模块agentd完全指南连接管理、缓冲机制与防篡改配置解析【免费下载链接】wazuhWazuh - The Open Source Security Platform. Unified XDR and SIEM protection for endpoints and cloud workloads.项目地址: https://gitcode.com/GitHub_Trending/wa/wazuhWazuh 的客户端模块client module由守护进程wazuh-agentd实现是 Agent 与 Manager 之间通信的唯一通道它负责建立并维持安全连接、转发各模块采集的事件数据、接收集中式配置更新并在网络中断时进行本地消息缓冲。本文基于仓库文档 docs/ref/modules/client/README.md 与 docs/ref/modules/client/configuration.md并结合 src/client-agent 目录下的 C 源码实现系统讲解该模块的架构流程、client、client_buffer、anti_tampering三大 XML 配置段、内部选项internal options、服务管理与常见排障方法帮助读者完整掌握 agentd 的配置与工作原理。模块概览属性说明守护进程wazuh-agentd平台Linux、Windows、macOS、Unix类型仅 Agent 端Agent-only配置文件/var/ossec/etc/ossec.confLinux/Unix或C:\Program Files (x86)\ossec-agent\ossec.confWindowsXML 配置段client、client_buffer、anti_tampering内部选项前缀agent.*、monitord.*另有windows.*仅 Windows客户端模块承担的核心职责包括建立并维持与 Wazuh Manager 的安全连接将采集到的数据事件、资产清单、安全评估结果发送给 Manager接收并应用 Manager 下发的集中式配置更新当 Manager 不可达时在本地对消息进行缓冲buffering通过防篡改anti-tampering特性保护 Agent 的完整性支持自动注册auto-enrollment与密钥管理。Agent 侧默认配置模板位于 etc/ossec-agent.conf其中client段使用manageraddressIP/address/manager的经典写法client_buffer段默认queue_size为 5000、events_per_second为 600。架构与进程流程处理流程wazuh-agentd的完整生命周期可分为六个阶段启动Startup读取配置、校验地址并建立连接认证Authentication与 Manager 校验预共享密钥pre-shared key数据采集Data collectionsyscheck、sca、syscollector 等模块把事件写入本地队列agentd 从中读取传输Transmissionagentd 对事件进行压缩、加密并转发给 Manager缓冲Buffering若 Manager 不可达事件先进入本地环形缓冲区排队配置同步Configuration sync接收并应用集中式配置更新必要时自动重启 Agent。组件交互┌─────────────────────┐ │ Data Collection │ │ (syscheck, sca, │ │ syscollector...) │ └──────────┬──────────┘ │ Events本地队列 DEFAULTQUEUE ▼ ┌─────────────────────┐ │ agentd (client) │ │ - Compression │ │ - Encryption │ │ - Buffering │ └──────────┬──────────┘ │ 加密 TCP ▼ ┌─────────────────────┐ │ Wazuh Manager │ │ (remoted) │ └─────────────────────┘源码级实现印证从 src/client-agent 的源码结构可以还原上述流程的具体实现入口与命令行解析src/client-agent/src/main.c 中main()解析-V/-h/-d/-t/-f/-u/-g/-c等参数读取配置ClientConf(cfg)、校验服务器地址Validate_Address、Validate_IPv6_Link_Local_Interface随后调用AgentdStart()进入守护进程主循环。主循环与重连src/client-agent/src/agentd.c 中的AgentdStart()完成降权、读密钥OS_ReadKeys、打开本地队列StartMQ(DEFAULTQUEUE, READ, 0)、创建 PID 文件、启动缓冲派发线程与日志轮转线程然后进入select()监控循环一旦 socket 失效agt-sock 0即调用start_agent(0)自动重连并把状态标记为非活跃GA_STATUS_NACTIVE。事件转发src/client-agent/src/event-forward.c 中的EventForward()从本地消息队列读取事件若缓冲开启则写入环形缓冲区buffer_append否则直接调用send_msg发送。加密发送src/client-agent/src/sendmsg.c 中的send_msg()通过CreateSecMSG对消息做安全封装再经OS_SendSecureTCP发送对EPIPE、ECONNRESET、ETIMEDOUT、EAGAIN、ECONNREFUSED、ENOTCONN等错误会判定 socket 失效并关闭触发主循环重连。Keep-alive 通知src/client-agent/src/notify.c 中根据agt-notify_time控制通知频率并在每次 keep-alive 时重新计算merged.mg共享文件哈希、构造 JSON keepalive 消息。握手与模块限流src/client-agent/src/start_agent.c 中的agent_handshake_to_server()在重连接时与 Manager 完成握手解析 FIM、syscollector、SCA 等模块的限流参数module_limits并写入agent_cluster_name、agent_cluster_node、agent_agent_groups等握手全局信息。客户端连接配置clientclient段配置 Agent 与 Wazuh Manager 的连接参数是 agentd 最核心的配置。server 块管理端Manager服务器配置块可定义多个server块实现故障转移failover。子选项必填默认值允许值说明address是至少一个 server无合法 IPv4、IPv6 或主机名Manager 的 IP 或域名例如192.168.1.100、manager.example.com、::1port否15141-65535Manager 监听端口protocol否TCP—已废弃解析但忽略通信协议硬编码为 TCPmax_retries否5正整数连接重试次数上限超过后切换到下一个 server仅在配置多个 server 时生效retry_interval否10正整数秒对同一 server 重试之间的等待时间interface_index否自动选择正整数接口索引号绑定指定网络接口与 Manager 通信平台相关Linux 可用ip link或ifconfig查询接口索引兼容性说明Agent 默认配置模板 etc/ossec-agent.conf 中仍使用经典的manageraddressIP/address/manager写法源码 src/config/src/client-config.c 会将manager作为“legacy server”处理并补齐默认max_retries/retry_interval二者可混用。其他client选项选项默认值允许值说明ip_update_interval0禁用0或正整数秒周期性向 Manager 上报 Agent IP 的间隔设为3600等正数可启用0表示禁用。对应源码中agt-main_ip_update_intervalconfig-profile无逗号分隔的 profile 名不含空格例如webserver,production,linux配合集中式配置agent.conf使用Manager 据此匹配下发目标notify_time60正整数秒最小10Agent 向 Manager 发送 keep-alive 通知的间隔Manager 在超过 3 倍该间隔未收到通知后判定 Agent 离线src/client-agent/src/main.c 中同时保证time-reconnect不小于notify_time的 3 倍time-reconnect60正整数秒最小1连接丢失后等待多久再尝试重连auto_restartyesyes/no收到 Manager 的集中式配置更新后是否自动重启 Agent集中式更新要生效必须为yescrypto_methodAES—已废弃解析但忽略加密方式硬编码为 AES源码 src/config/src/client-config.c 中明确记录了上述两个废弃选项的行为解析器在遇到protocol时打印Ignoring the protocol option. Switching to TCP.遇到crypto_method时打印Ignoring the crypto_method option. Switching to AES.随后继续执行因此老配置中的这两个标签可以安全保留但实际不会改变行为。enrollment 块自动注册enrollment是client下的可选子块配置 Agent 的自动注册行为。子选项默认值允许值说明enabledyesyes/no是否启用自动注册manager_address取serveraddressIPv4 / IPv6 / 主机名注册使用的 Manager 地址可与数据连接地址不同port15151-65535注册端口对应 Manager 端 authd 服务agent_name系统主机名任意字符串注册时使用的自定义 Agent 名称groupsdefault逗号分隔的组名注册时分配给 Agent 的组authorization_pass_path无合法文件路径注册授权密码文件的路径密码须与 Manager 端 authd 密码一致agent_address自动探测IPv4 / IPv6注册时使用的 Agent 自身 IP多网卡场景下覆盖自动探测结果ssl_cipher系统默认合法 OpenSSL cipher 字符串注册连接的 SSL/TLS 密码套件例如HIGH:!aNULL:!MD5server_ca_path无合法文件路径用于校验 Manager 证书的 CA 证书文件路径启用 SSL 校验时必填agent_certificate_path无合法文件路径双向 TLS 认证中 Agent 的客户端证书路径agent_key_path无合法文件路径双向 TLS 认证中 Agent 的私钥路径须与agent_certificate_path对应auto_methodnoyes/no启用后 Agent 自动选择最佳注册方式delay_after_enrollment20正整数秒最小1注册成功后延迟多久再开始正常上报给 Manager 处理新 Agent 的时间0非法解析器会拒绝use_source_ipnoyes/no使用 Agent 的源 IP 而非配置地址进行注册适合 NAT 场景interface_index自动选择正整数注册连接绑定的网络接口索引可用ip link/ifconfig查询从源码看自动注册还有一个联动行为src/client-agent/src/agentd.c 中当enrollment启用时即使本地没有有效密钥Agent 也不会直接退出OS_PassEmptyKeyfile而是进入注册流程只有禁用注册时才严格要求OS_CheckKeys()通过。此外 src/client-agent/src/config.c 显示注册连接的接收超时由内部选项agent.recv_timeout控制。客户端缓冲配置client_bufferclient_buffer段配置 Manager 不可达时的事件缓冲行为其防泛洪anti-flooding实现位于 src/client-agent/src/buffer.c。选项默认值允许值说明disablednoyes/no是否禁用缓冲no表示启用Manager 断连期间事件先入缓冲queue_size5000正整数最小1上限受系统内存约束缓冲的事件条数上限超过即丢弃新事件events_per_second500参考文档标注当前仓库 src/client-agent/src/config.c 初始化为600etc/ossec-agent.conf 同为600正整数最小1重连后每秒最多发送的事件数限速防止瞬间打满 Manager防泛洪状态机与内部联动缓冲模块内部使用一个环形缓冲区circular buffer并通过四个状态src/client-agent/include/agentd.h 中定义NORMAL / WARNING / FULL / FLOOD实现分级告警缓冲区使用率到达agent.warn_level默认 90%进入WARNING状态并记录告警日志缓冲区写满进入FULL状态若在agent.tolerance默认 15 秒内持续处于满状态则进入FLOOD泛洪状态使用率回落到agent.normal_level默认 70%以下时恢复NORMAL。每次状态切换不仅写入日志还会向本地消息队列投递一条event.dataset为wazuh-agent.buffer的状态事件见 src/client-agent/src/buffer.c可在日志分析中直接关联缓冲告警。生产环境建议把queue_size与磁盘/内存容量一起规划避免突发告警风暴时丢事件。防篡改配置anti_tamperinganti_tampering段用于防止 Agent 文件被未授权修改、防止 Agent 包被卸载。选项默认值允许值行为package_uninstallationyes文档标注当前仓库 src/client-agent/src/config.c 中 C 结构体默认初始化为false实际生效值以安装包模板为准yes/no启用后阻止apt remove、yum remove等包管理器卸载操作平台限制anti_tampering仅适用于 Linux/UnixWindows 与 macOS 上不可用源码中该配置仅在#ifndef WIN32分支读取见 src/client-agent/src/config.c 与 src/client-agent/include/agentd.h。重要若要禁用防篡改必须删除或注释掉整个anti_tampering块该块内部不存在disabled开关。卸载校验的实现防篡改的“卸载前校验”在 agentd 启动入口实现wazuh-agentd支持--uninstall-auth-login、--uninstall-auth-token、--uninstall-auth-host、--uninstall-ssl-verify四个长选项见 src/client-agent/src/main.c。当指定了 token 或 login 且给出 host 时进程直接调用package_uninstall_validation()src/client-agent/src/agentd.c向 Manager API 的/agents/uninstall发起 HTTPS 请求校验卸载权限HTTP 200 放行卸载、403 拒绝token 未提供时先用/security/user/authenticate?rawtrue换取令牌src/client-agent/src/agentd.c。内部选项Internal Options除 XML 配置外agentd 的行为还可通过内部选项文件调整。官方推荐修改/var/ossec/etc/local_internal_options.conf升级可保留不建议直接改/var/ossec/etc/internal_options.conf。仓库中的默认值见 etc/internal_options.conf本地覆盖模板见 etc/local_internal_options.conf。连接与网络# agentd 调试级别0无1基本2详细 agent.debug0 # 接收超时秒 agent.recv_timeout60 # 发送超时秒 agent.send_timeout30 # TCP keep-alive 空闲时间秒 agent.tcp_keepidle60 # TCP keep-alive 探测间隔秒 agent.tcp_keepintvl15 # TCP keep-alive 探测次数 agent.tcp_keepcnt4 # 请求最大重试次数 agent.max_attempts4 # 请求池大小 agent.request_pool1024 # 请求重传超时秒 agent.request_rto_sec1 # 请求重传超时毫秒 agent.request_rto_msec0 # 远程配置0禁用1启用 agent.remote_conf1 # 每秒事件数下限低于此值的 events_per_second 会被强制提升 agent.min_eps50 # 状态上报间隔秒 agent.state_interval5其中agent.min_eps与缓冲配置联动src/client-agent/src/config.c 在解析完配置后检查agt-events_persec min_eps时会把吞吐强制抬升到min_eps并打印警告Client buffer throughput too low。agent.remote_conf控制是否读取agent.conf的远程配置段src/client-agent/src/config.c。缓冲告警阈值# 缓冲使用率达到该百分比时进入告警默认 90 agent.warn_level90 # 缓冲使用率回落到该百分比以下视为恢复正常默认 70 agent.normal_level70 # 缓冲处于满状态达到该秒数后判定为泛洪默认 15 agent.tolerance15日志轮转# 压缩轮转日志0否1是 monitord.compress1 # 轮转日志保留天数 monitord.keep_log_days31 # 每日轮转时刻hh:mm 格式仓库默认 10 monitord.day_wait10 # 日志文件超过该大小MB即轮转0不限制仓库默认 512 monitord.size_rotate512 # 保留的每日轮转份数 monitord.daily_rotations12 # 启用自动日志轮转0否1是 monitord.rotate_log1说明参考文档 docs/ref/modules/client/configuration.md 对上述选项标注的示例默认值如agent.tcp_keepidle30、monitord.keep_log_days365、monitord.size_rotate0等与当前仓库 etc/internal_options.conf 中的实际值略有差异以当前仓库及安装版本随附的internal_options.conf为准。日志轮转由 agentd 在启动时按monitord.rotate_log决定是否创建轮转线程src/client-agent/src/agentd.c。配置示例以下示例均来自参考文档可直接复制并按需调整。基础客户端配置单 Managerclient server address10.0.0.10/address port1514/port protocoltcp/protocol /server config-profilewebserver,production/config-profile notify_time60/notify_time time-reconnect60/time-reconnect auto_restartyes/auto_restart crypto_methodaes/crypto_method /client故障转移配置多 Manager 高可用client server addressmanager1.example.com/address port1514/port protocoltcp/protocol max_retries3/max_retries /server server addressmanager2.example.com/address port1514/port protocoltcp/protocol max_retries3/max_retries /server server addressmanager3.example.com/address port1514/port protocoltcp/protocol max_retries3/max_retries /server notify_time30/notify_time time-reconnect30/time-reconnect /client自动注册配置client enrollment enabledyes/enabled manager_addressmanager.example.com/manager_address port1515/port agent_nameweb-server-prod-01/agent_name groupswebservers,production/groups authorization_pass_path/var/ossec/etc/authd.pass/authorization_pass_path /enrollment server addressmanager.example.com/address port1514/port protocoltcp/protocol /server /client高吞吐缓冲配置client_buffer disabledno/disabled queue_size50000/queue_size events_per_second1000/events_per_second /client_buffer防篡改配置仅 Linuxanti_tampering package_uninstallationyes/package_uninstallation /anti_tampering完整 Agent 配置示例ossec_config client server addressmanager1.example.com/address port1514/port protocoltcp/protocol max_retries5/max_retries /server server addressmanager2.example.com/address port1514/port protocoltcp/protocol max_retries5/max_retries /server config-profilewebserver,production,linux/config-profile notify_time60/notify_time time-reconnect60/time-reconnect auto_restartyes/auto_restart crypto_methodaes/crypto_method enrollment enabledyes/enabled manager_addressmanager1.example.com/manager_address port1515/port groupswebservers,production/groups /enrollment /client client_buffer disabledno/disabled queue_size10000/queue_size events_per_second600/events_per_second /client_buffer anti_tampering package_uninstallationyes/package_uninstallation /anti_tampering logging log_formatplain/log_format /logging /ossec_config服务管理启停服务Linuxsystemctl start wazuh-agent systemctl stop wazuh-agent systemctl status wazuh-agentWindowsPowerShell / CMDNET START WazuhSvc NET STOP WazuhSvc查看连接状态/var/ossec/bin/wazuh-control status输出中应能看到wazuh-agentd is running...即表示客户端守护进程正常。查看 Agent 信息/var/ossec/bin/wazuh-control info该命令展示 Agent ID、Manager 地址、连接状态与配置版本等信息。agentd 直接运行参数若需要直接调试守护进程本身例如不改服务文件的情况下验证配置wazuh-agentd支持以下命令行参数见 src/client-agent/src/main.c参数含义-V打印版本与许可证信息-h显示帮助-d调试模式可重复指定以提升调试级别-t仅测试配置读取并校验后退出不启动服务-f前台运行不守护化-u user指定运行用户默认ossec-g group指定运行组-c config指定配置文件默认ossec.conf另外wazuh-agentd收到SIGUSR1信号时会触发配置重载src/client-agent/src/agentd.c主循环在select()返回后重新读取缓冲配置并动态执行缓冲的启用、禁用或扩容src/client-agent/src/agentd.c无需重启进程即可调整queue_size。故障排查Agent 无法连接先校验配置/var/ossec/bin/wazuh-logtest-config再观察日志tail -f /var/ossec/logs/ossec.log常见原因Manager 地址或端口配置错误防火墙未放行 1514 端口TCPAgent 密钥未在 Manager 上注册client.keys缺失或失配Manager 未运行接受连接的remoted守护进程。缓冲溢出丢事件若因缓冲溢出导致事件被丢弃按以下顺序处理检查当前缓冲大小配置增大client_buffer中的queue_size若 Manager 可承受更高负载适当增大events_per_second确认网络链路稳定减少断连诱发的积压。同时可以结合 src/client-agent/src/buffer.c 的防泛洪状态机与agent.warn_level/agent.normal_level/agent.tolerance内部选项把告警阈值调到符合自身容量水位避免“满→泛洪→丢弃”的连锁反应。防篡改误报若防篡改频繁误报回顾近期 Agent 文件的合法变更如正常升级、脚本改动核对文件权限是否正确检查系统更新是否改动了 Agent 文件如需临时关闭验证删除或注释整个anti_tampering块注意块内没有disabled开关。已废弃选项汇总选项状态说明protocol已废弃解析但忽略通信固定使用 TCPcrypto_method已废弃解析但忽略加密固定使用 AESdisable-active-response已废弃静默空操作解析但无效主动响应行为由 active-response 模块配置active-responsedisabled控制建议从配置中移除force_reconnect_interval已废弃源码 src/config/src/client-config.c 中会打印Deprecated option force_reconnect_interval is not longer available.并忽略关联文档与深入阅读Client Configuration Reference完整的 client 配置参考本文第二大部分即基于此文档展开Remoted 模块文档 与 Remoted ConfigurationManager 端连接监听配置agentd 的对端Centralized Configuration基于组的集中式配置下发配合config-profile使用Agent ManagementAgent 管理、分组与注册相关流程Agent 默认配置模板安装后生成的默认ossec.conf参考内部选项默认值 与 本地覆盖模板agent.*、monitord.*内部选项的取值与注释核心源码src/client-agent/src/main.c入口、src/client-agent/src/agentd.c主循环与重连、src/client-agent/src/config.c配置读取、src/client-agent/src/buffer.c环形缓冲与防泛洪、src/client-agent/src/sendmsg.c加密发送、src/client-agent/src/event-forward.c事件转发、src/client-agent/src/start_agent.c握手与自动注册。【免费下载链接】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），仅供参考
