> ## 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.

# HackerOne 告警集成

> 通过 Webhook 将 HackerOne 项目中漏洞报告的提交、分诊和关闭事件同步到 Flashduty On-call。

通过 HackerOne 项目（Program）的 Webhook，将漏洞报告（Report）同步到 Flashduty On-call。每份 HackerOne 报告对应一条 Flashduty 告警：报告提交、分诊、重新打开时触发或更新这条告警，报告被解决或以其他方式关闭时告警恢复。

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

  ***

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

  ### 使用专属集成

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

  ### 使用共享集成

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

## 在 HackerOne 中配置

***

Webhook 按项目配置，并继承创建者的权限：创建者需要能查看该项目的报告，并有权修改项目设置。

<Steps>
  <Step title="新建 Webhook">
    1. 登录 HackerOne，进入 **Engagements**，点击目标项目右侧的菜单按钮，选择 **Settings**
    2. 进入 **Automation → Webhooks**，点击 **New webhook**
    3. 将 Flashduty 集成的完整推送地址粘贴到 **Payload URL**，地址中需包含 `integration_key`
    4. **Secret** 可以留空。Flashduty 通过推送地址中的 `integration_key` 识别集成，不校验 `X-H1-Signature` 签名
  </Step>

  <Step title="选择事件">
    选择 **Let me specify individual events**，勾选以下事件：

    | HackerOne 事件 | 报告状态 | 在 Flashduty 中的效果 |
    | :- | :- | :- |
    | `report_created` | `new` | 触发告警 |
    | `report_triaged` | `triaged` | 更新告警 |
    | `report_reopened` | 打开状态 | 触发或更新告警 |
    | `report_resolved` | `resolved` | 恢复告警 |
    | `report_closed_as_duplicate` | `duplicate` | 恢复告警 |
    | `report_closed_as_informative` | `informative` | 恢复告警 |
    | `report_closed_as_not_applicable` | `not-applicable` | 恢复告警 |
    | `report_closed_as_spam` | `spam` | 恢复告警 |

    按需加选 `report_needs_more_info`、`report_retesting` 等事件，它们只会更新同一份报告的告警。最后点击 **Add webhook**。

    <Warning>
      必须勾选 `report_resolved` 和四个 `report_closed_as_*` 事件，否则报告关闭后 Flashduty 中的告警不会恢复。
    </Warning>

    也可以选择 **Send me everything**。评论、赏金等事件同样按报告当前状态处理：报告仍打开时更新告警，报告已关闭时不会产生新告警。`program_hacker_joined` 等项目事件不含报告，Flashduty 返回成功但不创建告警。
  </Step>

  <Step title="验证生命周期">
    提交或分诊一份报告，确认 Flashduty 收到活动告警；然后在 HackerOne 中将该报告关闭（如 **Resolved**），确认原告警恢复。

    编辑 Webhook 时可点击 **Test request** 发送示例请求，用于确认地址可达。如果示例请求在 Flashduty 中生成了告警，手动关闭即可。在 Webhook 编辑页的 **Recent deliveries** 中可以查看每次推送的请求和 Flashduty 的响应。
  </Step>
</Steps>

## Alert Key

***

Flashduty 使用报告 ID（Webhook 中的 `data.report.id`）作为 Alert Key。HackerOne 的每次推送都携带该报告的完整信息，同一份报告在提交、分诊、关闭、重新打开时的 `data.report.id` 相同，它也是报告地址 `https://hackerone.com/reports/<id>` 中的编号。

标题、状态、严重程度的变化都不会改变 Alert Key。含有报告但缺少 `data.report.id` 的推送会被拒绝。

## 状态和告警等级

***

告警状态由报告当前状态（`data.report.attributes.state`）决定，而不是事件名：

| 报告状态 | 告警状态 |
| :- | :- |
| `new`、`pending-program-review`、`triaged`、`needs-more-info`、`retesting` | 触发 |
| `resolved`、`not-applicable`、`informative`、`duplicate`、`spam` | 恢复 |

其他状态值会被拒绝，HackerOne 的 **Recent deliveries** 中会显示失败。

告警等级由报告的严重程度（`data.report.relationships.severity.data.attributes.rating`）决定：

| HackerOne 严重程度 | Flashduty 等级 |
| :- | :- |
| `critical` | Critical |
| `high` | Critical |
| `medium` | Warning |
| `low` | Info |
| `none` | Info |
| 未评级或其他值 | Warning |

分诊时调整了严重程度的报告，会以新的等级更新原告警。

## 标签

***

| 标签 | 来源 |
| :- | :- |
| `report_id` | 报告 ID，即 Alert Key |
| `report_state` | 报告当前状态 |
| `severity_rating` | HackerOne 严重程度 |
| `event` | 本次推送的事件名（`X-H1-Event` 请求头） |
| `reporter` | 提交报告的研究者用户名 |
| `url` | HackerOne 中的报告链接 |
| `check` | 报告标题 |

告警描述为报告的漏洞详情（`vulnerability_information`），超过 8 KB 的部分会被截断。

## 排查问题

***

* **HackerOne 显示推送失败**：在 Webhook 编辑页的 **Recent deliveries** 中点开失败的请求，在 **Response** 中查看 Flashduty 的返回信息；确认 **Payload URL** 完整且包含 `integration_key`
* **告警没有恢复**：确认已勾选 `report_resolved` 和四个 `report_closed_as_*` 事件。未勾选这些事件时关闭的报告，对应告警需在 Flashduty 中手动关闭
* **收不到某些报告**：Webhook 继承创建者的权限，确认创建者能看到这些报告

更多字段含义请参阅 [HackerOne Webhooks](https://api.hackerone.com/webhooks/) 和 [HackerOne 帮助中心：Webhooks](https://docs.hackerone.com/en/articles/8588351-webhooks)。