Wazuh 5.x 如何用 KVDB 替代 CDB 列表并重写规则查找【免费下载链接】wazuhWazuh - The Open Source Security Platform. Unified XDR and SIEM protection for endpoints and cloud workloads.项目地址: https://gitcode.com/GitHub_Trending/wa/wazuh在 Wazuh 4.x 中规则通过存放在/var/ossec/etc/lists/下的 CDBConstant Database列表完成威胁数据查找升级到 Wazuh 5.0 后规则处理由新的 Engine 模块接管同样的查找用途改用 KVDBKey-Value Database实现。官方文档明确指出CDB 列表不会自动迁移——你必须把每个列表转换成 KVDB并把原来引用它的规则改写成 decoder 的check和map阶段。本文基于 Wazuh 仓库中的迁移文档给出从备份、转换、打包上传到验证的完整操作路径。适用的前提是你的 5.x 环境已经具备 Wazuh Indexer 与 Engine并且自定义内容decoder、integration、KVDB通过 Wazuh Indexer 管理而不是直接改 Engine 本地文件。迁移前需要理解的两点结构差异5.x 与 4.x 在列表查找上有两个直接影响改写方式的差异在 4.xCDB 查找出现在规则list标签和 decoder 中在 5.x所有 KVDB 查找都位于 decoder 中原来写在规则层的 CDB 查找逻辑必须移到处理这些事件的 decoder 里。CDB 列表没有定义 schema是/var/ossec/etc/lists/下的文件KVDB 是带显式content条目的 YAML 文档随 integration 打包、存储在 Wazuh Indexer 中并自动同步到 Engine。此外 5.x 的 decoder 由 XML 改为 YAML 定义decoder 树也允许一个 decoder 有多个 parent详见 Engine 模块简介。准备工作备份 CDB 列表与规则转换前先备份原有的 CDB 列表和规则文件。以下命令只读取并复制源文件到/tmp/cdb-migration不修改任何原文件sudo mkdir -p /tmp/cdb-migration cp -r /var/ossec/etc/lists /tmp/cdb-migration cp -r /var/ossec/etc/rules/ /tmp/cdb-migrationCDB lookup 类型到 5.x KVDB 辅助函数的映射迁移文档给出了逐条对应关系这是改写规则时的对照表CDBlookup类型5.x KVDB 辅助函数所在 decoder 阶段match_keykvdb_match(db_name)checknot_match_keykvdb_not_match(db_name)checkmatch_key_valuekvdb_get(db_name, $field) 对取回的值做过滤normalizemapcheckaddress_match_key精确 IPkvdb_match(db_name)checkaddress_match_key子网无直接等价物——改用ip_cidr_matchchecknot_address_match_key精确 IPkvdb_not_match(db_name)checknot_address_match_key子网无直接等价物check其中kvdb_match检查目标字段的值是否为指定 KVDB 中已存在的 keykvdb_not_match语义相反两者都只用于check阶段、不修改事件kvdb_get在map中取回 key 对应的值签名kvdb_get(db_name, key)。完整行为可查 KVDB 辅助函数参考。步骤一把 CDB 文件转换为 KVDB1. 编写 KVDB 骨架每个 KVDB 的骨架如下迁移文档示例。注意id、author、date处是占位符需要替换为你自己的值id换成一个新的 UUIDv4author换成你或你的组织名date用YYYY-MM-DD格式kvdbs: - id: replace-with-a-new-uuidv4 metadata: title: ips_list description: kvdb listing of ips author: ORGANIZATION/AUTHOR OF DECODER date: YYYY-MM-DD enabled: true content: # Here will go all your cdb key:value2. 逐条翻译 CDB 内容CDB 中的分隔符是:无空格KVDB 中 key 与 value 用标准 YAML mapping 的:分隔。例如 CDB 里的0x1:laptop 0x2:printer 0x3:1234对应 KVDB 的content: 0x1: laptop 0x2: printer 0x3: 1234KVDB 的值可以是任意 JSON 值字符串、数字、布尔、嵌套对象、数组这一点比 CDB 更宽泛。步骤二把 KVDB 打包进 integration 并上传KVDB 不能单独注册——它是integration的一部分integration 是 Engine 从 Wazuh Indexer 拉取内容的最小单元。创建一个 integration YAML引用该 KVDB 的 UUID 以及将使用它的 decoder 的 UUIDintegration 的kvdbs字段列出本 integration 的 decoder 使用的 KVDB UUID 列表decoders字段列出 decoder UUID。然后把 integration 和 KVDB 上传到 Wazuh Indexer 的Customspace。Engine 的内容管理器CMSync会在下一次同步周期检测到 Custom space 的变化并把 KVDB 推给 decoder 可用。Custom space 中用户自定义内容的管理方式见 Engine 内容管理章节。CMSync 的工作方式是先对比 Wazuh Indexer 中存储的内容 hash 与本地 hashhash 不同才拉取该 space 的完整内容并应用到 Engine 本地存储随后重建受影响的操作图。步骤三把规则中的列表查找改写为 decoder 阶段4.x 里规则用list field... lookup...引用 CDB 列表5.x 中这段逻辑移到 decoder用 KVDB 辅助函数写在check和normalize阶段。迁移文档给出了四类最常见模式。以下 YAML 示例中id: replace-with-a-new-uuidv4与metadata的author、date同样是占位符按上文说明替换。单列表 IP 检查address_match_key4.x 规则rule id110700 level10 if_groupjson/if_group list fieldsrcip lookupaddress_match_keyetc/lists/List-one/list descriptionIP blacklisted in LIST ONE/description grouplist1,/group /rule5.x decoder 等价写法name: decoder/ip-blacklist-list-one/0 id: replace-with-a-new-uuidv4 enabled: true parents: - decoder/json/0 metadata: title: IP blacklisted in LIST ONE description: Matches source IPs found in the list_one KVDB. author: ORGANIZATION/AUTHOR OF DECODER date: YYYY-MM-DD check: - source.ip: kvdb_match(list_one) normalize: - map: - wazuh.threat.groups: array_append(list1)允许名单检查not_match_keynot_match_key用于在字段值不在列表中时告警典型用途是标记来自允许名单之外用户或 IP 的事件。假设 CDB 允许名单为alice:、bob:、carol:三条注意 key 后带冒号表示值为空对应的 5.x decoder 用kvdb_not_match写在check阶段name: decoder/unauthorized-user-login/0 id: replace-with-a-new-uuidv4 enabled: true parents: - decoder/json/0 metadata: title: Login attempt from unauthorized user description: Flags login events from users not found in the authorized_users KVDB. author: ORGANIZATION/AUTHOR OF DECODER date: YYYY-MM-DD check: - source.user.name: kvdb_not_match(authorized_users) normalize: - map: - wazuh.threat.groups: array_append(auth)只有当source.user.name不是authorized_usersKVDB 中的 key 时该 decoder 才继续处理事件名单内的用户事件在check阶段就被拒绝。键值双重匹配match_key_valuematch_key_value要求 key 存在且其存储值匹配指定内容。5.x 的做法是在normalize的map块中用kvdb_get取回值再在一个后续块中对该值做过滤对应映射表里的normalizemapcheck。以 4.x 规则list fieldsrcip lookupmatch_key_value check_valuemalwareetc/lists/threat_types/list为例CDB 内容为1.2.3.4:malware、5.6.7.8:botnet时5.x decoder 示例name: decoder/ip-threat-type/0 id: replace-with-a-new-uuidv4 enabled: true parents: - decoder/json/0 metadata: title: Source IP threat-type lookup description: Enriches events with the threat type stored for the source IP in threat_types KVDB. author: ORGANIZATION/AUTHOR OF DECODER date: YYYY-MM-DD normalize: - map: - source.threat_type: kvdb_get(threat_types, $source.ip)文档说明第一个normalize块把 KVDB 值映射到source.threat_type随后的块只在值等于malware时继续处理。另注意一个行为细节失败的normalize块会被跳过而不会拒绝事件所以 key 不存在时 decoder 照常继续。跨两个列表的 AND 与 ORAND4.x 中通过if_sid串联规则、要求同时命中两个列表在 5.x 变成子 decoder 的 parent 指向第一个 decoder。第二个 decoder 的parents指向decoder/ip-blacklist-list-one/0只有 parent 已匹配时它才运行AND 语义由此保持name: decoder/ip-blacklist-both-lists/0 id: replace-with-a-new-uuidv4 enabled: true parents: - decoder/ip-blacklist-list-one/0 metadata: title: IP blacklisted in LIST ONE and LIST TWO description: Matches source IPs found in both list_one and list_two KVDBs. author: ORGANIZATION/AUTHOR OF DECODER date: YYYY-MM-DD check: - source.ip: kvdb_match(list_two) normalize: - map: - wazuh.threat.groups: array_append(list2)OR4.x 中两条彼此独立的规则各自检查一个列表、任一命中即告警在 5.x 用同一 parent 下的两个兄弟 decoder 表达每个 decoder 独立对满足自己check的事件触发。文档同时提醒了一个 OR 的行为差异Engine 按顺序评估兄弟 decoder 并跟随第一个匹配的。如果某个 IP 同时出现在两个列表里默认只有第一个 decoder 触发。需要两个标签都打上的话改用 AND父子模式在子 decoder 的normalize块里合并标签。子网CIDR条目的处理这是迁移中最常见的坑如果你的 CDB 列表含子网条目例如192.168.0.0/16:KVDB 没有等价能力。处理方式是在 decoder 的check阶段用显式的ip_cidr_match检查替代check: - ip_cidr_match/192.168.0.0/16/$source.ip如果单个 CDB 列表里混有精确 IP 和 CIDR 段必须拆成两部分精确 IP 放进 KVDB子网写成显式ip_cidr_match条目放在同一个check块中。ip_cidr_match检查字段中的 IP 是否属于给定 CIDR 范围不匹配或出错时求值为 false通常在check阶段使用见 辅助函数参考。验证迁移结果确认内容已同步到 EngineEngine 的日志写在 Wazuh manager 日志文件/var/wazuh-manager/logs/wazuh-manager.log中大多数 Engine 消息使用wazuh-manager-analysisd组件标签。上传 integration 和 KVDB 后观察下一次 CMSync 周期是否出现 Custom space 同步的记录若出现WARNING: [CMSync] Failed to synchronize namespace for space standard之类的上下文标签文档示例中为No available server说明同步未成功应先解决 Indexer 连通性问题再验证 decoder。确认 decoder 按预期接受或拒绝事件启用 trace 可以在不经过生产环境的情况下测试 Engine 如何处理一条具体事件trace 会以traces:形式按阶段输出每个资产的评估结果例如[] decoder/decoder-name/0 - success能直接看出新 decoder 在哪一步通过、在哪一步被拒。需要更详细的诊断时编辑/var/wazuh-manager/etc/wazuh-manager-internal-options.conf将analysisd.debug1设为 debug 级别0为默认 normal2为 tracetrace 输出量大仅在需要逐步跟踪单个事件时使用保存后重启wazuh-manager服务生效。KVDB 名称写错的典型现象辅助函数参考文档中的测试示例表明kvdb_match(non-existing-db)这类引用不存在 KVDB 的 check 会执行失败check was performed with errors。如果你在 trace 里看到引用 KVDB 的 check 以错误结束先核对 decoder 中db_name与 integration 里注册的 KVDB 是否一致、KVDB 是否已同步到位。已知限制迁移文档用一张表列出了 4.x 与 5.x 的行为差异改写规则前需要对照范围4.x CDB 行为5.x KVDB 行为子网匹配address_match_key/not_address_match_key支持 CIDR 记法无 KVDB 等价物每个子网改为 decodercheck阶段的显式ip_cidr_match精确 IP 与子网混合列表单个 CDB 文件可混放必须拆分精确 IP 进 KVDB子网写成ip_cidr_matchOR 且条目重叠两条独立规则各自触发兄弟 decoder 实现 OR但每个事件只有第一个匹配触发需要双标签时用父子AND模式规则层逻辑list可与match、regex、field并存于规则中所有条件移入单个 decoder 的check块KVDB 辅助函数与其他条件组合在同一个check数组中参考资料CDB 到 KVDB 迁移指南Engine 模块简介KVDB 说明Key Value DatabasesEngine 内容管理KVDB 辅助函数参考【免费下载链接】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 如何用 KVDB 替代 CDB 列表并重写规则查找？
Wazuh 5.x 如何用 KVDB 替代 CDB 列表并重写规则查找【免费下载链接】wazuhWazuh - The Open Source Security Platform. Unified XDR and SIEM protection for endpoints and cloud workloads.项目地址: https://gitcode.com/GitHub_Trending/wa/wazuh在 Wazuh 4.x 中规则通过存放在/var/ossec/etc/lists/下的 CDBConstant Database列表完成威胁数据查找升级到 Wazuh 5.0 后规则处理由新的 Engine 模块接管同样的查找用途改用 KVDBKey-Value Database实现。官方文档明确指出CDB 列表不会自动迁移——你必须把每个列表转换成 KVDB并把原来引用它的规则改写成 decoder 的check和map阶段。本文基于 Wazuh 仓库中的迁移文档给出从备份、转换、打包上传到验证的完整操作路径。适用的前提是你的 5.x 环境已经具备 Wazuh Indexer 与 Engine并且自定义内容decoder、integration、KVDB通过 Wazuh Indexer 管理而不是直接改 Engine 本地文件。迁移前需要理解的两点结构差异5.x 与 4.x 在列表查找上有两个直接影响改写方式的差异在 4.xCDB 查找出现在规则list标签和 decoder 中在 5.x所有 KVDB 查找都位于 decoder 中原来写在规则层的 CDB 查找逻辑必须移到处理这些事件的 decoder 里。CDB 列表没有定义 schema是/var/ossec/etc/lists/下的文件KVDB 是带显式content条目的 YAML 文档随 integration 打包、存储在 Wazuh Indexer 中并自动同步到 Engine。此外 5.x 的 decoder 由 XML 改为 YAML 定义decoder 树也允许一个 decoder 有多个 parent详见 Engine 模块简介。准备工作备份 CDB 列表与规则转换前先备份原有的 CDB 列表和规则文件。以下命令只读取并复制源文件到/tmp/cdb-migration不修改任何原文件sudo mkdir -p /tmp/cdb-migration cp -r /var/ossec/etc/lists /tmp/cdb-migration cp -r /var/ossec/etc/rules/ /tmp/cdb-migrationCDB lookup 类型到 5.x KVDB 辅助函数的映射迁移文档给出了逐条对应关系这是改写规则时的对照表CDBlookup类型5.x KVDB 辅助函数所在 decoder 阶段match_keykvdb_match(db_name)checknot_match_keykvdb_not_match(db_name)checkmatch_key_valuekvdb_get(db_name, $field) 对取回的值做过滤normalizemapcheckaddress_match_key精确 IPkvdb_match(db_name)checkaddress_match_key子网无直接等价物——改用ip_cidr_matchchecknot_address_match_key精确 IPkvdb_not_match(db_name)checknot_address_match_key子网无直接等价物check其中kvdb_match检查目标字段的值是否为指定 KVDB 中已存在的 keykvdb_not_match语义相反两者都只用于check阶段、不修改事件kvdb_get在map中取回 key 对应的值签名kvdb_get(db_name, key)。完整行为可查 KVDB 辅助函数参考。步骤一把 CDB 文件转换为 KVDB1. 编写 KVDB 骨架每个 KVDB 的骨架如下迁移文档示例。注意id、author、date处是占位符需要替换为你自己的值id换成一个新的 UUIDv4author换成你或你的组织名date用YYYY-MM-DD格式kvdbs: - id: replace-with-a-new-uuidv4 metadata: title: ips_list description: kvdb listing of ips author: ORGANIZATION/AUTHOR OF DECODER date: YYYY-MM-DD enabled: true content: # Here will go all your cdb key:value2. 逐条翻译 CDB 内容CDB 中的分隔符是:无空格KVDB 中 key 与 value 用标准 YAML mapping 的:分隔。例如 CDB 里的0x1:laptop 0x2:printer 0x3:1234对应 KVDB 的content: 0x1: laptop 0x2: printer 0x3: 1234KVDB 的值可以是任意 JSON 值字符串、数字、布尔、嵌套对象、数组这一点比 CDB 更宽泛。步骤二把 KVDB 打包进 integration 并上传KVDB 不能单独注册——它是integration的一部分integration 是 Engine 从 Wazuh Indexer 拉取内容的最小单元。创建一个 integration YAML引用该 KVDB 的 UUID 以及将使用它的 decoder 的 UUIDintegration 的kvdbs字段列出本 integration 的 decoder 使用的 KVDB UUID 列表decoders字段列出 decoder UUID。然后把 integration 和 KVDB 上传到 Wazuh Indexer 的Customspace。Engine 的内容管理器CMSync会在下一次同步周期检测到 Custom space 的变化并把 KVDB 推给 decoder 可用。Custom space 中用户自定义内容的管理方式见 Engine 内容管理章节。CMSync 的工作方式是先对比 Wazuh Indexer 中存储的内容 hash 与本地 hashhash 不同才拉取该 space 的完整内容并应用到 Engine 本地存储随后重建受影响的操作图。步骤三把规则中的列表查找改写为 decoder 阶段4.x 里规则用list field... lookup...引用 CDB 列表5.x 中这段逻辑移到 decoder用 KVDB 辅助函数写在check和normalize阶段。迁移文档给出了四类最常见模式。以下 YAML 示例中id: replace-with-a-new-uuidv4与metadata的author、date同样是占位符按上文说明替换。单列表 IP 检查address_match_key4.x 规则rule id110700 level10 if_groupjson/if_group list fieldsrcip lookupaddress_match_keyetc/lists/List-one/list descriptionIP blacklisted in LIST ONE/description grouplist1,/group /rule5.x decoder 等价写法name: decoder/ip-blacklist-list-one/0 id: replace-with-a-new-uuidv4 enabled: true parents: - decoder/json/0 metadata: title: IP blacklisted in LIST ONE description: Matches source IPs found in the list_one KVDB. author: ORGANIZATION/AUTHOR OF DECODER date: YYYY-MM-DD check: - source.ip: kvdb_match(list_one) normalize: - map: - wazuh.threat.groups: array_append(list1)允许名单检查not_match_keynot_match_key用于在字段值不在列表中时告警典型用途是标记来自允许名单之外用户或 IP 的事件。假设 CDB 允许名单为alice:、bob:、carol:三条注意 key 后带冒号表示值为空对应的 5.x decoder 用kvdb_not_match写在check阶段name: decoder/unauthorized-user-login/0 id: replace-with-a-new-uuidv4 enabled: true parents: - decoder/json/0 metadata: title: Login attempt from unauthorized user description: Flags login events from users not found in the authorized_users KVDB. author: ORGANIZATION/AUTHOR OF DECODER date: YYYY-MM-DD check: - source.user.name: kvdb_not_match(authorized_users) normalize: - map: - wazuh.threat.groups: array_append(auth)只有当source.user.name不是authorized_usersKVDB 中的 key 时该 decoder 才继续处理事件名单内的用户事件在check阶段就被拒绝。键值双重匹配match_key_valuematch_key_value要求 key 存在且其存储值匹配指定内容。5.x 的做法是在normalize的map块中用kvdb_get取回值再在一个后续块中对该值做过滤对应映射表里的normalizemapcheck。以 4.x 规则list fieldsrcip lookupmatch_key_value check_valuemalwareetc/lists/threat_types/list为例CDB 内容为1.2.3.4:malware、5.6.7.8:botnet时5.x decoder 示例name: decoder/ip-threat-type/0 id: replace-with-a-new-uuidv4 enabled: true parents: - decoder/json/0 metadata: title: Source IP threat-type lookup description: Enriches events with the threat type stored for the source IP in threat_types KVDB. author: ORGANIZATION/AUTHOR OF DECODER date: YYYY-MM-DD normalize: - map: - source.threat_type: kvdb_get(threat_types, $source.ip)文档说明第一个normalize块把 KVDB 值映射到source.threat_type随后的块只在值等于malware时继续处理。另注意一个行为细节失败的normalize块会被跳过而不会拒绝事件所以 key 不存在时 decoder 照常继续。跨两个列表的 AND 与 ORAND4.x 中通过if_sid串联规则、要求同时命中两个列表在 5.x 变成子 decoder 的 parent 指向第一个 decoder。第二个 decoder 的parents指向decoder/ip-blacklist-list-one/0只有 parent 已匹配时它才运行AND 语义由此保持name: decoder/ip-blacklist-both-lists/0 id: replace-with-a-new-uuidv4 enabled: true parents: - decoder/ip-blacklist-list-one/0 metadata: title: IP blacklisted in LIST ONE and LIST TWO description: Matches source IPs found in both list_one and list_two KVDBs. author: ORGANIZATION/AUTHOR OF DECODER date: YYYY-MM-DD check: - source.ip: kvdb_match(list_two) normalize: - map: - wazuh.threat.groups: array_append(list2)OR4.x 中两条彼此独立的规则各自检查一个列表、任一命中即告警在 5.x 用同一 parent 下的两个兄弟 decoder 表达每个 decoder 独立对满足自己check的事件触发。文档同时提醒了一个 OR 的行为差异Engine 按顺序评估兄弟 decoder 并跟随第一个匹配的。如果某个 IP 同时出现在两个列表里默认只有第一个 decoder 触发。需要两个标签都打上的话改用 AND父子模式在子 decoder 的normalize块里合并标签。子网CIDR条目的处理这是迁移中最常见的坑如果你的 CDB 列表含子网条目例如192.168.0.0/16:KVDB 没有等价能力。处理方式是在 decoder 的check阶段用显式的ip_cidr_match检查替代check: - ip_cidr_match/192.168.0.0/16/$source.ip如果单个 CDB 列表里混有精确 IP 和 CIDR 段必须拆成两部分精确 IP 放进 KVDB子网写成显式ip_cidr_match条目放在同一个check块中。ip_cidr_match检查字段中的 IP 是否属于给定 CIDR 范围不匹配或出错时求值为 false通常在check阶段使用见 辅助函数参考。验证迁移结果确认内容已同步到 EngineEngine 的日志写在 Wazuh manager 日志文件/var/wazuh-manager/logs/wazuh-manager.log中大多数 Engine 消息使用wazuh-manager-analysisd组件标签。上传 integration 和 KVDB 后观察下一次 CMSync 周期是否出现 Custom space 同步的记录若出现WARNING: [CMSync] Failed to synchronize namespace for space standard之类的上下文标签文档示例中为No available server说明同步未成功应先解决 Indexer 连通性问题再验证 decoder。确认 decoder 按预期接受或拒绝事件启用 trace 可以在不经过生产环境的情况下测试 Engine 如何处理一条具体事件trace 会以traces:形式按阶段输出每个资产的评估结果例如[] decoder/decoder-name/0 - success能直接看出新 decoder 在哪一步通过、在哪一步被拒。需要更详细的诊断时编辑/var/wazuh-manager/etc/wazuh-manager-internal-options.conf将analysisd.debug1设为 debug 级别0为默认 normal2为 tracetrace 输出量大仅在需要逐步跟踪单个事件时使用保存后重启wazuh-manager服务生效。KVDB 名称写错的典型现象辅助函数参考文档中的测试示例表明kvdb_match(non-existing-db)这类引用不存在 KVDB 的 check 会执行失败check was performed with errors。如果你在 trace 里看到引用 KVDB 的 check 以错误结束先核对 decoder 中db_name与 integration 里注册的 KVDB 是否一致、KVDB 是否已同步到位。已知限制迁移文档用一张表列出了 4.x 与 5.x 的行为差异改写规则前需要对照范围4.x CDB 行为5.x KVDB 行为子网匹配address_match_key/not_address_match_key支持 CIDR 记法无 KVDB 等价物每个子网改为 decodercheck阶段的显式ip_cidr_match精确 IP 与子网混合列表单个 CDB 文件可混放必须拆分精确 IP 进 KVDB子网写成ip_cidr_matchOR 且条目重叠两条独立规则各自触发兄弟 decoder 实现 OR但每个事件只有第一个匹配触发需要双标签时用父子AND模式规则层逻辑list可与match、regex、field并存于规则中所有条件移入单个 decoder 的check块KVDB 辅助函数与其他条件组合在同一个check数组中参考资料CDB 到 KVDB 迁移指南Engine 模块简介KVDB 说明Key Value DatabasesEngine 内容管理KVDB 辅助函数参考【免费下载链接】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），仅供参考