Wazuh Remoted 模块：Agent 通信网关、状态无关元数据富化与 x-wev1 事件协议详解

Wazuh Remoted 模块Agent 通信网关、状态无关元数据富化与 x-wev1 事件协议详解【免费下载链接】wazuhWazuh - The Open Source Security Platform. Unified XDR and SIEM protection for endpoints and cloud workloads.项目地址: https://gitcode.com/GitHub_Trending/wa/wazuh本文以 Wazuh 仓库中remoted模块的参考文档为主体系统讲解 remoted 作为 Agent 与 Manager 之间通信网关的完整职责从 TCP/UDP 多协议接入、基于 Agent Key 的认证与消息路由、无状态元数据Stateless Metadata富化机制到 remoted 向分析引擎转发事件所使用的x-wev1事件封装协议。读完本文你将能够理解 remoted 的端到端数据流、按 Agent 数量与事件速率对队列/线程参数进行调优并看懂 remoted 与 analysisd 之间的批量事件线格式wire format。1. remoted 模块定位remoted模块负责管理 Wazuh Agent 与 Manager 之间的安全通信承担 Agent 连接建立、认证、消息路由以及事件富化enrichment。它是Manager 端专属模块Manager-only也是所有 Agent 通信的主入口primary entry point。其核心工作可以概括为六步见 模块概览接收 Agent 消息通过 TCP 或 UDP 连接认证与校验使用 Agent Key 对消息进行身份认证与完整性校验提取元数据从 Agent 的 keep-alive 控制消息中解析元数据富化事件用 Agent 与主机元数据为事件补充上下文转发事件把富化后的事件送往分析引擎analysisd进行规则评估管理分组负责 Agent 分组group分配与配置同步。关键特性多协议支持同时支持 TCP 与 UDP 通信协议状态无关的元数据富化自动为 Agent 事件补充元数据使 analysisd 无需自行维护 Agent 状态Agent Keep-Alive 处理监控并跟踪 Agent 连接状态事件批处理Batching高性能的事件聚合与转发分组管理动态的 Agent 分组分配与配置下发。协作模块wazuh-manager-db存储 Agent 信息与连接状态wazuh-manager-analysisd消费富化后的事件进行规则评估agent-upgrade处理 Agent 更新通知inventory-sync同步 Agent 资产inventory数据。2. 高层架构与数据流从 架构文档 可知remoted 内部由以下核心组件协作Network Listener (TCP/UDP) ──▶ Message Handler (Threads) ──▶ Metadata Database (OSHash) │ │ │ ┌─────────────▼─────────────┐ │ │ Control Message Queue │ │ │ (Indexed) │ │ └─────────────┬─────────────┘ │ │ │ ┌──────────────▼──────────────┐ │ │ Control Msg Processor │──▶ wazuh-db (Agent Info) │ │ (Threads) │ │ └─────────────────────────────┘ │ └──────────────▶ Event Queue (Round-Robin) │ ┌──────────▼───────────┐ │ Event Batch │ ◀── Metadata Database (Enrichment) │ Dispatcher (Thread) │ └──────────┬───────────┘ │ ┌──────▼───────────┐ │ HTTP Client │ │ (Unix Socket) │ └──────┬───────────┘ │ ┌───────▼────────┐ │ Analysisd │ │ /events/ │ │ enriched │ └────────────────┘核心组件说明组件职责Network Listener处理来自 Agent 的入站连接默认 TCP 端口1514或 UDPMessage Handler解密AES、校验消息完整性与 Agent 身份、分类消息类型控制消息 vs 事件消息Metadata Database以 Agent ID 为索引的内存哈希表OSHash线程安全读写锁存储 Agent 名称、版本、OS 细节、分组、主机名Event Queue Dispatcher环形队列Round-Robin缓冲来自所有 Agent 的事件Dispatcher 线程把事件分批并富化元数据再通过 HTTP POST 送往 analysisdHTTP Client通过 Unix 域套接字向 analysisd 转发富化后的事件批次消息类型是理解 remoted 分类逻辑的关键控制消息Control Messages前缀#!-Keep-alive、startup、shutdown事件消息Event Messages日志数据、文件完整性、系统信息。数据流Data FlowAgent 发送事件 → Network Listener → 解密并校验 → 消息分类 · 控制消息 → 解析 Keep-Alive → 更新元数据缓存 → 更新 wazuh-manager-db · 事件消息 → Event Queue → 分批并用元数据富化 → HTTP POST 到 analysisd3. 状态无关元数据富化Stateless Metadata这是 remoted 在 Wazuh 5.0 中最关键的架构演进之一。据 状态无关元数据文档remoted 会在把事件转发给 analysisd之前为每个事件附加 Agent 元数据身份、OS、分组从而让 analysisd 不再需要自行维护 Agent 状态提升了可扩展性与可靠性。工作流程Agent 发送携带元数据JSON的 keep-aliveremoted 把元数据缓存在线程安全的哈希表中Agent 发送事件remoted 用缓存的元数据头header富化事件通过x-wev1协议转发给 analysisd。分组变更的自动传播API 更新 Agent 分组Manager 在下一个 keep-alive 响应中通知 AgentAgent 发送更新后的 keep-alive之后的事件即携带新分组。传播时间最长可达 60 秒。源码佐证元数据缓存的过期清理在 agent_metadata_db.c 中调用agent_meta_cleanup_expired(enrich_cache_expire_time, queue)与下文remoted.enrich_cache_expire_time参数一一对应配置项batch_events_capacity、enrich_cache_expire_time等均在 remoted.h 中声明为全局变量并在 config.c 中通过getDefine_Int_default(...)从内部选项文件解析。性能特征据文档内存约每 Agent 500–1000 字节哈希表默认 2048 个桶超过 20K Agent 需增大批处理每个批次只生成一次 header。4. x-wev1 事件协议wire format据 事件协议规范Wazuh Event Protocol v1x-wev1定义了 remoted 向 analysisd 传输富化事件的格式确保每个事件都携带完整的 Agent 元数据以支持无状态处理。协议名Wazuh Event Protocol v1Content-Typeapplication/x-wev1版本1.0Wazuh 5.0传输向 Unix 套接字发送 HTTP POST批量结构BatchH JSON_HEADERLF E EVENT_1LF E EVENT_2LFH 头部行JSON 元数据每批次一次位于首行E 事件行原始事件数据LF 换行符0x0A。头部 JSON 遵循 Elastic Common SchemaECS字段如下节选字段类型必填说明示例wazuh.agent.idstring是Agent 数字 ID001wazuh.agent.namestring否Agent 名称web-server-01wazuh.agent.versionstring否Agent 版本v5.0.0wazuh.agent.groupsarray[string]否Agent 分组[web,production]wazuh.agent.host.hostnamestring否主机名web-server-01wazuh.agent.host.os.namestring否OS 名称Ubuntuwazuh.cluster.namestring否集群名称productionwazuh.cluster.nodestring否Manager 节点master-node规则每个批次恰有一个 header首行JSON 必须紧凑无换行UTF-8 编码。完整批量示例POST /events/enriched HTTP/1.1 Host: localhost Content-Type: application/x-wev1 Content-Length: 512 User-Agent: wazuh-manager-remoted/1.0 Connection: keep-alive H {agent:{id:001,name:web-server-01,version:v5.0.0,groups:[web,production],host:{architecture:x86_64,hostname:web-server-01,os:{name:Ubuntu,version:22.04,platform:ubuntu,type:linux}}},wazuh:{cluster:{name:production,node:master-node}}} E {timestamp:2026-01-05T10:00:00.000Z,log:sshd[1234]: Connection from 192.168.1.100 port 54321} E {timestamp:2026-01-05T10:00:01.123Z,log:sshd[1234]: Accepted publickey for admin from 192.168.1.100}源码级实现细节从 secure.c 的实现可以印证并补充协议文档发送配置uhttp_options_t中content_type明确为application/x-wev1url为http://localhost/events/enricheduser_agent为wazuh-manager-remoted/1.0unix_socket_path指向 analysisd 的 Unix 套接字宏ANLSYS_ENRICH_SOCK事件封装在rr_collect_one中完成先确保 body 顶部有 headerappend_header再对每个事件追加E 前缀、缩进负载与\n。源码注释特别指出多行负载的续行采用空格缩进space-indented以避免事件内容内部出现误匹配的\nE 分隔符——这是协议解析健壮性的关键细节值得在自研对接时特别注意分发线程dispach_events_thread对 analysisd 的连接失败采用带退避的熔断circuit breaker失败时按指数退避0.5s…封顶约 30s重建客户端并在离线期间排水丢弃当轮事件以避免忙等。解析要点据协议文档按\n切分检查首字符H或E从第 2 个字符后提取负载。错误处理400批量格式错误413批量过大需拆分重试5xx带退避重试。性能建议每批 100–500 个事件以获得最佳吞吐且每批只生成一次 header。安全方面因走 Unix 套接字不暴露到网络套接字权限建议wazuh-manager:wazuh-manager 0660。5. 配置参考remoted 的配置分两部分主配置XMLremote段与内部选项remoted.*前缀。据 配置文档。5.1 主配置配置文件/var/wazuh-manager/etc/wazuh-manager.confXML 段remote适用Manager-only内部选项前缀remoted.*参数默认值允许值说明port15141–65535Agent 连接监听端口protocoltcptcp、udp、tcp,udp接受的通信协议TCP 推荐用于可靠传输queue_size131072正整数入站消息队列大小262144会产生告警allow_higher_versionsnoyes/no接受比 Manager 版本更高的 Agent 连接升级 Agent 先于 Manager 时开启ipv6noyes/no启用 IPv6 支持local_ip所有接口合法 IPv4/IPv6绑定到特定本地 IPrids_closing_time3005 分钟带s/m/h/d后缀的时间值Agent 断开后会话 IDRIDs的缓存保留时长connection_overtake_time600–3600秒允许新连接顶替同 ID 旧连接的等待时间0禁用保护5.2 内部选项配置文件/var/wazuh-manager/etc/wazuh-manager-internal-options.conf前缀remoted.*。以下参数均已在 config.c 中通过getDefine_Int_default解析源码中给出的默认值与取值范围可直接印证文档内部选项默认值源码确认的范围/说明remoted.debug00关闭、1基础、2详细排障用日志量大remoted.control_msg_queue_size16384源码范围4096–1048576大 Agent 数增大如32768对应 10K Agentremoted.batch_events_capacity131072源码范围0–1048576高事件速率增大如262144对应 50K 事件/秒remoted.enrich_cache_expire_time300源码范围60–86400秒瞬态 Agent 用300稳定 Agent 用600–1800remoted.worker_pool4处理 Agent 消息的工作线程数高吞吐可调至8remoted.sender_pool8向引擎转发事件的发送线程数高吞吐可调至16remoted.queue_max_bytes6710886464 MiB输入队列字节上限0表示不限remoted.batch_events_max_bytes3355443232 MiB事件队列字节上限0表示不限remoted.keyupdate_interval10重载 Agent Key 文件的间隔秒remoted.rlimit_nofile458752最大打开文件描述符数约支持 ~200K 并发连接remoted.state_interval5写统计状态文件的间隔秒0禁用remoted.recv_timeout1接收 Agent 数据超时秒remoted.tcp_keepidle/tcp_keepintvl/tcp_keepcnt30/10/3TCP 保活死连接判定 keepidle (keepintvl × keepcnt)remoted.merge_sharedyes合并 Agent 共享配置文件排障时可禁用remoted.pass_empty_keyfileyes允许client.keys为空时启动生产环境建议禁用remoted.router_forwarding_disabledno禁向 router 组件转发独立 Manager 模式置yesremoted.verify_msg_idno校验消息 ID 序列以检测篡改/重放remoted.disk_storageno磁盘持久化事件队列跨重启其余还有remoted.receive_chunk、remoted.send_chunk、remoted.send_buffer_size、remoted.buffer_relax、remoted.request_pool、remoted.request_timeout、remoted.response_timeout、remoted.request_rto_sec、remoted.request_rto_msec、remoted.max_attempts、remoted.shared_reload、remoted.batch_events_per_agent_capacity、remoted.recv_counter_flush、remoted.comp_average_printout等完整参数见 配置文档。5.3 典型配置示例默认配置wazuh_config remote port1514/port protocoltcp/protocol queue_size131072/queue_size agents allow_higher_versionsno/allow_higher_versions /agents /remote /wazuh_config大型部署10K Agent——主配置queue_size提至262144配合内部选项remoted.control_msg_queue_size32768 remoted.keyupdate_interval30 remoted.rlimit_nofile131072高吞吐50K 事件/秒remoted.control_msg_queue_size32768 remoted.batch_events_capacity262144 remoted.worker_pool8 remoted.sender_pool16低内存环境remoted.control_msg_queue_size4096 remoted.batch_events_capacity32768 remoted.worker_pool2 remoted.sender_pool4瞬态 Agent短生命周期与稳定长驻 Agent的区别主要在remoted.enrich_cache_expire_time瞬态300稳定1800。按规模的队列建议据文档规模control_msg_queue_sizebatch_events_capacity小型1K Agent409632768中型1K–10K16384131072大型10K327682621445.4 队列字节上限remoted.queue_max_bytes与remoted.batch_events_max_bytes从字节总量角度封顶队列内存与事件数上限相互独立任一上限触发都会丢弃事件。达到上限时的行为单个事件超过上限会被立即丢弃使总量超上限的事件会被丢弃直到腾出空间被丢弃事件与队列满共用同一discarded_count计数器在状态文件中告警日志最多每 5 秒打印一次避免日志刷屏1–1023字节的取值在启动时会被拒绝大概率是配置错误设为0可回退为仅按事件数限流。6. 监控与排障启用统计在内部选项文件中设置remoted.state_interval5然后查看cat /var/wazuh-manager/var/run/wazuh-manager-remoted.state grep discarded_count /var/wazuh-manager/var/run/wazuh-manager-remoted.state启用调试日志设置remoted.debug2然后tail -f /var/wazuh-manager/logs/wazuh-manager.log | grep remoted监控重点是队列深度与discarded_count被丢弃事件数用于判断是否需要根据事件速率上调batch_events_capacity或字节上限。7. 小结remoted是 Wazuh 中 Agent 通信的枢纽它把接入—认证—元数据富化—批量转发四件事串成一条无状态、可水平扩展的流水线。理解它的价值在于架构层面无状态元数据富化让 analysisd 无需维护 Agent 状态提升可扩展性与可靠性协议层面x-wev1批量封装H头 E事件行 空格缩进续行是 remoted 与 analysisd 之间约定的稳定线格式调优层面control_msg_queue_size、batch_events_capacity、worker_pool、sender_pool、字节上限与enrich_cache_expire_time共同决定了在大规模 Agent 数与高事件速率下的吞吐与内存占用。本文所有配置默认值与取值范围均已在 config.c 中得到源码级印证事件封装逻辑见 secure.c元数据缓存清理见 agent_metadata_db.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），仅供参考