从 integratord 迁移到 Wazuh 5.x Dashboard 通知Notifications 与 Alerting 插件迁移实战指南【免费下载链接】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 中由integratord守护进程驱动的第三方告警集成Slack、PagerDuty、Jira、Shuffle 等详细讲解其在 Wazuh 5.x 中被Notifications通知渠道管理与Alerting监控与告警动作两个 Dashboard 插件完全取代后的迁移路径。读完本文你将掌握integration配置块的逐字段映射方法、Dashboard 渠道与监控的完整配置流程、动态消息模板的编写方式以及 Maltiverse、Virustotal 等双向增强型集成为何无法迁移及其替代方案。迁移背景为什么 4.x 的 integratord 架构会被取代在 Wazuh 4.x 中第三方集成直接在 Manager 的ossec.conf中通过integration块配置由integratord守护进程负责把告警推送到 Slack、PagerDuty 等外部服务。每个integration块声明一个外部服务、认证凭据与告警过滤条件如规则 ID、告警级别、分组并在告警命中时调用对应脚本完成推送。Wazuh 5.x 用两个 Dashboard 插件取代了这一整套机制Notifications统一管理第三方服务的共享渠道Channel与连接设置Webhook URL、请求头、认证信息。Alerting创建监控Monitor对索引中的数据进行查询扫描并在触发器条件满足时通过渠道发送消息。所有集成配置现在全部在 Dashboard 上完成无需再修改ossec.conf。⚠️ 注意Notifications 插件不支持Maltiverse、Virustotal 这类双向bi-directional集成——它们在 4.x 中由integratord支持详见后文 增强型集成Enrichment的处理。说明本次迁移必须手动完成。目前没有自动工具能把ossec.conf中的integration块直接转换为 Wazuh 5.x 的 Dashboard 配置。从源码结构看当前仓库Wazuh 5.x的src/目录中已不存在integratord守护进程相关的 4.x 集成测试工作流仍保留在 .github/workflows/4_testintegration_integratord-tier-0-1.yml 中仅用于 4.x 兼容分支的回归验证。这印证了 integratord 已从 5.x 核心架构中移除。配置映射4.xintegration字段 → 5.x Dashboard下表将 Wazuh 4.x 的每个integration字段映射到 5.x Dashboard 中的对应位置4.x 字段5.x 插件5.x 位置说明nameNotificationsChannel name用于标识渠道hook_urlNotificationsWebhook URL部分 4.x 内置脚本如 PagerDuty端点被硬编码在脚本中不需要该字段api_keyNotificationsWebhook URL / Headers取决于服务类型凭据可能放在 URL、请求头中或完全不需要alert_format—无对应项取决于渠道中配置的消息格式rule_idAlertingMonitor query监控基于索引模式index pattern上的查询而非规则匹配对应字段为wazuh.rule.idlevelAlertingMonitor query4.x 中为rule.level见下方说明groupAlertingMonitor query原分组标签指生成数据的内部 Wazuh 组件现用wazuh.integration.name表示event_locationAlertingMonitor query4.x 标签用 sregex 表达式匹配 Wazuh 模块或日志源/文件5.x 无直接对应见下方说明optionsAlertingTrigger → Action message见下文专项说明说明在 5.x 中rule.level更名为wazuh.rule.level且值从 0–16 的整数改为分类值low、medium、high。由于没有直接换算关系你必须重新审查现有告警阈值结合组织自身的路由需求决定如何把历史数值级别映射到新分类。说明event_location标签在 5.x 中没有一一对应的替代字段。5.x 将告警解析为高度结构化文档旧的location字段被拆分为多个独立字段。你需要审查现有使用场景确定哪些 5.x 字段如wazuh.protocol.location、file.path、wazuh.agent.name等最贴合你的实现。上图展示了 5.x Alerting 监控中 Index 模式选择与多查询Query条件配置界面对应 4.x 中rule_id、level、group等过滤条件在 5.x 中的落点。从options到触发器动作在 4.x 中options块允许用户以JSON 字符串自定义脚本行为集成脚本会读取该 JSON 并应用自定义行为。在 5.x 中这一概念被彻底取代为Alerting监控触发器的通知动作中定义的消息message通知渠道 URL 中的查询参数query parameters通知渠道中的请求头参数header parameters。通知渠道应按预期类型支持并管理行为自定义。从配置一开始你就对外部集成发送的结构和内容拥有100% 的控制权。上图展示了 5.x Alerting 中触发器名称、严重级别、触发条件与动作Action即通知消息的配置界面是 4.xoptions自定义行为在 5.x 中的最终落点。用例映射在 4.x 中每个用例可能包含多个integration块并搭配不同脚本自定义集成无内置脚本也支持自备脚本。下表将部分 4.x 配置示例映射到 5.x 等价物4.x 配置形态5.x 等价物一个integration块 一个脚本一个渠道channel一个监控monitor每个过滤器对应一个查询query只有一个触发器trigger多个integration块认证与端点相同、过滤器不同且都使用同一脚本一个渠道一个监控含多个查询每个integration块对应一个触发器多个integration块面向不同服务、但过滤器相同每个服务一个渠道一个监控含一个触发器、每个服务一个动作且各自携带不同的消息负载5.x 插件提供了显著更灵活的配置模型。一次典型的迁移结果是每个外部服务一个渠道一个或多个监控组合查询与触发器以覆盖此前全部integration块。Wazuh 4.x 参考配置示例以下是 Wazuh 4.x 的一组配置可作为迁移步骤的参照。该配置声明了 6 个integration块涵盖 Slack、PagerDuty、自定义 Webhook、自定义 Jira 脚本、Virustotal 与 Maltiverseossec_config integration nameslack/name hook_urlYOUR_SLACK_WEBHOOK/hook_url rule_id10002/rule_id alert_formatjson/alert_format /integration integration namepagerduty/name api_keyYOUR_INTEGRATION_KEY/api_key level14/level alert_formatjson/alert_format /integration integration namecustom-webhook/name hook_urlWEBHOOK_URL/hook_url api_keyAPI_KEY/api_key level8/level alert_formatjson/alert_format /integration integration namecustom-jira/name groupsyscheck/group level9/level hook_urlYOUR_JIRA_HOOK_URL/hook_url api_keyEMAIL:API_KEY/api_key alert_formatjson/alert_format /integration integration namevirustotal/name api_keyYOUR_API_KEY/api_key groupsyscheck/group level10/level alert_formatjson/alert_format /integration integration namemaltiverse/name hook_urlhttps://api.maltiverse.com/hook_url api_keyYOUR_API_KEY/api_key level5/level alert_formatjson/alert_format /integration /ossec_config说明Jira 在 4.x 中是一个没有默认脚本的集成。下方给出创建custom-jira脚本的完整过程这是理解 4.x 集成脚本机制的关键示例也是 5.x 消息模板设计的对照基础。创建 Wazuh 4.x 的 custom-jira 脚本1. 在/var/ossec/integrations/custom-jira创建脚本文件#!/var/ossec/framework/python/bin/python3 import sys import json import requests from requests.auth import HTTPBasicAuth # 读取配置参数 alert_file open(sys.argv[1]) user sys.argv[2].split(:)[0] api_key sys.argv[2].split(:)[1] hook_url sys.argv[3] # 读取告警文件 alert_json json.loads(alert_file.read()) alert_file.close() # 提取 issue 字段 alert_level alert_json[rule][level] ruleid alert_json[rule][id] description alert_json[rule][description] agentid alert_json[agent][id] agentname alert_json[agent][name] path alert_json[syscheck][path] # 设置项目属性 运行前需手动配置 project_key YOUR_PROJECT_SPACE_KEY # 可从 issue key 开头获取例如 issue WS-5018 的 key 为 WS issuetypeid 10003 # 可查 Atlassian 文档或通过 API 端点获取 # 生成请求 headers {content-type: application/json} issue_data { update: {}, fields: { summary: FIM alert on [ path ], issuetype: { id: issuetypeid }, project: { key: project_key }, description: { version: 1, type: doc, content: [ { type: paragraph, content: [ { text: - State: description \n- Rule ID: str(ruleid) \n- Alert level: str(alert_level) \n- Agent: str(agentid) agentname, type: text } ] } ], }, } } # 发送请求 response requests.post(hook_url, datajson.dumps(issue_data), headersheaders, auth(user, api_key)) print(json.dumps(json.loads(response.text), sort_keysTrue, indent4, separators(,, : ))) # --- 调试时可取消注释 sys.exit(0)2. 设置正确的权限chmod 750 /var/ossec/integrations/custom-jira chown root:wazuh /var/ossec/integrations/custom-jira3. 在ossec.conf中添加引用脚本名custom-jira的integration块。这个 4.x 脚本揭示了迁移的本质脚本中硬编码的项目 Key、issue 类型 ID、告警字段提取逻辑与请求头在 5.x 中全部转移到了Notifications 渠道配置Webhook URL、Headers与Alerting 动作消息模板Mustache 变量中无需再维护独立的 Python 脚本文件。迁移步骤在 5.x Dashboard 中重建集成以下步骤演示迁移上述 4.x 参考配置的一种可行路径请以此为指导并根据自身需求调整。步骤 1配置 Notifications 渠道进入Explore Notifications Channels。1.1 使用默认渠道Wazuh 自带一组预配置渠道默认处于静音muted状态。使用前先取消静音并填入所需凭据每个渠道都附带简短的配置说明。本例既可使用默认渠道也可以从头新建渠道见 1.2 自定义 Webhook 渠道。示例 — PagerDuty 渠道取消渠道静音。编辑渠道把 4.x 配置中的api_key填入Webhook headers下的X-Routing-Key字段。可选更新渠道名称与描述。示例 — Jira 渠道取消渠道静音。编辑渠道把 4.x 配置中的hook_url填入Webhook URL。4.x 中api_key的结构为email:token5.x 中需先将该字符串编码为 base64然后在Webhook headers下的Authentication请求头中设置为Basic encodedString。说明PagerDuty 与 Jira 示例将在 步骤 2 中继续。1.2 自定义 Webhook 渠道4.x 为Slack、PagerDuty、Shuffle、Maltiverse、Virustotal提供了内置脚本5.x 则为Slack、PagerDuty、Shuffle、Jira提供了预配置渠道。⚠️ 警告Maltiverse、Virustotal及其他双向或威胁增强型集成无法迁移到 Notifications 插件详见 增强型集成Enrichment的处理。对于 4.x 中的其他自定义集成请使用以下渠道类型之一新建渠道。1.2.1 默认渠道类型Wazuh 5.x 为Slack、Chime、Email等常见服务提供了专用渠道类型可简化配置——例如Chime仅需一个 Webhook URL。1.2.2 自定义 Webhook 渠道类型对于没有专用渠道类型的集成请使用Custom webhook类型。这也是 Wazuh 提供的PagerDuty、Jira、Shuffle渠道底层所使用的类型。自定义 Webhook 渠道可服务于Slack、Chime等服务——当你想给Slack发送 JSON 负载而非纯文本时尤其有用见 触发器动作Actions。自定义 Webhook 渠道支持方法PUT、POST或PATCH端点定义Webhook URL 或带查询参数的自定义 URL自定义请求头如Authorization、Content-Type示例 — 从头创建 PagerDuty 渠道创建自定义渠道前务必先明确目标并参考外部服务的官方文档获取配置请先完成 PagerDuty 账户、服务与集成的配置。本例创建的渠道将用于在 PagerDuty 上触发事件创建。将渠道Name设为PagerDuty Channel若已有同名渠道可改为PagerDuty Incident Channel。为渠道创建描述可选。在Channel type选择器中选中Custom webhook。根据 PagerDuty 文档选择POST作为Method。PagerDuty V2 Events API使用通用端点无需自定义属性选择Webhook URL。填入文档中的端点地址https://events.pagerduty.com/v2/enqueue创建请求头Key为X-Routing-KeyValue为你的集成 Key。创建渠道。实现提示PagerDuty 公开文档将routing_key定义为必填字段但也可以用X-Routing-Key请求头替代即使未在其公开文档中列出。这样更简洁——用户无需在每个发送给 PagerDuty 的监控消息中携带routing_key参数。步骤 2使用 Alerting 插件创建一个或多个监控渠道配置完成后创建监控来查询数据并通过渠道发送消息。进入Explore Alerting Create Monitor。2.1 基础配置监控定义索引、调度以及查询/触发器/动作结构。由于单个监控支持多个查询、触发器与动作基础配置决定了你需要一个还是多个监控。示例 — 安全监控可复用于 PagerDuty、Slack、Jira 与 Shuffle字段值Monitor nameSecurity MonitorMonitor typePer document monitorScheduleBy interval — every 1 minuteIndex patternwazuh-findings-v5-security2.2 查询Queries单个监控可包含多个查询。为 4.x 中的每个过滤条件创建一个查询。PagerDuty 示例查询在 PagerDuty 示例中原始的level14/level没有直接对应项见 配置映射表。本例使用high值。字段值Query namehigh_security_findingFieldwazuh.rule.levelOperatorisValuehighJira 示例查询在 Jira 示例中原始的groupsyscheck/group是与 FIM文件完整性监控相关规则的分组因此映射为wazuh.integration.name等于wazuh-fimlevel9/level的映射见配置映射表本例使用medium值。字段值Query namemedium_security_findingFieldwazuh.rule.levelOperatorisValuemedium字段值Query namefim_integrationFieldwazuh.integration.nameOperatorisValuewazuh-fim2.3 触发器Triggers一个监控可以有多个触发器每个触发器可引用多个查询。PagerDuty 示例触发器字段值Trigger nameHigh level threatSeverity level1 (Highest)Trigger conditionshigh_security_finding来自 2.2 的查询Jira 示例触发器字段值Trigger nameMedium level threatSeverity level3 (Medium)Trigger conditionsmedium_security_finding AND fim_integration来自 2.2 的查询2.4 动作Actions每个触发器可以有多个动作从而让一个触发器同时通知多个渠道。说明下面 PagerDuty 与 Jira 的示例消息都是 JSON 负载但并非总是如此——例如使用Slack default channelWazuh 用 Slack 通知类型创建时消息会解析为纯文本而非 JSON。这也由自定义 Webhook 中的Content Type请求头决定。PagerDuty 示例动作添加新通知。将Action name设为PagerDuty Incident。将Channel设为PagerDuty Channel。将Message设为下方负载。发送测试消息——你应该能在 PagerDuty 账户中看到测试事件。⚠️ 警告消息负载必须匹配接收端集成期望的格式。如果格式不正确外部侧不会出现任何事件。发送前请查阅各集成的 API 文档。以下负载复刻了 4.x 默认 PagerDuty 脚本发送的内容{ event_action: trigger, payload: { summary: Wazuh Alert: {{ctx.alerts.0.sample_documents.0._source.event.original}}, source: {{ctx.alerts.0.sample_documents.0._source.wazuh.agent.name}}, severity: critical, custom_details: { Rule ID: {{ctx.alerts.0.sample_documents.0._source.wazuh.rule.id}}, Rule Level: {{ctx.alerts.0.sample_documents.0._source.wazuh.rule.level}}, Agent OS: {{ctx.alerts.0.sample_documents.0._source.wazuh.agent.host.os.name}}, File Path: {{ctx.alerts.0.sample_documents.0._source.file.path}}, Monitor Name: {{ctx.monitor.name}} } } }上图展示了迁移完成后 PagerDuty 上触发的事件状态为 Triggered标题含 Wazuh 告警摘要验证 5.x 通知链路已成功打通。Jira 示例动作添加新通知。将Action name设为Jira task ticket。将Channel设为Jira Channel。将Message设为下方负载。发送测试消息——你的 Jira 项目中应已创建任务。⚠️ 警告请将YOUR_PROJECT_SPACE_KEY替换为 Jira 项目详情中的空间 Key4.x 中直接配置在脚本里issue ID 同理——本例中10003对应 task 类型但你的项目可能不同请相应修改。以下负载是创建任务的示例{ fields: { project: { key: YOUR_PROJECT_SPACE_KEY }, issuetype: { id: 10003 }, summary: FIM alert on [{{ctx.alerts.0.sample_documents.0._source.file.path}}], description: { version: 1, type: doc, content: [ { type: paragraph, content: [ { type: text, text: - State: {{ctx.alerts.0.sample_documents.0._source.wazuh.rule.title}}\n- Rule ID: {{ctx.alerts.0.sample_documents.0._source.wazuh.rule.id}}\n- Alert level: {{ctx.alerts.0.sample_documents.0._source.wazuh.rule.level}}\n- Agent: {{ctx.alerts.0.sample_documents.0._source.wazuh.agent.id}} {{ctx.alerts.0.sample_documents.0._source.wazuh.agent.name}} } ] } ] } } }上图展示了 Wazuh 告警同步到 Jira 后创建的任务标题为 “FIM alert on [...]”描述含规则 ID、告警级别、代理等字段对应 4.xcustom-jira脚本在 5.x 中的等价实现。对比两个负载与 4.x 的custom-jira脚本可以发现原先在 Python 中通过alert_json[rule][level]、alert_json[agent][id]等硬编码提取的字段现在全部改为{{ctx.alerts.0.sample_documents.0._source.xxx}}形式的 Mustache 变量由监控上下文动态注入无需任何脚本代码。编写动态消息负载时可参考Mustache 模板语法{{variable}}双花括号插值OpenSearch Alerting 文档中的 Monitor 变量、Trigger 变量与 Action 变量这些变量体系为构建复杂的动态负载提供了完整的上下文来源如告警样本文档、监控名称、触发器信息等。增强型集成Enrichment的处理在 4.x 中Maltiverse和Virustotal以双向回调循环的方式工作内置脚本把告警发送到外部服务接收增强后的响应再作为新告警重新注入 Wazuh。5.x 中不存在等价机制——这些集成无法迁移。增强功能如今在事件到达索引器之前由 Engine 在事件处理管线内联完成。从仓库源码可以验证这一结论引擎的增强构建器实现位于 src/engine/source/builder/src/builders/enrichment/enrichment.hpp其中getGeoEnrichmentBuilder与getIocEnrichmentBuilder分别对应两类内置增强插件。Geo 增强的字段映射配置见 src/engine/ruleset/schemas/enrichment-geo.json覆盖client.ip、source.ip、destination.ip、host.ip等 IP 字段到 AS自治域与 Geo 信息的映射。IOC 增强的字段映射配置见 src/engine/ruleset/schemas/enrichment-ioc.json涵盖hash_md5、hash_sha1、hash_sha256、url_domain、url_full以及连接级 IP/端口组合的 IOC 查询来源。引擎文档 docs/ref/modules/engine/README.md 中的 “Security enrichment process” 一节进一步说明管线先执行Pre-enrichment空间标注、丢弃事件过滤、解码临时变量清理再进入Enrichment阶段按策略顺序应用 Geo 与 IOC 增强。Engine 恰好只提供两个内置增强插件Geo/ASN 与 IOC且无法扩展自定义第三方服务。因此4.x 中依赖 Maltiverse、Virustotal 外部 API 做情报查询的用例在 5.x 中应改用引擎内置的 IOC 增强能力数据来自本地维护的威胁情报库并将告警联动需求改由 Alerting 插件与 Notifications 渠道实现。完成渠道与监控的创建和测试后你就成功迁移了 4.x 的 integratord 配置。总结一下完整迁移路径用 Notifications 插件为每个外部服务创建/启用渠道迁移hook_url、api_key与认证信息用 Alerting 插件创建监控把rule_id、level、group等过滤条件转换为索引查询用触发器 动作把options脚本行为转换为可动态取值的消息负载对 Maltiverse、Virustotal 等双向集成改由 Engine 内置增强能力替代并通过测试验证新的通知链路。【免费下载链接】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），仅供参考