はじめに
現時点では、Copilot for Security は https://securitycopilot.microsoft.com/ のスタンドアローンポータルもしくは Defender XDR ポータルなどへの組み込みから利用する形です。他には Logic Apps のコネクタから実行することが可能ですが、API 利用のドキュメントや SDK は公開されていません。そのため、今回はスタンドアローン ポータルにおけるリクエスト/レスポンスをブラウザの開発者ツールで確認し、API 経由でプロンプトを送れるように仕様を確認してみました。
プロンプトを送信する仕組み
Copilot for Security では、以下の流れでプロンプトを送信し、回答を表示しているようです。
- セッションを作成
- 作成したセッションの ID を指定し、プロンプトを送信
- 送信したプロンプトで評価 (プラグインの選択や情報の収集、回答の準備など) を実行
- 評価が完了した時点で回答を受領し表示
上記に基づいて、各リクエストを確認したので、PowerShell で API を実行していきます。
PowerShell で API 経由でプロンプトを送信
0. Bearer トークンを取得
API を実行するにあたり、Bearer トークンが必要になりますので、Connect-AzAccount を利用して取得します。
# テナント ID を指定
$tenantId = "your tenant id"
# Azure PowerSHell に接続
Connect-AzAccount -Tenant $tenantId
# api.securitycopilot.microsoft.com をリソースとして Bearer トークンを取得
$token = Get-AzAccessToken -ResourceUrl "https://api.securitycopilot.microsoft.com"
# header 作成
$bearertoken = "Bearer " + $token.Token
$headers = @{
"Authorization"= $bearerToken
"Content-Type"="application/json"
}
1. セッションを作成
以下の API リクエストでセッションを生成します。
# セッション作成用リクエスト作成
$request = @{
Uri = "https://api.securitycopilot.microsoft.com/geo/eastus/sessions"
Body = '{"name":"' + $sessionName + '","source":"immersive"}'
Headers = $headers
Method = 'POST'
}
# セッション作成 API 実行
$response = Invoke-WebRequest @request
# セッション ID の取得
$sessionId = ($response.Content | ConvertFrom-Json).sessionId
実行すると、ポータル上は以下のようなプロンプトを含まない空のセッションが作成されます。
2. 作成したセッションの ID を指定し、プロンプトを送信
以下の API リクエストで 1. にて作成したセッション内でプロンプトを送信します。
# プロンプトを指定
$prompt = "Sentinel インシデント 9002 について教えてください。"
# プロンプト送信用リクエスト作成
$request = @{
Uri = "https://api.securitycopilot.microsoft.com/geo/eastus/sessions/$sessionId/prompts"
Body = '{"promptType":"Prompt","content":"' + $prompt + '","sessionId":"' + $sessionId + '","source":"immersive"}'
Headers = $headers
Method = 'POST'
}
# プロンプト送信 API 実行
$response = Invoke-WebRequest @request
# プロンプト ID の取得
$promptId = ($response.Content | ConvertFrom-Json).promptId
実行すると、ポータル上はプロンプトが表示されますが、実行中のまま何も進まない状態になります。
3. 送信したプロンプトで評価を実行
プロンプトに対して Security for Copilot がアクションを起こすように先ほど送信したプロンプトに対して評価 (evaluations) を実行します。
# 評価実行用リクエスト作成
$request = @{
Uri = "https://api.securitycopilot.microsoft.com/geo/eastus/sessions/$sessionId/prompts/$promptId/evaluations"
Body = '{"sessionId":"' + $sessionId + '","promptId":"' + $promptId + '"}'
Headers = $headers
Method = 'POST'
}
# 評価実行 API 実行
$response = Invoke-WebRequest @request
# 評価 ID の取得
$evaluationId = ($response.Content | ConvertFrom-Json).evaluation.evaluationId
評価を実行すると、以下のようにプライグインの確認などが始まります。
4. 評価が完了した時点で回答を受領し表示
さきほど実行した評価の結果 (プロンプトの応答) を取得します。
# プロンプト回答取得リクエスト作成
$request = @{
Uri = "https://api.securitycopilot.microsoft.com/geo/eastus/sessions/$sessionId/prompts/$promptId/evaluations/$evaluationId"
Headers = $headers
Method = 'GET'
}
# プロンプト回答取得 API 実行
$response = Invoke-WebRequest @request
# 回答の表示
$response.Content | ConvertFrom-Json
以下のようにステータスなどとともに回答を取得することができます。
一連の PowerShell スクリプト
上記の流れをまとめて以下の PowerShell スクリプトとしています。評価の処理については、ステータスが Created, Running, Completed がある (他にもあると思うが確認できず) ため、評価が完了するまで繰り返しチェックし、Completed になったタイミングで回答を取得するようにしています。(ポータルも同じ動きをしている模様)
Discussion