消息连接器 (Pro)

可用性： 消息连接器是一项测试版功能。请在功能标志页面启用 Messaging Connectors。由于警报是通过规则路由的，因此还必须启用 Rules Engine 2.0。

消息连接器可以将 DefectDojo 中的警报发送到聊天服务、电子邮件地址或 Amazon SNS 主题。它们与工单和事件管理连接器一起位于同一个 下游连接器 页面上，配置方式也相同：先创建一次连接，然后决定要向其发送哪些内容。

工单连接器和消息连接器解决的是不同的问题。工单连接器会创建并更新一个工单，用于随时间跟踪单个发现项。消息连接器则针对刚刚发生的事情发布一条消息，例如某次导入带来了新的高危和严重发现项。消息没有需要流转的状态，也没有需要保持同步的工单，因此两者是分开配置的，互不影响。

您可以发送的内容#

警报由规则引擎 2.0 负责路由。一条规则决定何时发送（触发条件）、哪些发现项符合条件（条件），以及消息发送到何处（即指向您的连接和频道的通知节点）。

这意味着警报可用的过滤条件与规则可用的过滤条件相同：严重程度、范围、标签、状态，以及规则条件能够表达的任何其他内容。发送到多个不同频道的多条不同警报，其实就是多条规则。

四种目标服务#

每种服务的设置方式都相同：在 连接 > 下游 下添加连接，然后创建一条指向该连接的警报。

设置 Slack 连接#

您需要一个带有机器人令牌的 Slack 应用。如果您的工作区中已经有为 DefectDojo 创建的应用，可以直接复用。

1. 创建 Slack 应用#

1. 访问 https://api.slack.com/apps，选择 Create New App，然后选择 From scratch。
2. 为应用命名（例如 DefectDojo），并选择它要发布消息的工作区。
3. 打开 OAuth & Permissions，添加以下 Bot Token Scopes（机器人令牌权限范围）：
   • chat:write（必需）：允许应用发布消息。
   • chat:write.public（可选）：允许应用无需先被邀请即可向任意公开频道发布消息。如果没有此权限范围，您必须将机器人邀请到每个要使用的频道中。
4. 选择 Install to Workspace，并批准该应用。
5. 复制 Bot User OAuth Token（机器人用户 OAuth 令牌）。它以 xoxb- 开头。

2. 在 DefectDojo 中添加连接#

1. 前往 连接 > 下游。
2. 在 Messaging（消息）区域中，找到 Slack 图块，选择 Add Configuration。
3. 输入以下信息：
   • Location（位置）：您的 Slack 工作区 URL，例如 https://your-workspace.slack.com。此项仅用于显示和链接。
   • Identifier（标识符）：用于将此连接与其他连接区分开的标签，例如 Security workspace。
   • Bot Token（机器人令牌）：您复制的 xoxb- 令牌。
4. 保存。DefectDojo 会立即向 Slack 验证该令牌，因此如果令牌错误或已被撤销，会在此处报告，而不是等到第一次触发警报时才发现。

您可以根据需要添加任意数量的 Slack 连接。要连接多个工作区，就需要创建多个独立的连接。

3. 查找频道 ID#

Slack 目标使用的是频道 ID，而不是频道名称。

1. 在 Slack 中打开该频道，点击顶部的频道名称。
2. 滚动到 About（关于）标签页的底部。
3. 复制 Channel ID（频道 ID）。其格式类似于 C0123456789。

如果应用没有 chat:write.public 权限范围，还需要将其邀请到该频道：在频道中输入 /invite @your-app-name。

设置 Microsoft Teams 连接#

Teams 使用的是 Power Automate 工作流 URL。传统的 Office 365 连接器已经停用，这种方式无需应用注册，也无需租户管理员同意：任何有权限访问该频道的人都可以创建工作流，并粘贴其返回的 URL。

一个连接只能发布到一个频道。 消息发送到哪里由工作流 URL 决定，因此要发送到第二个频道，需要建立第二个连接，而不是添加第二个目标。

1. 创建工作流#

1. 在 Teams 中打开要发布消息的频道，点击频道名称旁边的 … 菜单，然后选择 Workflows。
2. 选择 Post to a channel when a webhook request is received（收到 Webhook 请求时发布到频道）模板。
3. 确认团队和频道，然后选择 Add workflow。
4. 复制该工作流提供给您的 URL。这是一个较长的 https:// 地址，位于 Microsoft Power Automate 主机上。

请将此 URL 当作密码对待。任何持有该 URL 的人都可以向该频道发布消息。

2. 在 DefectDojo 中添加连接#

1. 前往 连接 > 下游。
2. 在 Messaging 区域中，找到 Microsoft Teams 图块，选择 Add Configuration。
3. 输入以下信息：
   • Location：您的 Teams 或 Microsoft 365 URL。此项仅用于显示和链接。
   • Instance Label（实例标签）：为此连接所指向的频道命名的标签，例如 Security / Alerts。
   • Workflow URL（工作流 URL）：您复制的 URL。
4. 保存。

DefectDojo 在保存时会检查该 URL 的格式（必须是 https:// 协议且位于 Microsoft 工作流主机上），但不会向其发布消息。工作流 URL 除了实际发送消息之外没有其他测试方式，而在保存时就在频道中意外弹出一条消息，比事后才发现问题更糟。准备好后，请使用 Send test message（发送测试消息）。

Teams 目标只有一个可选字段，即频道标签，它仅用于标记投递记录。真正决定目标的是工作流 URL。

设置电子邮件连接#

电子邮件不需要任何凭据。DefectDojo 会通过该实例已用于发送通知的邮件服务器发送消息，因此无需新增配置，也不存在第二处可能出错的 SMTP 设置。

1. 前往 连接 > 下游。
2. 在 Messaging 区域中，找到电子邮件图块，选择 Add Configuration。
3. 输入以下信息：
   • Location：要显示的发件人身份，例如 mailto:defectdojo@example.com。
   • Instance Label：用于将此连接与其他连接区分开的标签。
4. 保存。

如果该实例未配置邮件服务器或发件人地址，保存将会失败，因为通过该连接发送的任何内容都无法真正发出。请先在 设置 > 系统设置 中配置 SMTP。

收件人是在警报上设置的，而不是在连接上设置的，因此一个电子邮件连接可以服务于所有警报。一个电子邮件目标最多支持 50 个地址；超出此数量时，请使用群发地址。

设置 Amazon SNS 连接#

SNS 与前面三种服务在本质上不同：DefectDojo 只向一个主题发布一条消息，由 AWS 将其分发给所有订阅方，订阅方可能是电子邮件地址、短信号码、Lambda 函数、HTTPS 端点或 SQS 队列。DefectDojo 并不知道也不关心具体是哪一种。

1. 创建具有发布权限的访问密钥#

1. 在 AWS 控制台中，为 DefectDojo 创建（或选择）一个 IAM 用户或角色。
2. 附加一个允许对您打算使用的主题执行 sns:Publish 的策略。明确指定主题 ARN 比允许所有主题更好。
3. 为其创建一个访问密钥，并复制密钥的两部分。AWS 只会显示一次 Secret Access Key。

如果该主题使用 KMS 密钥加密，同一主体还需要对该密钥拥有 kms:GenerateDataKey 和 kms:Decrypt 权限，否则每次发布都会被拒绝。

2. 在 DefectDojo 中添加连接#

1. 前往 连接 > 下游。
2. 在 Messaging 区域中，找到 Amazon SNS 图块，选择 Add Configuration。
3. 输入以下信息：
   • Location：仅用于显示和链接的 URL，例如您的 AWS 控制台 URL。
   • Instance Label：用于将此连接与其他连接区分开的标签，例如 Production AWS account。
   • Access Key ID（访问密钥 ID）：密钥 ID，格式类似于 AKIAIOSFODNN7EXAMPLE。
   • Secret Access Key（秘密访问密钥）：密钥的秘密部分。
4. 保存。

DefectDojo 会立即向 AWS 验证该凭据，因此如果密钥错误或已被删除，会在此处报告，而不是等到第一次触发警报时才发现。该检查仅确认凭据本身有效；至于它是否有权向某个特定主题发布消息，则会在您设置目标时进行检查。

无需填写区域。 区域信息已包含在主题 ARN 中，因此一个连接可以向多个区域中的主题发布消息，也不存在与 ARN 相冲突的第二个设置项。

3. 查找主题 ARN#

SNS 目标使用的是主题的 ARN。

1. 在 SNS 控制台中打开该主题。
2. 从页面顶部复制 ARN。其格式类似于 arn:aws:sns:us-east-1:123456789012:security-alerts。

与 Teams 的工作流 URL 不同，ARN 并不是一个秘密：它只是标识一个主题，向该主题发布消息仍需要连接上的凭据。这也是为什么一个 SNS 连接可以服务于多个主题。

不支持 FIFO 主题（ARN 以 .fifo 结尾）。此类主题需要消息组和去重 ID，这些是排序规则，而警报无法提供这些信息。请使用标准主题。

发送测试消息#

在任何配置了消息目标的地方，Send test message（发送测试消息）都会通过与真实警报完全相同的路径投递一条简短消息，并报告目标服务返回的结果。

使用它来确认那些容易出错的地方：对 Slack 而言，确认频道 ID 是否正确、机器人是否能够在该频道发布消息；对 Teams 而言，确认工作流 URL 是否仍然有效；对电子邮件而言，确认地址是否可达；对 SNS 而言，确认密钥是否有权向该主题发布消息。目标服务返回的原始信息会直接透传，因此如果 Slack 机器人尚未被邀请，看到的会是提示您邀请机器人的消息，而不是一个笼统的失败提示。

成功的测试还会清除因自动禁用而被停用的连接（参见连接失效时）。

创建警报#

有两种创建方式，最终产生的都是同一样东西：一条规则引擎 2.0 规则。

警报页面#

这是较为简便的方式，适用于最常见的场景：通报某次导入中新增的发现项。

1. 前往 连接 > 下游，在某个消息连接上选择 Create Alert，或者直接打开 Messaging Alerts（消息警报）。
2. 选择 New Alert（新建警报），并填写以下内容：
   • Name（名称）：说明该警报的用途，例如 New highs to the security channel。
   • Alert（警报类型）：说明该警报针对的内容。目前唯一可选项是 New findings from an import（导入产生的新发现项）。
   • Send over（发送渠道）：所使用的消息连接。
   • Where it delivers（投递位置）：目标服务自身的字段，即 Slack 频道 ID、可选的 Teams 频道标签、电子邮件地址列表，或 SNS 主题 ARN。
   • Severity（严重程度）：下限设置，从 Critical only（仅严重）到 Every severity（所有严重程度）。
   • Mode（模式）：Simulate（模拟）只记录本应发送的内容而不实际发送，Live（实时）则会真正发送。
3. 选择 Create Alert。

该页面会列出已创建的警报，包括触发条件、严重程度下限，以及用于启用或禁用各条警报的开关。

如果想在任何频道实际收到消息之前先看看某条警报会捕获哪些内容，可以先从 Simulate 模式开始。规则照常运行，投递记录照常生成，但不会实际发送任何内容。

警报本质上就是规则，因此也可以在同一个列表中通过规则编辑器打开。一旦某条规则被编辑成表单无法表达的形式，例如增加了第二个分支或第二条消息，列表会转而提供规则编辑器，而不是用一个会悄悄抹平这些额外内容的表单来处理。

规则编辑器#

这是完整的方式，适用于表单未覆盖的一切情况。

1. 前往 自动化 > 规则引擎 2.0，创建一条规则。
2. 添加一个触发条件。若要针对新导入的发现项发出警报，请使用发现项事件触发器，触发条件为 created（已创建）。导入是批量进行的，因此一次导入只会产生一条警报，而不是每个发现项各产生一条。
3. 添加符合条件的判断规则，例如最低严重程度为高。
4. 为所需的目标服务添加消息节点（Send a Slack Message、Send a Microsoft Teams Message、Send an Email，或 Publish to an SNS Topic），并设置：
   • Connection（连接）：您所创建的消息连接。
   • Destination（目标）：目标服务对应的目标信息，即 Slack 的频道 ID、Teams 的可选频道标签、电子邮件的收件人，或 SNS 的主题 ARN。
5. 保存并启用该规则。

如果没有发现项符合条件，则不会发送任何内容，因此如果一条规则设置为只针对高危及以上的发现项，那么当某次导入只带来低危发现项时，该规则会保持静默。

在消息连接器出现之前编写的规则#

消息节点只能通过连接发送消息，别无他法。此前，如果没有选择连接，Slack、Teams 和电子邮件节点会回退使用 设置 > 通知 下的实例级设置，现在已不再如此。

以这种方式编写的规则仍会继续运行，但其消息节点会记录一条被跳过的投递，说明该节点未指定连接。要修复此问题，请打开该规则，在节点上选择连接和目标，然后保存。一旦节点指定了连接，此前已记录的投递即可从投递列表中重新发送。

连接是每个消息节点的必填字段，因此规则编辑器会要求先指定连接，才能保存规则。

连接失效时#

机器人令牌被撤销、工作流被删除，或 AWS 访问密钥被删除，都会导致其所服务的每一条警报失败。DefectDojo 不会为每个事件重复记录相同的失败，而是按目标统计连续的凭据失败次数，并在达到一定次数后停止发送。该连接会报告哪个目标被禁用以及原因。

要恢复：先修复凭据（重新安装 Slack 应用并粘贴新令牌、重新创建 Teams 工作流并粘贴新 URL，或创建新的 AWS 访问密钥），然后向该目标发送一条测试消息，成功后即可重新启用该目标，或者直接使用重新启用操作。

只有凭据失败才会触发这种情况。如果消息因为 Slack 频道 ID 错误、机器人未被邀请、电子邮件地址不存在，或 IAM 策略不允许向某个主题发布消息而被拒绝，都不会导致禁用，因为凭据本身没有问题，只需更正目标或策略即可立即恢复正常。

警报与通知并存#

消息连接器并不会取代通知功能。设置 > 通知 下的实例级 Slack、Teams 和电子邮件设置、个人通知，以及通知矩阵，都会按原有配置继续正常工作。它们负责通报 DefectDojo 自身的事件，而消息连接器则是您所编写的规则用来发送消息的渠道。

需要注意的一点是：如果某条警报发布到的频道或地址，与实例级设置已经通报的频道或地址相同，该目标会同时收到两条消息。对于同一个目标，请只配置其中一种方式。

限制#

• 目前尚不支持自定义消息文案。警报使用 DefectDojo 内置的文案。
• 消息是单向的。DefectDojo 不会读取回复，消息中也没有按钮或其他交互元素。
• 不支持消息串、消息编辑，以及向单个用户发送私信。个人通知仍继续使用现有的通知系统。
• 一个 Teams 连接只能到达一个频道，因为频道是由工作流 URL 决定的。
• SNS 消息为纯文本格式。一个主题可以同时分发给电子邮件、短信、Lambda 和 HTTPS 订阅方，没有一种格式能同时适配所有这些方式，因此系统也不会针对每种协议单独发布不同版本。
• 不支持 SNS FIFO 主题。
• 目前尚不支持发送报告或其他附件。警报只是带有指向 DefectDojo 链接的消息。
• 警报页面仅覆盖导入产生的新发现项这一场景，其他情况都需要在规则编辑器中构建。