Webhook

Webhook を使用して、AppScan on Cloud で発生したイベントに関する通知を受け取れるようになりました。

概要

ASoC REST API では、ユーザー定義の HTTP コールバック (Webhook) がサポートされています。Webhook は AppScan on Cloud でイベントが発生したときに通知します。以下のイベント・タイプがサポートされています。

  • スキャン実行完了
  • アプリケーション・カウンターまたはステータスの変更

Webhook を使用するには、まず AppScan プレゼンスをお使いのローカル・ネットワークにダウンロードのうえインストールします (通常はワンタイム・セットアップ)。プレゼンスは ASoC に接続します。

Webhook がトリガーされると、プレゼンスが ASoC からコマンドを受信し、HTTP GET 要求をローカル・ネットワークの Webhook URI に送信します。

プレゼンスはネットワーク内から要求を送信するため、ASoC からの着信要求に対してファイアウォールを開かずに内部サーバーに通知できます。

REST API を使用して Webhook を作成および管理する

Webhook を作成、管理、構成するには、ASoC REST API を使用します。Webhook エンドポイントは、パブリック API リファレンスで文書化されています。

AppScan REST API - Webhook エンドポイント

Webhook を作成するには、/api/v4/Webhooks エンドポイントに次の情報とともに POST 要求を送信します。

  • PresenceId: Webhook 要求を処理する AppScan プレゼンス・インスタンスの ID。
  • Uri: イベントがトリガーされたときに呼び出す HTTP エンドポイント。URI には{SubjectId} プレースホルダーを含めることができます。
  • イベント: Webhook をトリガーするイベント・タイプ (ScanExecutionCompleted または ApplicationCountersChanged)
  • グローバル: これがグローバル Webhook (すべてのアプリケーションまたは資産グループに適用)であるか、スコープ付きWebhook (特定のアプリケーションまたは資産グループにのみ適用) であるかを示すブール値
  • AssetGroupId: (オプション) Webhook が適用される資産グループの ID

例: スキャン完了のためのグローバル Webhook

この例では、スキャン実行完了時にトリガーされるグローバル Webhook を作成します。組織内のすべてのスキャンに対して Webhook が呼び出されます。

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

この Webhook がトリガーされると、ASoC がサービスに GET 要求を送信します。{SubjectId} 値は、スキャン実行 ID に置き換えられます。

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

重要: Webhook は要求本体にイベント・データを送信しません。追加データ (スキャンによって検出された問題のリストなど) を取得するには、Webhook イベントを処理する別のサービスを実装し、API キーを使用して ASoC にログインし、ASoC API から必要なデータを取得します。

Webhook URI プレースホルダー

Webhook URI を定義するときに、{SubjectId} プレースホルダーを含めることができます。このプレースホルダーは、イベント・サブジェクトの ID (通常はスキャン実行 ID) と置き換えられます。この値を使用して、基本的なイベント・コンテキストを Webhook ハンドラーに渡すことができます。

プレースホルダーを使用した URI の例:

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

ID 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 は、1 つ以上の「有効範囲」に関連付けることができます。有効範囲は、特定のアプリケーション、または Webhook が組織レベルで定義されている場合は、特定の資産グループです。

有効範囲が指定された Webhook は、イベントが関連する有効範囲のいずれかで発生する場合にのみトリガーされます。

例: Webhook が「スキャンの実行完了」時にトリガーされるよう設定されていて、Webhook の「有効範囲」が特定のアプリケーションであるとき、Webhook はアプリケーション内でスキャン実行が完了するたびにトリガーされます。

有効範囲 Webhook の Webhook 関連付けの作成

Webhook がグローバルでない場合 (つまり、"Global": false を設定した場合)、Webhook を適用するアプリケーションまたは資産グループを指定するための関連付けを作成する必要があります。Webhook 関連付け API エンドポイントを使用して、これらの関連付けを作成します。

Webhook を特定のアプリケーションまたは資産グループに関連付けるには、POST 要求を /api/v4/Webhooks/Associations/{id} エンドポイントに送信します。{id} には、Webhook の作成時に返される Webhook ID が入ります。

例: 特定の資産グループのスコープ付き Webhook

まず、(グローバルではなく) スコープ付き Webhook を作成します。

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

この Webhook は、関連付けを作成するまでトリガーされません。次に、関連付けエンドポイントを使用して、Webhook を特定のアプリケーションに関連付けます。これにより、その資産グループ内の関連アプリケーションのスキャンに対してのみ Webhook がトリガーされるようになります。

Webhook 関連付けの作成と管理の詳細については、AppScan REST API ドキュメントを参照してください。