> ## Documentation Index
> Fetch the complete documentation index at: https://docs.flashduty.com/llms.txt
> Use this file to discover all available pages before exploring further.

# SecurityScorecard 告警集成

> 通过 Rule Builder 的 Send a web request 动作，将 SecurityScorecard 的评分变化、新问题和数据泄露事件同步到 Flashduty On-call。

通过 SecurityScorecard Rule Builder 规则中的 **Send a web request** 动作，将评分卡（Scorecard）上的事件同步到 Flashduty On-call。规则每触发一次，SecurityScorecard 发送一个 POST 请求，Flashduty 为其创建一条告警。

SecurityScorecard 的事件只在发生时发送一次，没有对应的恢复通知，因此告警不会自动恢复。请在协作空间中开启超时自动关闭，见下文 [告警不会恢复](#告警不会恢复)。

<div className="hide">
  ## 在 Flashduty On-call

  ***

  您可通过以下两种方式获取集成推送地址，任选其一即可。

  ### 使用专属集成

  1. 进入 Flashduty 控制台，选择 **协作空间**，打开一个协作空间
  2. 选择 **配置** → **集成数据** → **专属集成**，点击 **新增一个集成**
  3. 选择 **SecurityScorecard**，点击 **保存**
  4. 打开生成的集成卡片，复制 **推送地址**

  ### 使用共享集成

  1. 进入 Flashduty 控制台，选择 **集成中心 → 告警事件**
  2. 选择 **SecurityScorecard**，填写集成名称
  3. 配置默认路由并选择协作空间；创建后可在 **路由** 中增加更多规则
  4. 点击 **保存**，复制生成的 **推送地址**
</div>

## 在 SecurityScorecard 中配置

***

Rule Builder 需要 SecurityScorecard 付费套餐，每个用户最多创建 25 条规则。

<Steps>
  <Step title="新建规则">
    1. 登录 SecurityScorecard 平台，进入 **Automation** → **Rule Builder**，点击 **Create Rule**（旧版界面在右上角头像 → **My Settings** → **Rules** 中）
    2. 选择 **Events**，让规则在事件发生时运行
    3. 填写规则名称，例如 `Flashduty: vendor score drop`
    4. 选择规则监控的评分卡：本组织的评分卡、单个评分卡或某个 Portfolio
    5. 选择触发事件，例如总分降到某个阈值以下、出现指定严重程度的新问题、报告数据泄露
  </Step>

  <Step title="添加 Send a web request 动作">
    1. 动作选择 **Send a web request**
    2. URL 粘贴 Flashduty 集成的完整推送地址，含 `integration_key` 参数。SecurityScorecard 只向 HTTPS 地址发送，且不支持自定义请求头，`integration_key` 必须放在 URL 中
    3. 检查规则后点击 **Save**

    保存后，规则每次触发都会向该地址发送一次 POST，请求体为包含 `trigger`、`execution_id`、`scorecard_id`、`domain` 的 JSON。
  </Step>

  <Step title="验证">
    Rule Builder 没有发送测试请求的按钮。SecurityScorecard 每天评估一次评分卡事件，规则在事件满足条件后运行。要立即验证，可以使用 SecurityScorecard API 的 [Simulate Actions](https://securityscorecard.readme.io/docs/simulate-actions)（请求中带上规则的 `rule_id`）模拟一次事件，确认 Flashduty 收到对应告警。模拟会产生一条真实告警，验证后请手动关闭。
  </Step>
</Steps>

## Alert Key

***

Flashduty 使用 `execution_id`、`scorecard_id` 和 `trigger.type` 计算 Alert Key。SecurityScorecard 的 [Rule Builder: Webhooks](https://support.securityscorecard.com/hc/en-us/articles/360058429271-Rule-Builder-Webhooks) 说明，`execution_id` 是一次规则执行的唯一标识，请求失败重试时保持不变。因此同一次执行的重试会合并到同一条告警，不同的规则执行各自成为独立告警。

请求中缺少 `execution_id` 时，Flashduty 生成随机 Alert Key，每个请求都是一条新告警。缺少 `trigger.type` 时返回参数错误。

## 告警等级

***

| 事件（`trigger.type`） | 条件 | Flashduty 等级 |
| :- | :- | :- |
| 数据泄露（`breach_reported`） | | Critical |
| 新问题（`new_issues`） | `trigger.severity` 为 `high` 或 `critical` | Critical |
| 新问题（`new_issues`） | `trigger.severity` 为 `medium`、缺省或无法识别的值 | Warning |
| 新问题（`new_issues`） | `trigger.severity` 为 `low`、`info` 或 `informational` | Info |
| 评分变化（`grade_drop`）及其他事件类型 | | Warning |

## 字段映射

***

| Flashduty | SecurityScorecard 字段 |
| :- | :- |
| 标题 | 事件类型和 `domain`（缺省时用 `scorecard_id`），例如 `SecurityScorecard score change: example.com (score 54)`、`SecurityScorecard new issues: example.com (2 issue types)`、`SecurityScorecard breach reported: example.com`；其他事件类型为 `SecurityScorecard <trigger.type>: <domain>` |
| 描述 | 事件类型、`domain`、`trigger.score`、`trigger.severity`、每种问题的 active / departed / resolved 数量、泄露描述 |
| 标签 | `trigger_type`（同时写入 `check`）、`domain`（同时写入 `resource`）、`scorecard_id`、`execution_id`、`score`、`selected`、`issue_severity`、`issue_types`，以及数据泄露事件的 `breach_root_cause`、`breach_company`、`breach_records_lost`、`breach_type` |

请求中的 `retries` 和 `webhooks`（前序 Webhook 的响应）不写入告警。SecurityScorecard 将该请求体标注为 beta，问题和泄露详情的结构变化时，Flashduty 忽略无法解析的部分，仍然创建告警。

## 告警不会恢复

***

评分变化、新问题和数据泄露都是一次性事件，SecurityScorecard 不会发送恢复通知。请在接收该集成的协作空间中开启 [超时自动关闭](/zh/on-call/channel/create-edit)，建议 24 小时，并按团队处理安全评级事件的时效调整。

## 排查问题

***

<AccordionGroup>
  <Accordion title="规则触发了但没有收到告警">
    确认规则的动作是 **Send a web request**，URL 是完整的推送地址且以 `https://` 开头。SecurityScorecard 每天评估一次事件，规则不会在评分卡变化的当下立即运行。只有分数变化超过规则设置的分值时才会触发，等于该分值不触发。
  </Accordion>

  <Accordion title="收到 [Action Required] Failed Webhook Request 邮件">
    SecurityScorecard 在网络错误或 5xx 响应时重试，36 小时后仍失败会给规则所有者发送该邮件。请检查推送地址是否完整、集成是否已被删除。
  </Accordion>

  <Accordion title="Flashduty 返回参数错误">
    请求体必须是不超过 1 MiB 的 JSON，且 `trigger.type` 非空。推送地址中的 `integration_key` 必须属于一个 SecurityScorecard 集成。
  </Accordion>
</AccordionGroup>

更多字段含义请参阅 SecurityScorecard 文档中的 [Receive event notifications with webhooks](https://securityscorecard.readme.io/docs/receive-event-notifications-with-webhooks)。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.