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

# Semgrep 告警集成

> 通过 Webhook 将 Semgrep AppSec Platform 的新增代码扫描发现和供应链安全事件同步到 Flashduty On-call。

通过 Semgrep AppSec Platform 的 Webhook 集成，将新发现的代码问题（SAST、SCA、Secrets）和供应链安全事件同步到 Flashduty On-call。每个发现（finding）对应一条 Flashduty 告警；影响到您项目的供应链事件对应一条 Flashduty 告警。

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

  ***

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

  ### 使用专属集成

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

  ### 使用共享集成

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

## 在 Semgrep 中配置

***

需要 Semgrep AppSec Platform 的管理权限。

<Steps>
  <Step title="创建 Webhook 集成">
    1. 在 Semgrep AppSec Platform 中点击 **Settings → Integrations → Add integration**，选择 **Webhook**
    2. **Name** 填写集成名称
    3. **Webhook URL** 粘贴 Flashduty 的完整推送地址，地址中需包含 `integration_key`
    4. **Signature Secret** 可留空。填写后（至少 15 个字符），Semgrep 会在每次推送中携带 `X-Semgrep-Signature-256` 请求头；Flashduty 不校验该签名，通过地址中的 `integration_key` 认证
    5. 点击 **Subscribe**
  </Step>

  <Step title="在策略中开启通知">
    编辑或创建 [Unified Policies](https://docs.semgrep.dev/semgrep-appsec-platform/unified-policies/get-started#create-a-remediation-policy) 中的策略，点击 **Add action → Call a webhook**，选择刚创建的 Webhook 集成。策略的筛选条件（严重程度、置信度、项目等）决定哪些发现会推送到 Flashduty。Semgrep 要求策略至少包含一个条件才能保存，例如 **Confidence** 为 High、Medium、Low 中任意值。

    如需接收供应链安全事件，开启 **Early notification for Supply Chain incidents** 策略并选择同一个 Webhook 集成。
  </Step>

  <Step title="保存并验证">
    1. 在 **Settings → Integrations** 中点击该 Webhook 集成的 **Test** 按钮，确认 Flashduty 返回成功。测试请求的内容为 `[{"text":"Test Notification","username":"Semgrep"}]`，Flashduty 返回成功，并创建一条标题为 "Semgrep test notification" 的独立 Info 告警，请手动关闭
    2. 提交一段会命中规则的代码并触发扫描，确认 Flashduty 收到新的告警
  </Step>
</Steps>

## 推送内容和告警恢复

***

Semgrep 推送三类对象，一次请求可以包含多个：

| Semgrep 对象 | 触发时机 | 在 Flashduty 中的效果 |
| :- | :- | :- |
| `semgrep_finding` | 策略匹配到新的发现 | 每个发现一条告警 |
| `semgrep_supply_chain_incident` | Semgrep 安全研究团队发布供应链事件 | 影响到您的项目（`is_affected` 为 `true`）时一条告警；未影响时不创建告警 |
| `semgrep_scan` | 每次扫描 | 不创建告警，直接返回成功 |

Semgrep 只在发现首次出现时推送一次，不推送更新或已修复通知，因此 Flashduty 告警不会自动恢复。请在协作空间中开启[超时自动关闭](/zh/on-call/channel/create-edit)，建议 7 天；也可以在问题修复后手动关闭。

## Alert Key

***

| 对象 | 使用的字段 |
| :- | :- |
| 发现 | `numeric_id`（发现在 Semgrep AppSec Platform 中的 ID） |
| 供应链事件 | `incident_id` |

Alert Key 由对象类型和上表中的 ID 共同计算，同一发现重复投递会合并，数字相同的发现 ID 和事件 ID 不会互相合并。规则名称、严重程度等字段变化不会改变 Alert Key。缺少对应 ID 的对象会导致整个请求被拒绝。

## 告警等级

***

发现的 `severity` 为数字，由规则严重程度换算：

| Semgrep `severity` | 对应规则严重程度 | Flashduty 等级 |
| :- | :- | :- |
| `3` | Critical | Critical |
| `2` | Error / High | Critical |
| `1` | Warning / Medium | Warning |
| `0` | Info / Low | Info |
| `4` | Experiment | Info |
| 缺失或其他值 | - | Warning |

影响到您项目的供应链事件固定为 Critical。

## 标签

***

发现：

| 标签 | 来源 |
| :- | :- |
| `check` / `rule_id` | 规则 ID（`check_id`），同时作为告警标题 |
| `finding_id` | `numeric_id` |
| `repo` / `path` / `line` / `ref` | 仓库、文件路径、行号、分支 |
| `commit_url` | 提交链接 |
| `semgrep_severity` | Semgrep 原始严重程度数字 |
| `confidence` / `category` | 规则元数据中的置信度和类别 |
| `cwe` / `owasp` / `vulnerability_class` | 规则元数据中的分类，逗号分隔 |

供应链事件：

| 标签 | 来源 |
| :- | :- |
| `check` | 事件标题 |
| `incident_id` | `incident_id` |
| `packages` | 受影响的依赖包名，逗号分隔（最多 50 个） |
| `affected_projects` | 受影响的项目，逗号分隔（最多 50 个） |
| `advisories_url` / `blog_url` | Semgrep 公告和博客链接 |

所有告警都带有 `source=semgrep` 和 `event_type`（`finding` 或 `supply_chain_incident`）。告警描述为规则的 `message`，不会推送代码片段。

## 排查问题

***

* **Flashduty 返回参数错误**：确认 Webhook URL 完整且包含 `integration_key`；发现缺少 `numeric_id` 或事件缺少 `incident_id` 时也会返回该错误
* **没有收到告警**：确认策略中已添加 **Call a webhook** 动作；Semgrep 只在发现首次出现时推送，已有的发现不会重复通知
* **告警一直未关闭**：Semgrep 没有恢复通知，请开启协作空间的超时自动关闭
* **收到的告警太多**：在 Semgrep 策略中提高严重程度或置信度筛选条件

更多信息请参阅 [Semgrep Webhooks 文档](https://docs.semgrep.dev/semgrep-appsec-platform/webhooks)。