Webhook

使用 Webhook 可接收关于 AppScan on Cloud 中所发生事件的通知。

概述

通过 ASoC REST API 支持用户定义的 HTTP 回调 (Webhook)。Webhook 会在 AppScan on Cloud 中发生事件时通知您。支持以下事件类型：

  • 扫描执行完成
  • 应用程序计数器或状态已更改

要使用 Webhook，请先下载 AppScan Presence 并将其安装在您的本地网络中（通常只需设置一次）。Presence 连接到 ASoC。

触发 Webhook 时，Presence 会从 ASoC 接收命令，并向本地网络中的 Webhook URI 发送 HTTP GET 请求。

由于 Presence 从您的网络内部发送请求，因此您可以直接通知内部服务器，而无需在防火墙上为来自 ASoC 的传入请求开放任何端口。

使用 REST API 创建和管理 Webhook

要创建、管理和配置 Webhook，请使用 ASoC REST API。Webhook 端点在公共 API 参考文档中进行了说明：

AppScan REST API - Webhook 端点

要创建 Webhook，请向 /api/v4/Webhooks 端点发送包含以下信息的 POST 请求：

  • PresenceId：处理 Webhook 请求的 AppScan Presence 实例的标识
  • Uri：事件触发时要调用的 HTTP 端点。此 URI 可以包含 {SubjectId} 占位符。
  • 事件：触发 Webhook 的事件类型（ScanExecutionCompleted 或 ApplicationCountersChanged）
  • 全局：一个布尔值，用于指示该 Webhook 是全局 Webhook（适用于所有应用程序或资产组），还是限定范围的 Webhook（仅适用于特定应用程序或资产组）
  • AssetGroupId：（可选）应用 Webhook 的资产组的标识

示例：扫描完成时触发的全局 Webhook

此示例将创建一个在扫描执行完成时触发的全局 Webhook。对于组织中的所有扫描，都会调用该 Webhook：

{
    "PresenceId": "1234",
    "Uri": "http://mysite.com/ScanEnded/{SubjectId}",
    "Event": "ScanExecutionCompleted",
    "Global": true
    }

此 Webhook 被触发时，ASoC 会向您的服务发送一个 GET 请求。{SubjectId} 值将替换为扫描执行标识：

GET /ScanEnded/9ea1fcb6-dc1d-443a-bfff-7465ced2ef1b HTTP/1.1 
    Host: mysite.com

要点：此 Webhook 不会在请求正文中发送事件数据。要获取更多数据（例如，扫描中所发现问题的列表），请实施一项单独的服务，该服务会处理 Webhook 事件，使用 API 密钥登录 ASoC，然后通过 ASoC API 检索所需的数据。

Webhook URI 占位符

定义 Webhook URI 时，您可以包含 {SubjectId} 占位符。此占位符将替换为事件主题的标识（通常为扫描执行标识）。您可以使用此值将基本事件上下文传递给 Webhook 处理程序。

带占位符的 URI 示例：

Webhook URI：http://myservice.com/ScanEnded/{SubjectId}

如果标识为 9ea1fcb6-dc1d-443a-bfff-7465ced2ef1b 的扫描执行完成，则 Webhook 将在以下位置进行调用：

http://mysite.com/ScanEnded/9ea1fcb6-dc1d-443a-bfff-7465ced2ef1b

Webhook 访问控制

要创建或修改 Webhook，您必须在 ASoC 中拥有创建/修改 Webhook 许可权。缺省情况下，此许可权会分配给管理员和管理者角色，也可以添加到到自定义角色中。

您可以在组织级别或者为特定资产组定义 Webhook：

  • 组织级别的 Webhook 由管理员或具有所有组的完全访问权限的用户进行定义和管理。
  • 资产组级别的 Webhook 可由有权访问资产组并拥有创建/修改 Webhook 许可权的任何用户进行定义和管理。

Webhook 范围

您可以将 Webhook 定义为全局 Webhook 或限定范围的 Webhook。

每当组织或资产组中（具体取决于 Webhook 的定义位置）发生与 Webhook 事件类型相匹配的事件时，就会触发全局 Webhook。

如果某个 Webhook 并非全局 Webhook，则可以将它与一个或多个范围相关联。范围可以是一个特定的应用程序，或者如果 Webhook 是在组织级别定义的，则范围也可以是一个特定的资产组。

仅当事件在其中一个关联的范围内发生时，才会触发限定范围的 Webhook。

示例：如果 Webhook 是在扫描执行完成时触发的，并且范围是一个特定的应用程序，则每次该应用程序中有扫描执行完成时都会触发此 Webhook。

为限定范围的 Webhook 创建 Webhook 关联

如果 Webhook 不是全局 Webhook（即，如果您设置了 "Global": false），则您必须创建关联以指定该 Webhook 适用的应用程序或资产组。使用 Webhook 关联 API 端点创建这些关联。

要将 Webhook 与特定的应用程序或资产组相关联，请向 /api/v4/Webhooks/Associations/{id} 端点发送 POST 请求，其中 {id} 是您创建 Webhook 时返回的 Webhook 标识。

示例：适用于特定资产组的限定范围 Webhook

首先，创建一个限定范围的 Webhook（不是全局 Webhook）：

{
    "PresenceId": "1234",
    "Uri": "http://mysite.com/ScanEnded/{SubjectId}",
    "Event": "ScanExecutionCompleted",
    "Global": false,
    "AssetGroupId": "5678"
    }

在您创建关联之前，此 Webhook 不会触发。接下来，使用关联端点将 Webhook 与特定应用程序相关联。这可确保仅当对该资产组内的关联应用程序进行扫描时，才会触发此 Webhook。

有关如何创建和管理 Webhook 关联的详细信息，请参阅 AppScan REST API 文档。