尧图网页设计 
Wazuh 5.x 自定义 Decoder 迁移指南从 XML 到 YAML 的完整改造实战【免费下载链接】wazuhWazuh - The Open Source Security Platform. Unified XDR and SIEM protection for endpoints and cloud workloads.项目地址: https://gitcode.com/GitHub_Trending/wa/wazuh导读Wazuh 5.x 将解码层从 4.x 的 XML 格式 decoder 全面迁移到基于 YAML 的声明式资产模型并引入全新的 logpar 结构化字段提取语言取代正则表达式。本文以官方迁移文档为主体结合引擎源码与 schema 定义系统讲解自定义 decoder 从 XML 迁移到 YAML 的完整路径包括支持的 YAML 特性、XML 与 YAML 的逐项等价关系、4.x 中被废弃的 decoder 元素及原因、逐步迁移操作流程以及可直接复用的参考 YAML 示例与一个 sshd/sudo 认证日志的完整转换案例。读完本文你将能够独立把任意 4.x 自定义 decoder 改写为 5.x 的 YAML decoder并理解 logpar 表达式、normalize 块与 schema 字段类型背后的实现原理。迁移前建议先阅读 引擎模块入门 和 引擎完整参考文档理解 5.x 的解码架构与资产模型迁移体验会更顺畅。1. 迁移前置条件先理解 5.x 引擎模型在动手改写 decoder 之前需要先理解 5.x 相对 4.x 的根本性架构变化详见 引擎模块入门格式变化4.x 的 decoder 用 XML 编写5.x 用 YAML 定义。这一决策主要源于 YAML 能更清晰、更易维护地表达结构化与类型化值字符串、数字、布尔、数组、对象同时消除了 4.x 的预解码阶段——该阶段偶尔会解析失败并产生不准确的值。树结构变化4.x 的 decoder 链是decoder-1 - decoder-2 - ... - decoder-n每个 decoder 可以有子节点但子节点不能再有子节点树的最大深度为 2事件到达后 decoder 逐个尝试父节点的子节点顺序测试若全部失败则父节点也失败并把事件交给下一个 decoder。5.x 中一个 decoder 可以拥有一个或多个parent形成深度为 n 的树处理流程更垂直。运行时架构5.x 的引擎wazuh-manager-analysisd守护进程通过策略policy处理事件策略包含可选预过滤器、有序的集成integration列表、可选富化enrichment、可选后过滤器与输出outputs阶段。所有 decoder 都属于某个集成集成归属七类 category 之一access-management、applications、cloud-services、network-activity、security、system-activity、othercategory 会写入每个事件的wazuh.integration.category字段并用于输出路由。内容管理decoder 等资产的真源位于 Wazuh Indexer引擎通过 CMSync 子模块定期从 Indexer 拉取内容到本地存储后重建运行图参见 内容管理章节。理解这些变化是迁移的前提尤其是decoder 名称全局唯一无跨事件状态字段必须属于 Wazuh Common SchemaWCS或临时变量这三条约束它们直接决定了下文哪些 XML 特性会被移除。2. YAML decoder 支持的字段能力总览2.1 支持的 YAML 标签Assets 通用属性5.x 中 decoder 是一种资产asset。每个资产共享以下通用属性详细字段说明见 引擎文档 Assets 章节属性说明name全局唯一标识模式为asset_type/name/version例如decoder/aws-cloudtrail/0id全局唯一 UUIDv4 字符串enabled布尔值禁用的资产在构建策略运行图时被忽略metadata资产的描述性信息parents列出父资产名称决定该资产在资产图中的位置definitions构建期类型化宏在被引用的位置做值替换decoder 特有属性为check、parse|field、normalize三个阶段详见 引擎文档 Decoders 章节本文第 4、5 节会逐一展开。2.2 Metadata 元数据字段metadata用于描述 decoder 的用途、作者与兼容性不参与事件处理。常见子字段如下参考 引擎文档 Attributes 章节字段类型说明modulestring关联模块如syslog、windows、apachetitlestring人类可读的标题descriptionstring简要描述authorobject作者信息可含name、email、url、datedatestring创建/修订日期如2026-03-20referencesarray指向相关产品文档的链接数组compatibilitystring兼容的产品、版本与格式versionsarray经过测试和支持的版本列表迁移文档给出的参考示例中metadata至少包含title、description、author、date、references与supports等字段建议在迁移时补齐这些信息以保证资产的可维护性。2.3 Normalize 数组normalize是 decoder 的变换阶段它是一个有序的归一化块normalization block数组。每个块是独立单元可包含以下子阶段的任意组合详见 引擎文档 Normalize/Enrichment 章节check可选块的进入条件失败则跳过整个块不会导致 decoder 失败parse|field可选块内的解析步骤map可选字段赋值数组形式为{目标字段: 值或表达式}。关键行为normalize 内某个块失败只会被跳过而不会让整个 decoder 失败。这与顶层check/parse|的语义不同——顶层条件失败意味着 decoder 拒绝该事件。合法的块组合方式组合适用场景map无条件赋值checkmap仅当条件成立时赋值checkparse|map有条件的提取然后赋值checkparse|有条件的提取不赋值parse|仅提取从源码结构看这一设计与 decoder schema 定义 中 normalize 块允许check、parse|、map组合出现的约束一致。3. XML 元素与 YAML 的等价映射迁移的本质是把 4.x 的每个 XML 元素翻译成对应的 YAML 结构。官方等价表如下XML 元素YAML 等价物decoder name... ... /decodername: ...parent.../parentparents: ...prematch.../prematchcheck: ...parse|field: ...regex.../regex/order.../orderparse|field: ...program_name.../program_namecheck: $process.name ...逐项解读parent→parents4.x 中 decoder 只有一个父节点5.x 的parents是数组一个子 decoder 可以挂接在多个父 decoder 之下。子 decoder 只有在其中一个父 decoder 已经匹配事件后才会运行。prematch→check4.x 中prematch是纯预过滤器其捕获组从不映射到order字段只有regex的捕获组会映射。因此 5.x 把它改写成不提取任何内容的布尔条件表达式例如$process.name sshd不会丢失任何提取逻辑。regexorder→parse|field4.x 中正则捕获组与order字段一一对应5.x 中每个正则被改写为一条 logpar 表达式捕获组被替换为带类型字段的占位符详见第 4 节。program_name→check: $process.name ...程序名过滤在 5.x 中就是对已解码的process.name字段做相等判断。从 引擎文档 Decoding process 可知decoder 树的求值是深度优先的decoder 接受事件后其子 decoder 依次求值同一父节点下的兄弟 decoder 按逻辑 OR 处理——只有第一个接受事件的子 decoder 会被选中其余跳过。这决定了parents与兄弟顺序对事件路由的实际影响。4. 不支持的 XML 模式及其移除原因以下 4.x XML 元素在 5.x 中没有对应物迁移时必须删除或重构XML 元素移除原因plugin_decoder插件 decoder 是硬编码 C 处理程序JSON_Decoder、SyscollectorDeltas 等的钩子。5.x 用原生 YAML 驱动的解析取代了该扩展模型插件钩子已无可调用对象json_null_field控制 4.x JSON 插件对 null 值的处理方式。5.x 以不同语义原生处理 JSON没有可配置的插件type4.x 用 decoder 类型syslog、json、windows 等将日志路由到内置处理程序。5.x 替换了整个路由层decoder 是带显式 parse 表达式的纯 YAML 流水线无需路由ftsFirst-Time-Seen 是构建在 decoder 层的有状态特性。5.x decoder 设计为无状态每个事件独立处理ftscomment附加在fts上的人类可读标签用于描述触发首次告警的内容。FTS 在 5.x 中被移除该注释无对应物accumulate/允许 decoder 跨多行日志累积数据同样是有状态的与fts原因相同——5.x 解码层没有跨事件状态use_own_name4.x 中兄弟 decoder 可共享同名use_own_name让子 decoder 报告自己的名字而非父的名字。5.x 强制唯一名称decoder/name/version无需消歧prematch typepcre2/regex typepcre24.x 默认 POSIX ERE可选 PCRE2。5.x 的 logpar根本不是基于正则的——它是结构化字段提取语言正则引擎选择无关紧要prematch offsetafter_parent/regex offsetafter_prematchoffsetafter_parent、after_prematch、after_regex是告诉正则引擎从何处开始扫描的性能提示。logpar 表达式是顺序解析器天然跟踪位置无需 offset 提示需要特别指出的是use_own_name的消失源于名称唯一性约束5.x 的资产name采用asset_type/name/version模式且全局唯一引擎文档 Attributesschema 验证层wazuh-decoders.json同样按此约束校验 decoder 文档结构。而offset类特性的消除可从 logpar 模块实现 得到印证logpar 表达式被编译为组合解析器combinator字段的结束 token 由表达式中下一个字面量/组递归解析得出位置推进由解析器天然完成。5. 迁移操作步骤XML → YAML按以下六个步骤迁移一个 decoder第 1 步编写 Header头部name设为decoder/your-name/0。5.0 中所有用户创建的 decoder 版本号均为 0——版本化保留给未来使用为id生成一个 UUIDv4设置enabled: true填充metadata见 2.2 节。第 2 步转换parent把parent转换为parents数组列出父 decoder 的名称。子 decoder 只有在某个列出的父 decoder 已匹配事件后才运行。例如parentsyslog/parent转换为parents: - decoder/syslog/0注意5.x 中parents的值是资产全名含decoder/前缀与版本号而非 4.x 的短名。第 3 步转换prematch为check把prematch改写为对已解码字段的布尔表达式。check只做过滤、从不提取。prematch^(sshd|sudo)/prematch转换为check: $process.name sshd OR $process.name sudo[!NOTE] 4.x 中prematch是纯预过滤器其捕获组从不映射到order字段只有regex的捕获组才映射到order。因此把prematch迁移为check不会丢失任何提取逻辑。check支持两种写法详见 引擎文档 Check/Allow 章节条件表达式字符串使用$field引用、helper 调用与逻辑/比较运算符AND、OR、NOT、、!、、、、条件列表有序的单键对象数组{字段: 条件}所有条件必须按顺序全部通过。# 条件表达式写法 check: $process.name sshd OR $process.name sudo # 条件列表写法 check: - process.name: sshd从 decoder schema 定义 可以看到check的两种形式_checkExpression与_checkList都经过 JSON Schema 严格校验表达式必须包含$field或 helper 调用且含比较/逻辑运算符列表项必须是单键对象且值只能是 JSON 字面量、$field引用或 helper 调用。第 4 步转换regexorder为parse|field把每个正则改写为一条logpar 表达式。语法为parse|field: - logpar expression 1 - logpar expression 2其中field是要解析的源字段syslog 事件通常是message。表达式中每个捕获组替换为带 schema 类型的命名字段占位符。官方迁移文档给出的 logpar 核心规则如下Schema 字段自动类型source.ipIP、source.port数字、timestamp日期等 schema 字段会自动套用与其类型匹配的解析器无需显式声明类型。在 logpar 模块实现 中这一schema 类型 → 解析器类型映射在Logpar::build()构建管线中完成字段类型通过schemf::IValidator解析再按映射选择hlp::parsers::*中注册的类型化解析器如IP → P_IP、LONG → P_LONG、TEXT/KEYWORD → P_TEXT。用后缀强制类型source.port/long显式指定使用 long 解析器。可选段connected from source.ip(? port source.port)匹配可选的port N后缀对可选字段本身用?optional.field前缀问号标记。匹配但不映射通配符~匹配并丢弃任意内容可加可选名称区分同一条表达式中的多个通配符~skip可加类型后缀约束其匹配内容~skip/long只匹配整数内容。临时变量以_前缀命名如_ssh.event解码结束后会被剥离见下文。多表达式同一个parse|下可以列出多条表达式按顺序尝试首个匹配生效。关于 logpar 的更多语法元素字面量转义、字段选择a?b、可选组、结束 token 规则等可参考 解析器参考文档 与 logpar 模块说明。例如 引擎文档 Parse 章节 给出的 Apache error 解析示例parse|event.original: - [timestamp/Mon Dec 26 16:22:00 2016] [log.level] [client source.address(?:source.port)] message - [timestamp/%a %b %d %T %Y/en_US.UTF-8] [~apache.error.module:log.level] [pid process.pid(?:tid process.thread.id)] [client source.address(?:source.port)] message临时变量的生命周期临时变量_前缀字段提供解码树遍历期间的暂存空间可被一个 decoder 写入、被后续 decoder 读取。解码阶段结束后预富化阶段的临时变量清理步骤会强制删除所有_前缀字段保证进入富化/输出阶段的事件只剩 WCS 字段见 引擎文档 Cleanup of decoder temporary variables。第 5 步添加静态赋值map所有无条件设置的内容事件类别、数据集、结果等都放在 normalize 内的map块中normalize: - map: - event.action: authentication-failure - event.outcome: failure - event.category: array_append(authentication)map的每个操作都是{目标字段: 值或表达式}引擎文档 Operations 章节值可以是 YAML 字面量、$field引用或 helper 函数调用。上面的array_append(authentication)是映射型 helper用于向数组字段追加值。映射到 schema 字段时会做类型校验构建期提供固定值则立即校验类型非法直接构建失败动态值来自 helper 或其他字段在运行时校验失败则字段保持未映射以维持事件完整性。第 6 步组合 normalize 块每个 normalize 块可独立组合check、parse|、map见 2.3 节组合表。失败的块被跳过而不是让整个 decoder 失败这是 normalize 与顶层 check/parse 的关键差异允许尽力而为的提取策略例如第 5 节参考示例中先无条件map设置event.kind后续按不同进程名分别解析。6. 参考 YAML 示例6.1 认证失败 decoder含 parent、check、parse、mapname: decoder/ssh-auth-failure/0 id: replace-with-a-new-uuidv4 enabled: true parents: - decoder/syslog/0 metadata: title: SSH/Sudo authentication failure description: Extracts failed authentication attempts from sshd and sudo processes. author: ORGANIZATION/AUTHOR OF DECODER date: YYYY-MM-DD references: - https://github.com/wazuh/wazuh/tree/main/docs/ref/modules/engine/ compatibility: - Wazuh 5.0 supports: - Ubuntu 24.04 LTS check: $process.name sshd OR $process.name sudo normalize: - parse|message: - ~: Failed password for user.name from source.ip map: - event.action: authentication-failure - event.outcome: failure - event.category: array_append(authentication)逐段解读parents挂在decoder/syslog/0之下说明该 decoder 只处理已由 syslog decoder 接受的 syslog 事件顶层check用 OR 表达式限定process.name为 sshd 或 sudo源自 4.x 的prematchprogram_namenormalize内的parse|message以~通配符丢弃时间戳等前缀提取user.name与source.ip随后的map无条件写入event.action、event.outcome并用array_append追加event.category。6.2 基础父 decoder只有 check mapname: decoder/sshd-base/0 id: replace-with-a-new-uuidv4 enabled: true metadata: title: Base sshd process event description: Base decoder for sshd events. Sets event.kind before child decoders extract details. author: ORGANIZATION/AUTHOR OF DECODER date: YYYY-MM-DD check: - process.name: sshd normalize: - map: - event.kind: event这个示例展示了基础 decoder模式只做轻量check条件列表写法与无条件map为下游子 decoder 预先设置event.kind符合每个 decoder 处理一个专门层级的树状设计思想。6.3 参考引擎内置 system-auth decoder 的结构引擎文档 Decoders 章节 给出了更复杂的decoder/system-auth/0示例展示了两点实战技巧迁移大型 decoder 时可直接借鉴用definitions宏保持 OR 条件可读把一长串$process.name sshd OR ...提取为definitions.isAuthProcess在check中通过$isAuthProcess引用——definitions 是构建期替换的宏不是运行时变量用多个 normalize 块分场景解析Block 1 无条件 map 基础字段Block 2 按process.name: sshd分派到多条 parse 表达式Block 3~5 依据临时变量_system.auth.ssh.event的值分别映射登录成功/登出/失败Block 12 做related.*、process.command_line等收尾映射。7. 完整转换案例认证日志 decoder7.1 原始 4.x XMLdecoder nameauth_decoder parentsyslog/parent prematch^(sshd|sudo)/prematch regex(\w): Failed password for (\w) from ([\d.])/regex orderprocess.name,user.name,source.ip/order /decoder该 decoder 的功能作为 syslog 的子 decoder先以^(sshd|sudo)预匹配再用正则提取process.name、user.name、source.ip三个字段。7.2 迁移后的 5.x YAMLname: decoder/auth-failure/0 id: replace-with-a-new-uuidv4 enabled: true parents: - decoder/syslog/0 metadata: title: SSH/Sudo authentication failure description: Extracts failed authentication attempts author: ORGANIZATION/AUTHOR OF DECODER date: YYYY-MM-DD check: $process.name sshd OR $process.name sudo normalize: - parse|message: - process.name: Failed password for user.name from source.ip map: - event.action: authentication-failure - event.outcome: failure - event.category: array_append(authentication)7.3 逐项对照4.x XML5.x YAML说明decoder nameauth_decodername: decoder/auth-failure/0名称唯一化并带上类型/版本前缀4.x 短名auth_decoder变成decoder/auth-failure/0parentsyslog/parentparents: [decoder/syslog/0]父节点用资产全名prematch^(sshd\|sudo)/prematchcheck: $process.name sshd OR $process.name sudo正则预匹配 → 对已解码字段process.name的布尔判断。注意4.x 中^(sshd\|sudo)用\|表示正则选择logpar 中对应的是OR逻辑运算regex(\w): Failed password for (\w) from ([\d.])/regexorderprocess.name,user.name,source.ip/orderparse\|message: process.name: Failed password for user.name from source.ip正则的\w捕获组 → schema 类型字段process.name、user.name[\d.]IP 匹配→ 自动类型化的source.ip。logpar 不再需要\w、[\d.]这类字符类字段类型由 schema 决定—无对应map: event.action / event.outcome / event.category新增的归一化赋值把提取结果语义化认证失败、失败结果、认证类别7.4 类型化字段的解析效果按照 schema 解析器映射user.namekeyword/text 类型使用 text 解析器source.ipip 类型使用 IP 解析器可匹配 IPv4/IPv6source.portlong 类型使用 long 解析器。以日志行sshd: Failed password for alice from 192.168.1.10为例解析结果对应字段为process.namesshd、user.namealice、source.ip192.168.1.10且source.ip最终以 IP 类型写入 WCS 事件。若 4.x 正则捕获的 IP 含非法字符logpar 的 IP 解析器会直接使该表达式不匹配进而尝试同parse|下一条表达式解析器参考文档 中每个解析器都有严格的失败语义这比正则的宽松匹配更严谨。8. 迁移后的验证与调试迁移完成后可以通过引擎的 trace 机制验证 decoder 行为详见 引擎文档 Traces 章节Graph history查看事件经过了哪些资产与策略阶段定位事件在哪个 decoder 被接受/拒绝/丢弃Full traces逐步查看每个资产内部的每个操作check、parse、map成功或失败精确定位解析失败点Asset filtering只输出指定资产组的 trace缩小排查范围。引擎日志统一写入/var/wazuh-manager/logs/wazuh-manager.log组件标签通常为wazuh-manager-analysisd。需要更详细日志时可在/var/wazuh-manager/etc/wazuh-manager-internal-options.conf中设置analysisd.debug1debug或2trace修改后重启wazuh-manager服务生效内部选项参考。此外decoder 文档结构在构建/上传时还会经过 decoder schema 验证name唯一性、check表达式/列表合法性、字段类型与 schema 一致性等问题都会在构建期暴露避免错误的 decoder 进入运行图引擎文档 Operations 章节。总结从 XML 到 YAML 的 decoder 迁移本质上是一次模型转换把正则驱动的有状态 XML decoder改造成 logpar 驱动的无状态 YAML 资产。迁移时把握三条主线即可结构等价parent→parents、prematch→check、regexorder→parse|field、program_name→check: $process.name ...丢弃有状态/正则特性fts、accumulate、use_own_name、type、plugin_decoder、regex engine 与 offset 提示全部移除善用新能力多父节点、normalize 块组合、schema 自动类型化字段、通配符/可选组/临时变量、definitions 宏与 KVDB这些是 5.x 表达力远超 4.x 的地方。参考 引擎完整文档、解析器参考、helper 函数参考 与 logpar 模块说明 可继续深入每个语法细节与实现原理。【免费下载链接】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），仅供参考 Wazuh 5.x 自定义 Decoder 迁移指南：从 XML 到 YAML 的完整改造实战
Wazuh 5.x 自定义 Decoder 迁移指南从 XML 到 YAML 的完整改造实战【免费下载链接】wazuhWazuh - The Open Source Security Platform. Unified XDR and SIEM protection for endpoints and cloud workloads.项目地址: https://gitcode.com/GitHub_Trending/wa/wazuh导读Wazuh 5.x 将解码层从 4.x 的 XML 格式 decoder 全面迁移到基于 YAML 的声明式资产模型并引入全新的 logpar 结构化字段提取语言取代正则表达式。本文以官方迁移文档为主体结合引擎源码与 schema 定义系统讲解自定义 decoder 从 XML 迁移到 YAML 的完整路径包括支持的 YAML 特性、XML 与 YAML 的逐项等价关系、4.x 中被废弃的 decoder 元素及原因、逐步迁移操作流程以及可直接复用的参考 YAML 示例与一个 sshd/sudo 认证日志的完整转换案例。读完本文你将能够独立把任意 4.x 自定义 decoder 改写为 5.x 的 YAML decoder并理解 logpar 表达式、normalize 块与 schema 字段类型背后的实现原理。迁移前建议先阅读 引擎模块入门 和 引擎完整参考文档理解 5.x 的解码架构与资产模型迁移体验会更顺畅。1. 迁移前置条件先理解 5.x 引擎模型在动手改写 decoder 之前需要先理解 5.x 相对 4.x 的根本性架构变化详见 引擎模块入门格式变化4.x 的 decoder 用 XML 编写5.x 用 YAML 定义。这一决策主要源于 YAML 能更清晰、更易维护地表达结构化与类型化值字符串、数字、布尔、数组、对象同时消除了 4.x 的预解码阶段——该阶段偶尔会解析失败并产生不准确的值。树结构变化4.x 的 decoder 链是decoder-1 - decoder-2 - ... - decoder-n每个 decoder 可以有子节点但子节点不能再有子节点树的最大深度为 2事件到达后 decoder 逐个尝试父节点的子节点顺序测试若全部失败则父节点也失败并把事件交给下一个 decoder。5.x 中一个 decoder 可以拥有一个或多个parent形成深度为 n 的树处理流程更垂直。运行时架构5.x 的引擎wazuh-manager-analysisd守护进程通过策略policy处理事件策略包含可选预过滤器、有序的集成integration列表、可选富化enrichment、可选后过滤器与输出outputs阶段。所有 decoder 都属于某个集成集成归属七类 category 之一access-management、applications、cloud-services、network-activity、security、system-activity、othercategory 会写入每个事件的wazuh.integration.category字段并用于输出路由。内容管理decoder 等资产的真源位于 Wazuh Indexer引擎通过 CMSync 子模块定期从 Indexer 拉取内容到本地存储后重建运行图参见 内容管理章节。理解这些变化是迁移的前提尤其是decoder 名称全局唯一无跨事件状态字段必须属于 Wazuh Common SchemaWCS或临时变量这三条约束它们直接决定了下文哪些 XML 特性会被移除。2. YAML decoder 支持的字段能力总览2.1 支持的 YAML 标签Assets 通用属性5.x 中 decoder 是一种资产asset。每个资产共享以下通用属性详细字段说明见 引擎文档 Assets 章节属性说明name全局唯一标识模式为asset_type/name/version例如decoder/aws-cloudtrail/0id全局唯一 UUIDv4 字符串enabled布尔值禁用的资产在构建策略运行图时被忽略metadata资产的描述性信息parents列出父资产名称决定该资产在资产图中的位置definitions构建期类型化宏在被引用的位置做值替换decoder 特有属性为check、parse|field、normalize三个阶段详见 引擎文档 Decoders 章节本文第 4、5 节会逐一展开。2.2 Metadata 元数据字段metadata用于描述 decoder 的用途、作者与兼容性不参与事件处理。常见子字段如下参考 引擎文档 Attributes 章节字段类型说明modulestring关联模块如syslog、windows、apachetitlestring人类可读的标题descriptionstring简要描述authorobject作者信息可含name、email、url、datedatestring创建/修订日期如2026-03-20referencesarray指向相关产品文档的链接数组compatibilitystring兼容的产品、版本与格式versionsarray经过测试和支持的版本列表迁移文档给出的参考示例中metadata至少包含title、description、author、date、references与supports等字段建议在迁移时补齐这些信息以保证资产的可维护性。2.3 Normalize 数组normalize是 decoder 的变换阶段它是一个有序的归一化块normalization block数组。每个块是独立单元可包含以下子阶段的任意组合详见 引擎文档 Normalize/Enrichment 章节check可选块的进入条件失败则跳过整个块不会导致 decoder 失败parse|field可选块内的解析步骤map可选字段赋值数组形式为{目标字段: 值或表达式}。关键行为normalize 内某个块失败只会被跳过而不会让整个 decoder 失败。这与顶层check/parse|的语义不同——顶层条件失败意味着 decoder 拒绝该事件。合法的块组合方式组合适用场景map无条件赋值checkmap仅当条件成立时赋值checkparse|map有条件的提取然后赋值checkparse|有条件的提取不赋值parse|仅提取从源码结构看这一设计与 decoder schema 定义 中 normalize 块允许check、parse|、map组合出现的约束一致。3. XML 元素与 YAML 的等价映射迁移的本质是把 4.x 的每个 XML 元素翻译成对应的 YAML 结构。官方等价表如下XML 元素YAML 等价物decoder name... ... /decodername: ...parent.../parentparents: ...prematch.../prematchcheck: ...parse|field: ...regex.../regex/order.../orderparse|field: ...program_name.../program_namecheck: $process.name ...逐项解读parent→parents4.x 中 decoder 只有一个父节点5.x 的parents是数组一个子 decoder 可以挂接在多个父 decoder 之下。子 decoder 只有在其中一个父 decoder 已经匹配事件后才会运行。prematch→check4.x 中prematch是纯预过滤器其捕获组从不映射到order字段只有regex的捕获组会映射。因此 5.x 把它改写成不提取任何内容的布尔条件表达式例如$process.name sshd不会丢失任何提取逻辑。regexorder→parse|field4.x 中正则捕获组与order字段一一对应5.x 中每个正则被改写为一条 logpar 表达式捕获组被替换为带类型字段的占位符详见第 4 节。program_name→check: $process.name ...程序名过滤在 5.x 中就是对已解码的process.name字段做相等判断。从 引擎文档 Decoding process 可知decoder 树的求值是深度优先的decoder 接受事件后其子 decoder 依次求值同一父节点下的兄弟 decoder 按逻辑 OR 处理——只有第一个接受事件的子 decoder 会被选中其余跳过。这决定了parents与兄弟顺序对事件路由的实际影响。4. 不支持的 XML 模式及其移除原因以下 4.x XML 元素在 5.x 中没有对应物迁移时必须删除或重构XML 元素移除原因plugin_decoder插件 decoder 是硬编码 C 处理程序JSON_Decoder、SyscollectorDeltas 等的钩子。5.x 用原生 YAML 驱动的解析取代了该扩展模型插件钩子已无可调用对象json_null_field控制 4.x JSON 插件对 null 值的处理方式。5.x 以不同语义原生处理 JSON没有可配置的插件type4.x 用 decoder 类型syslog、json、windows 等将日志路由到内置处理程序。5.x 替换了整个路由层decoder 是带显式 parse 表达式的纯 YAML 流水线无需路由ftsFirst-Time-Seen 是构建在 decoder 层的有状态特性。5.x decoder 设计为无状态每个事件独立处理ftscomment附加在fts上的人类可读标签用于描述触发首次告警的内容。FTS 在 5.x 中被移除该注释无对应物accumulate/允许 decoder 跨多行日志累积数据同样是有状态的与fts原因相同——5.x 解码层没有跨事件状态use_own_name4.x 中兄弟 decoder 可共享同名use_own_name让子 decoder 报告自己的名字而非父的名字。5.x 强制唯一名称decoder/name/version无需消歧prematch typepcre2/regex typepcre24.x 默认 POSIX ERE可选 PCRE2。5.x 的 logpar根本不是基于正则的——它是结构化字段提取语言正则引擎选择无关紧要prematch offsetafter_parent/regex offsetafter_prematchoffsetafter_parent、after_prematch、after_regex是告诉正则引擎从何处开始扫描的性能提示。logpar 表达式是顺序解析器天然跟踪位置无需 offset 提示需要特别指出的是use_own_name的消失源于名称唯一性约束5.x 的资产name采用asset_type/name/version模式且全局唯一引擎文档 Attributesschema 验证层wazuh-decoders.json同样按此约束校验 decoder 文档结构。而offset类特性的消除可从 logpar 模块实现 得到印证logpar 表达式被编译为组合解析器combinator字段的结束 token 由表达式中下一个字面量/组递归解析得出位置推进由解析器天然完成。5. 迁移操作步骤XML → YAML按以下六个步骤迁移一个 decoder第 1 步编写 Header头部name设为decoder/your-name/0。5.0 中所有用户创建的 decoder 版本号均为 0——版本化保留给未来使用为id生成一个 UUIDv4设置enabled: true填充metadata见 2.2 节。第 2 步转换parent把parent转换为parents数组列出父 decoder 的名称。子 decoder 只有在某个列出的父 decoder 已匹配事件后才运行。例如parentsyslog/parent转换为parents: - decoder/syslog/0注意5.x 中parents的值是资产全名含decoder/前缀与版本号而非 4.x 的短名。第 3 步转换prematch为check把prematch改写为对已解码字段的布尔表达式。check只做过滤、从不提取。prematch^(sshd|sudo)/prematch转换为check: $process.name sshd OR $process.name sudo[!NOTE] 4.x 中prematch是纯预过滤器其捕获组从不映射到order字段只有regex的捕获组才映射到order。因此把prematch迁移为check不会丢失任何提取逻辑。check支持两种写法详见 引擎文档 Check/Allow 章节条件表达式字符串使用$field引用、helper 调用与逻辑/比较运算符AND、OR、NOT、、!、、、、条件列表有序的单键对象数组{字段: 条件}所有条件必须按顺序全部通过。# 条件表达式写法 check: $process.name sshd OR $process.name sudo # 条件列表写法 check: - process.name: sshd从 decoder schema 定义 可以看到check的两种形式_checkExpression与_checkList都经过 JSON Schema 严格校验表达式必须包含$field或 helper 调用且含比较/逻辑运算符列表项必须是单键对象且值只能是 JSON 字面量、$field引用或 helper 调用。第 4 步转换regexorder为parse|field把每个正则改写为一条logpar 表达式。语法为parse|field: - logpar expression 1 - logpar expression 2其中field是要解析的源字段syslog 事件通常是message。表达式中每个捕获组替换为带 schema 类型的命名字段占位符。官方迁移文档给出的 logpar 核心规则如下Schema 字段自动类型source.ipIP、source.port数字、timestamp日期等 schema 字段会自动套用与其类型匹配的解析器无需显式声明类型。在 logpar 模块实现 中这一schema 类型 → 解析器类型映射在Logpar::build()构建管线中完成字段类型通过schemf::IValidator解析再按映射选择hlp::parsers::*中注册的类型化解析器如IP → P_IP、LONG → P_LONG、TEXT/KEYWORD → P_TEXT。用后缀强制类型source.port/long显式指定使用 long 解析器。可选段connected from source.ip(? port source.port)匹配可选的port N后缀对可选字段本身用?optional.field前缀问号标记。匹配但不映射通配符~匹配并丢弃任意内容可加可选名称区分同一条表达式中的多个通配符~skip可加类型后缀约束其匹配内容~skip/long只匹配整数内容。临时变量以_前缀命名如_ssh.event解码结束后会被剥离见下文。多表达式同一个parse|下可以列出多条表达式按顺序尝试首个匹配生效。关于 logpar 的更多语法元素字面量转义、字段选择a?b、可选组、结束 token 规则等可参考 解析器参考文档 与 logpar 模块说明。例如 引擎文档 Parse 章节 给出的 Apache error 解析示例parse|event.original: - [timestamp/Mon Dec 26 16:22:00 2016] [log.level] [client source.address(?:source.port)] message - [timestamp/%a %b %d %T %Y/en_US.UTF-8] [~apache.error.module:log.level] [pid process.pid(?:tid process.thread.id)] [client source.address(?:source.port)] message临时变量的生命周期临时变量_前缀字段提供解码树遍历期间的暂存空间可被一个 decoder 写入、被后续 decoder 读取。解码阶段结束后预富化阶段的临时变量清理步骤会强制删除所有_前缀字段保证进入富化/输出阶段的事件只剩 WCS 字段见 引擎文档 Cleanup of decoder temporary variables。第 5 步添加静态赋值map所有无条件设置的内容事件类别、数据集、结果等都放在 normalize 内的map块中normalize: - map: - event.action: authentication-failure - event.outcome: failure - event.category: array_append(authentication)map的每个操作都是{目标字段: 值或表达式}引擎文档 Operations 章节值可以是 YAML 字面量、$field引用或 helper 函数调用。上面的array_append(authentication)是映射型 helper用于向数组字段追加值。映射到 schema 字段时会做类型校验构建期提供固定值则立即校验类型非法直接构建失败动态值来自 helper 或其他字段在运行时校验失败则字段保持未映射以维持事件完整性。第 6 步组合 normalize 块每个 normalize 块可独立组合check、parse|、map见 2.3 节组合表。失败的块被跳过而不是让整个 decoder 失败这是 normalize 与顶层 check/parse 的关键差异允许尽力而为的提取策略例如第 5 节参考示例中先无条件map设置event.kind后续按不同进程名分别解析。6. 参考 YAML 示例6.1 认证失败 decoder含 parent、check、parse、mapname: decoder/ssh-auth-failure/0 id: replace-with-a-new-uuidv4 enabled: true parents: - decoder/syslog/0 metadata: title: SSH/Sudo authentication failure description: Extracts failed authentication attempts from sshd and sudo processes. author: ORGANIZATION/AUTHOR OF DECODER date: YYYY-MM-DD references: - https://github.com/wazuh/wazuh/tree/main/docs/ref/modules/engine/ compatibility: - Wazuh 5.0 supports: - Ubuntu 24.04 LTS check: $process.name sshd OR $process.name sudo normalize: - parse|message: - ~: Failed password for user.name from source.ip map: - event.action: authentication-failure - event.outcome: failure - event.category: array_append(authentication)逐段解读parents挂在decoder/syslog/0之下说明该 decoder 只处理已由 syslog decoder 接受的 syslog 事件顶层check用 OR 表达式限定process.name为 sshd 或 sudo源自 4.x 的prematchprogram_namenormalize内的parse|message以~通配符丢弃时间戳等前缀提取user.name与source.ip随后的map无条件写入event.action、event.outcome并用array_append追加event.category。6.2 基础父 decoder只有 check mapname: decoder/sshd-base/0 id: replace-with-a-new-uuidv4 enabled: true metadata: title: Base sshd process event description: Base decoder for sshd events. Sets event.kind before child decoders extract details. author: ORGANIZATION/AUTHOR OF DECODER date: YYYY-MM-DD check: - process.name: sshd normalize: - map: - event.kind: event这个示例展示了基础 decoder模式只做轻量check条件列表写法与无条件map为下游子 decoder 预先设置event.kind符合每个 decoder 处理一个专门层级的树状设计思想。6.3 参考引擎内置 system-auth decoder 的结构引擎文档 Decoders 章节 给出了更复杂的decoder/system-auth/0示例展示了两点实战技巧迁移大型 decoder 时可直接借鉴用definitions宏保持 OR 条件可读把一长串$process.name sshd OR ...提取为definitions.isAuthProcess在check中通过$isAuthProcess引用——definitions 是构建期替换的宏不是运行时变量用多个 normalize 块分场景解析Block 1 无条件 map 基础字段Block 2 按process.name: sshd分派到多条 parse 表达式Block 3~5 依据临时变量_system.auth.ssh.event的值分别映射登录成功/登出/失败Block 12 做related.*、process.command_line等收尾映射。7. 完整转换案例认证日志 decoder7.1 原始 4.x XMLdecoder nameauth_decoder parentsyslog/parent prematch^(sshd|sudo)/prematch regex(\w): Failed password for (\w) from ([\d.])/regex orderprocess.name,user.name,source.ip/order /decoder该 decoder 的功能作为 syslog 的子 decoder先以^(sshd|sudo)预匹配再用正则提取process.name、user.name、source.ip三个字段。7.2 迁移后的 5.x YAMLname: decoder/auth-failure/0 id: replace-with-a-new-uuidv4 enabled: true parents: - decoder/syslog/0 metadata: title: SSH/Sudo authentication failure description: Extracts failed authentication attempts author: ORGANIZATION/AUTHOR OF DECODER date: YYYY-MM-DD check: $process.name sshd OR $process.name sudo normalize: - parse|message: - process.name: Failed password for user.name from source.ip map: - event.action: authentication-failure - event.outcome: failure - event.category: array_append(authentication)7.3 逐项对照4.x XML5.x YAML说明decoder nameauth_decodername: decoder/auth-failure/0名称唯一化并带上类型/版本前缀4.x 短名auth_decoder变成decoder/auth-failure/0parentsyslog/parentparents: [decoder/syslog/0]父节点用资产全名prematch^(sshd\|sudo)/prematchcheck: $process.name sshd OR $process.name sudo正则预匹配 → 对已解码字段process.name的布尔判断。注意4.x 中^(sshd\|sudo)用\|表示正则选择logpar 中对应的是OR逻辑运算regex(\w): Failed password for (\w) from ([\d.])/regexorderprocess.name,user.name,source.ip/orderparse\|message: process.name: Failed password for user.name from source.ip正则的\w捕获组 → schema 类型字段process.name、user.name[\d.]IP 匹配→ 自动类型化的source.ip。logpar 不再需要\w、[\d.]这类字符类字段类型由 schema 决定—无对应map: event.action / event.outcome / event.category新增的归一化赋值把提取结果语义化认证失败、失败结果、认证类别7.4 类型化字段的解析效果按照 schema 解析器映射user.namekeyword/text 类型使用 text 解析器source.ipip 类型使用 IP 解析器可匹配 IPv4/IPv6source.portlong 类型使用 long 解析器。以日志行sshd: Failed password for alice from 192.168.1.10为例解析结果对应字段为process.namesshd、user.namealice、source.ip192.168.1.10且source.ip最终以 IP 类型写入 WCS 事件。若 4.x 正则捕获的 IP 含非法字符logpar 的 IP 解析器会直接使该表达式不匹配进而尝试同parse|下一条表达式解析器参考文档 中每个解析器都有严格的失败语义这比正则的宽松匹配更严谨。8. 迁移后的验证与调试迁移完成后可以通过引擎的 trace 机制验证 decoder 行为详见 引擎文档 Traces 章节Graph history查看事件经过了哪些资产与策略阶段定位事件在哪个 decoder 被接受/拒绝/丢弃Full traces逐步查看每个资产内部的每个操作check、parse、map成功或失败精确定位解析失败点Asset filtering只输出指定资产组的 trace缩小排查范围。引擎日志统一写入/var/wazuh-manager/logs/wazuh-manager.log组件标签通常为wazuh-manager-analysisd。需要更详细日志时可在/var/wazuh-manager/etc/wazuh-manager-internal-options.conf中设置analysisd.debug1debug或2trace修改后重启wazuh-manager服务生效内部选项参考。此外decoder 文档结构在构建/上传时还会经过 decoder schema 验证name唯一性、check表达式/列表合法性、字段类型与 schema 一致性等问题都会在构建期暴露避免错误的 decoder 进入运行图引擎文档 Operations 章节。总结从 XML 到 YAML 的 decoder 迁移本质上是一次模型转换把正则驱动的有状态 XML decoder改造成 logpar 驱动的无状态 YAML 资产。迁移时把握三条主线即可结构等价parent→parents、prematch→check、regexorder→parse|field、program_name→check: $process.name ...丢弃有状态/正则特性fts、accumulate、use_own_name、type、plugin_decoder、regex engine 与 offset 提示全部移除善用新能力多父节点、normalize 块组合、schema 自动类型化字段、通配符/可选组/临时变量、definitions 宏与 KVDB这些是 5.x 表达力远超 4.x 的地方。参考 引擎完整文档、解析器参考、helper 函数参考 与 logpar 模块说明 可继续深入每个语法细节与实现原理。【免费下载链接】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），仅供参考