节点参考 (Pro)
注意：Rules Engine 2.0 是 DefectDojo Pro 专属功能。
Rules Engine 2.0 内置了分为四大类的 25 个节点。本页对它们逐一进行说明。
除非另有说明，每个节点都接受一个输入，产生一个名为 out 的输出，并将其收到的每一项都传递给该输出。这一点在你串联多个节点时很重要：一个发现项节点会先修改该发现项，然后再将其向后传递，因此依次排列的多个此类节点都会依次生效。
触发器
每张图中都有且仅有一个触发器，也只有触发器才能启动一次运行。三种触发器都会产生发现项，并且都带有一个范围设置，用来限定它们产生哪些发现项。范围的具体工作方式参见构建规则。
发现项事件
trigger.finding
当发现项被创建、更新、关闭或重新打开时运行。
| 设置 | 默认值 | 说明 |
|---|---|---|
| 事件 | created | 触发该规则的发现项变化类型：created、updated、closed、reopened，或用 any 表示以上四种全部。 |
| 范围 | 空 | 该规则所考虑的发现项范围。留空表示规则所有者可见的所有发现项。 |
事件所指定的发现项，在进入图之前会先与范围进行匹配，因此事件决定何时触发，范围决定触发哪些对象。
按计划
trigger.schedule
按照计划扫描范围内的所有发现项。该计划在规则上配置，且只能设置为整刻钟（每 15 分钟）的时间点。
| 设置 | 默认值 | 说明 |
|---|---|---|
| 范围 | 空 | 该规则所考虑的发现项范围。 |
手动运行
trigger.manual
当你在规则上点击运行时，扫描范围内的所有发现项。
| 设置 | 默认值 | 说明 |
|---|---|---|
| 范围 | 空 | 该规则所考虑的发现项范围。 |
逻辑
条件判断 / 过滤
filter.if
根据条件，将每一项路由到真或假分支。这是唯一一个拥有两个输出的节点，也是图实现分支的方式。
| 设置 | 默认值 | 说明 |
|---|---|---|
| 条件 | 空 | 每一行由一个路径、一个运算符和一个值组成。参见条件。 |
| 匹配 | all | 是要求所有条件都成立（all），还是只需其中一个成立（any）。 |
空的条件列表会让所有项都进入真分支。两个分支都是可选的：如果不连接假分支，未通过条件的项就会被直接丢弃。
限制数量
flow.limit
只放行前 N 项，其余全部丢弃。在测试规则时可以用作安全阀，也可以用来限制单次运行最多产生多少个工单或消息。
| 设置 | 默认值 | 说明 |
|---|---|---|
| 保留前几项 | 100 | 要放行的项目数量。 |
在单次运行内去重
flow.dedupe_batch
对于同一个键，只保留第一项，之后携带相同键的项一律丢弃。该去重范围限定在单次运行内，因此只在一次执行内部去重，不会跨多次执行去重。
| 设置 | 默认值 | 说明 |
|---|---|---|
| 键路径 | finding.hash_code | 用于判定重复项的字段路径。 |
一个常见用法是使用 finding.component_name，从而按受影响的组件而不是按发现项逐一通知。
发现项
这些节点会修改发现项。每一次修改都会被追溯到进行该修改的规则、运行和节点，并显示在该发现项的溯源时间线上。
设置严重程度
finding.set_severity
设置严重程度，并据此重新计算 SLA 日期和优先级。
| 设置 | 选项 |
|---|---|
| 严重程度 | Critical、High、Medium、Low、Info |
设置字段
finding.set_field
设置某个文本字段，或在其后追加内容、在其前插入内容。
| 设置 | 默认值 | 说明 |
|---|---|---|
| 字段 | 无 | 可选值为 component_name、component_version、cvssv3、cwe、description、file_path、impact、mitigation、service、title 之一。 |
| 模式 | set | set、append 或 prepend。CVSSv3 向量只能被替换。 |
| 值 | 无 | 要写入的文本内容。支持 {{finding.title}} 这类占位符。 |
设置状态
finding.set_status
将发现项变更为指定状态。
| 设置 | 默认值 | 说明 |
|---|---|---|
| 状态 | 无 | active、inactive、verified、unverified、false_positive、mitigated、reopen。 |
| 备注 | 空 | 随状态变更一并记录的可选备注。 |
添加标签
finding.add_tags
为发现项添加标签，已有标签保持不变。
| 设置 | 说明 |
|---|---|
| 标签 | 用逗号分隔。支持 {{product.name}} 这类占位符，因此你可以用发现项中的数据来打标签。 |
添加备注
finding.add_note
为发现项添加一条备注。
| 设置 | 说明 |
|---|---|
| 备注 | 备注内容。支持占位符。 |
设置负责人
finding.set_owners
指定一个组对该发现项负责。
| 设置 | 说明 |
|---|---|
| 组 | 负责这些发现项的组。 |
设置审核人
finding.set_reviewers
将该发现项交由所选用户进行审核。
| 设置 | 说明 |
|---|---|
| 审核人 | 应当审核这些发现项的一位或多位用户。 |
接受风险
finding.risk_accept
对该发现项进行简单风险接受，或将其加入某条风险接受记录。
| 设置 | 默认值 | 说明 |
|---|---|---|
| 方式 | simple | simple 会对该发现项设置简单风险接受；acceptance 会将其加入某条风险接受记录。 |
| 已接受 | 开启 | 在选择 simple 时显示。关闭表示取消风险接受。 |
| 风险接受 | 无 | 在选择 acceptance 时显示。指定要将这些发现项加入哪条风险接受记录。 |
设置缓解策略
finding.set_mitigation_policy
设置该发现项所依据的整改缓解策略。
| 设置 | 说明 |
|---|---|
| 缓解策略 | 要应用的策略。 |
更改优先级
finding.set_priority
设置优先级，或对其进行算术调整。此操作会覆盖系统计算出的优先级。
| 设置 | 默认值 | 说明 |
|---|---|---|
| 操作 | set | set、add、subtract、multiply、divide。 |
| 值 | 无 | 要设置的优先级，或要调整的数值。 |
设置风险
finding.set_risk
设置风险等级，覆盖系统计算出的结果。
| 设置 | 选项 |
|---|---|
| 风险 | Low、Medium、Needs Action、Urgent |
出站节点
出站节点是指会离开 DefectDojo 向外发送内容的节点。在发送任何内容之前，每一个出站节点都会先记录一条投递记录，并且都会遵循该规则所处的模拟或正式模式。
其中有几个节点都提供相同的按发现项逐条发送选项。关闭时，节点会发送一条描述整批内容的消息，其中包含严重程度细分和一份数量有上限的发现项列表；开启时，则会按发现项逐条发送消息。
按发现项逐条发送消息的节点，默认在单次运行中发送满 1,000 条后就会停止，并记录一条可见的跳过说明，注明还有多少发现项未被发送。参见配置。
当渠道不可用时
出站节点依赖于规则之外的某些资源：Slack 令牌、Microsoft Teams webhook、JIRA 配置、已获得许可的连接器等。当这些资源缺失或被关闭时，该节点就无法工作，而 Rules Engine 2.0 会在三个不同的时刻明确告知这一点，而不是悄无声息地失败：
- 在节点面板中，不可用的节点在你将其拖到画布上之前，就已经被标注为不可用并说明原因。
- 在保存时，包含不可用节点的图会被拒绝保存。这正是有人在场、可以另选一个节点的时刻。
- 在运行时，该次投递会被标记为跳过并附带原因，而不是标记为失败。在 Slack 开启时保存的规则，不应该在有人关闭 Slack 的那天开始报错。诚实的记录方式，就是一条说明“Slack 已关闭”的跳过记录。
创建 JIRA 问题
ticket.jira
为该发现项创建或更新 JIRA 问题。
| 设置 | 默认值 | 说明 |
|---|---|---|
| 跳过已存在问题的发现项 | 开启 | 对已经存在 JIRA 问题的发现项不做处理。 |
| 更新已存在的问题 | 关闭 | 在上面的跳过选项关闭时显示。会推送已存在问题的发现项，从而更新 JIRA 中的内容。 |
摘要、描述和优先级均来自该产品的 JIRA 配置，而非来自此节点。因此，规则所创建的工单，与通过“推送所有问题”创建的工单完全相同。
创建下游工单
ticket.downstream
通过下游连接器创建或更新工单。
| 设置 | 默认值 | 说明 |
|---|---|---|
| 问题跟踪系统 | auto | auto 使用分配给该测试活动或产品的问题跟踪系统；mapping 则指定某一个具体的映射。 |
| 问题跟踪系统映射 | 无 | 在选择 mapping 时显示。指定要推送到哪一个映射。 |
| 操作 | create | create 表示创建工单，update 表示更新已存在的工单。如果执行更新时并不存在对应工单，则会创建一个。 |
| 跳过已有工单的发现项 | 开启 | 对目标映射中已经存在工单的发现项不做处理。 |
该规则会取代分配设置中的自动推送配置：严重程度和“仅活动”过滤条件不会在此处被再次应用。无论某个发现项的工单最初是如何创建的，只要工单已存在，就会被跳过。
发送 Slack 消息
notify.slack
通过消息连接器发布到 Slack 频道。机器人令牌保存在该连接中；系统设置下的实例级 Slack 设置不会被使用，也不会作为后备方案。
| 设置 | 默认值 | 说明 |
|---|---|---|
| 连接 | 无 | 该类型的消息连接器。必填。 |
| 目的地 | 空 | 在选定连接后显示。具体字段取决于该连接所使用的供应商。 |
| 按发现项逐条发送 | 关闭 | 关闭时，会针对整批内容发送一条消息。 |
| 消息内容 | {{finding.severity}}: {{finding.title}} ({{product.name}}) | 按发现项逐条渲染。 |
| 摘要中列出的发现项数量 | 10 | 用于批量消息。指消息中列出多少条发现项后，再说明还有多少条未列出。 |
发送 Microsoft Teams 消息
notify.msteams
通过消息连接器发布一张卡片。Power Automate 工作流的 URL 保存在该连接中；系统设置下的实例级 Teams webhook 不会被使用，也不会作为后备方案。
| 设置 | 默认值 | 说明 |
|---|---|---|
| 连接 | 无 | 该类型的消息连接器。必填。 |
| 目的地 | 空 | 在选定连接后显示。具体字段取决于该连接所使用的供应商。 |
| 按发现项逐条发送 | 关闭 | 关闭时，会针对整批内容发送一张卡片。 |
| 消息内容 | {{finding.severity}}: {{finding.title}} ({{product.name}}) | 按发现项逐条渲染。 |
| 摘要中列出的发现项数量 | 10 | 用于批量消息。 |
发送电子邮件
notify.email
通过消息连接器向一组固定的地址发送电子邮件。收件人即该连接的目的地。
| 设置 | 默认值 | 说明 |
|---|---|---|
| 连接 | 无 | 该类型的消息连接器。必填。 |
| 目的地 | 空 | 在选定连接后显示。具体字段取决于该连接所使用的供应商。 |
| 主题 | [DefectDojo] {{ctx.count}} finding(s) from rule {{ctx.rule_name}} | 每条消息渲染一次。 |
| 正文 | 包含 {{ctx.findings_html}} 的 HTML 正文 | HTML。{{ctx.findings_html}} 用于渲染发现项列表。 |
| 按发现项逐条发送 | 关闭 | 关闭时，会针对整批内容发送一封电子邮件。 |
| 正文中列出的发现项数量 | 25 | {{ctx.findings_html}} 会列出多少条发现项后，再说明还有多少条未列出。 |
调用 Webhook
notify.webhook
向某个 webhook 端点 POST JSON 数据。
| 设置 | 默认值 | 说明 |
|---|---|---|
| Webhook 端点 | 无 | 一个已配置的通知 webhook。其自定义请求头会随请求一并发送。 |
| URL | 空 | 在未选择端点时显示。指定要 POST 到的地址。 |
| 以上两者必须填写其中一个。 | ||
| 签名密钥 | 空 | 以 X-DefectDojo-Signature: sha256=HMAC 的形式对请求体进行签名。 |
| 按发现项逐条发送 | 关闭 | 关闭时，会将整批内容放在一个请求中发送。 |
有两点需要注意。在此处填写的签名密钥会与规则一起存储，因此对于任何敏感信息，最好使用已配置的端点及其自带的请求头。此外，规则调用 webhook 从不会改变该端点自身的健康状态，因此规则本身的失败不会导致你的通知 webhook 被禁用。
手动填写的 URL 会在保存时进行校验。哪些地址会被拒绝、以及如何允许私有地址，参见配置。
触发应用内提醒
notify.alert
针对整批内容创建一条应用内提醒。
| 设置 | 默认值 | 说明 |
|---|---|---|
| 标题 | Rules Engine 2.0: {{ctx.rule_name}} | 针对整批内容渲染一次。 |
| 描述 | {{ctx.count}} finding(s) matched the rule {{ctx.rule_name}}. | 针对整批内容渲染一次。 |
| 接收人 | 空 | 用户名，用逗号分隔。留空则提醒管理员。 |
接收人仍然可以通过自己的Rules Engine Match 通知设置来控制这一行为，因此提醒无法绕过用户自己的通知偏好设置。
生成报告
report.generate
根据模板生成一份报告，范围限定为到达此节点的发现项，并可以通知发送该报告的下载链接。
| 设置 | 默认值 | 说明 |
|---|---|---|
| 报告模板 | 无 | 用于生成报告的模板。必填。 |
| 格式 | pdf | pdf 或 html。 |
| 包含的发现项 | batch_findings | batch_findings 会将报告限定为到达此节点的发现项；template_default 则让模板使用自己的过滤条件。 |
| 通知渠道 | 无 | 报告生成后，用于发布下载链接的消息连接器。留空则不发送通知。 |
| 通知目标 | 空 | 在选定连接后显示。指该连接的发送位置：Slack 频道 ID、电子邮件地址等等。 |
| 通知内容 | Report ready: {{ctx.report_url}} | 在发送通知时显示。{{ctx.report_url}} 即下载链接。 |
batch_findings 正是规则能做到、而定时报告做不到的事情：精确针对刚刚匹配到的那些发现项生成报告。
该通知会作为一条独立的投递记录单独记录，与报告的生成过程分开，因此你可以分别查看报告生成成功、而通知发送失败这样的情况。