MICROSOFT DEFENDER XDR REST API のHello World

  • [アーティクル]

適用対象:

  • Microsoft Defender XDR

重要

一部の情報は、市販される前に大幅に変更される可能性があるプレリリース製品に関するものです。 Microsoft は、ここに記載された情報に関して、明示または黙示を問わず、いかなる保証も行いません。

単純な PowerShell スクリプトを使用してインシデントを取得する

このプロジェクトを完了するには、5 分から 10 分かかります。 今回の見積もりには、アプリケーションの登録と、PowerShell サンプル スクリプトからのコードの適用が含まれます。

Microsoft Entra IDでアプリを登録する

  1. グローバル管理者 ロールを持つユーザーとして Azure にサインインします。

  2. [Microsoft Entra ID>アプリの登録新しい登録]> に移動します。

    Microsoft Defender ポータルの [新しい登録] セクション

  3. 登録フォームで、アプリケーションの名前を選択し、[ 登録] を選択します。 リダイレクト URI の選択は省略可能です。 この例を完了するために必要な操作はありません。

  4. アプリケーション ページで、[API アクセス許可][アクセス許可>の追加] の順>に選択し、organizationが使用する API を選択>し、「Microsoft Threat Protection」と入力して、[Microsoft Threat Protection] を選択します。 アプリがMicrosoft Defender XDRにアクセスできるようになりました。

    ヒント

    Microsoft Threat Protection は、Microsoft Defender XDRの以前の名前であり、元の一覧には表示されません。 テキスト ボックスに名前を書き込んで表示する必要があります。 Microsoft Defender ポータルでの API の使用状況のセクション

    • [ アプリケーションのアクセス許可>Incident.Read.All ] を選択し、[ アクセス許可の追加] を選択します。

      Microsoft Defender ポータルのアプリケーションのアクセス許可ウィンドウ

  5. [ 管理者の同意の付与] を選択します。 アクセス許可を追加するたびに、[管理者の同意を 付与 する] を選択して有効にする必要があります。

    Microsoft Defender ポータルの [管理者の同意の付与] セクション

  6. アプリケーションにシークレットを追加します。 [ 証明書 & シークレット] を選択し、シークレットに説明を追加してから、[ 追加] を選択します。

    ヒント

    [ 追加] を選択した後、[ 生成されたシークレット値のコピー] を選択します。 脱退後にシークレット値を取得することはできません。

    Microsoft Defender ポータルの [シークレットの追加] セクション

  7. アプリケーション ID とテナント ID を安全な場所に記録します。 これらは、アプリケーション ページの [概要 ] の下に表示されます。

    Microsoft Defender ポータルの [概要] セクション

アプリを使用してトークンを取得し、トークンを使用して API にアクセスする

Microsoft Entra トークンの詳細については、Microsoft Entra チュートリアルを参照してください。

重要

このデモ アプリの例では、テスト目的でシークレット値を貼り付けることをお勧めしますが、運用環境で実行されているアプリケーションに シークレットをハードコーディングしないでください 。 サード パーティは、シークレットを使用してリソースにアクセスできます。 Azure Key Vaultを使用して、アプリのシークレットを安全に保つことができます。 アプリを保護する方法の実際の例については、「Azure Key Vaultを使用してサーバー アプリのシークレットを管理する」を参照してください。

  1. 以下のスクリプトをコピーし、お気に入りのテキスト エディターに貼り付けます。 Get-Token.ps1として保存します。 PowerShell ISE でそのままコードを実行することもできますが、次のセクションでインシデントフェッチ スクリプトを使用するときにもう一度実行する必要があるため、保存する必要があります。

    このスクリプトはトークンを生成 し、名前 の下の作業フォルダーにLatest-token.txt保存します。

    # This script gets the app context token and saves it to a file named "Latest-token.txt" under the current directory.
# Paste in your tenant ID, client ID and app secret (App key).

$tenantId = '' # Paste your directory (tenant) ID here
$clientId = '' # Paste your application (client) ID here
$appSecret = '' # # Paste your own app secret here to test, then store it in a safe place!

$resourceAppIdUri = 'https://api.security.microsoft.com'
$oAuthUri = "https://login.windows.net/$tenantId/oauth2/token"
$authBody = [Ordered] @{
  resource = $resourceAppIdUri
  client_id = $clientId
  client_secret = $appSecret
  grant_type = 'client_credentials'
}
$authResponse = Invoke-RestMethod -Method Post -Uri $oAuthUri -Body $authBody -ErrorAction Stop
$token = $authResponse.access_token
Out-File -FilePath "./Latest-token.txt" -InputObject $token
return $token

トークンを検証する

  1. 受け取ったトークンをコピーして JWT に貼り付けてデコードします。

  2. JWT は JSON Web トークンを表します。 デコードされたトークンには、多数の JSON 形式の項目または要求が含まれます。 デコードされたトークン内の ロール 要求に必要なアクセス許可が含まれていることを確認します。

    次の図では、、、および アクセス許可を持つIncidents.Read.AllIncidents.ReadWrite.Allアプリから取得されたデコードされたトークンをAdvancedHunting.Read.All確認できます。

    Microsoft Defender ポータルの [デコードされたトークン] セクション

最近のインシデントの一覧を取得する

次のスクリプトでは、 Get-Token.ps1 を使用して API にアクセスします。 次に、過去 48 時間以内に最後に更新されたインシデントの一覧を取得し、その一覧を JSON ファイルとして保存します。

重要

このスクリプトは、Get-Token.ps1保存したのと同じフォルダー に 保存します。

# This script returns incidents last updated within the past 48 hours.

$token = ./Get-Token.ps1

# Get incidents from the past 48 hours.
# The script may appear to fail if you don't have any incidents in that time frame.
$dateTime = (Get-Date).ToUniversalTime().AddHours(-48).ToString("o")

# This URL contains the type of query and the time filter we created above.
# Note that `$filter` does not refer to a local variable in our script --
# it's actually an OData operator and part of the API's syntax.
$url = "https://api.security.microsoft.com/api/incidents`?`$filter=lastUpdateTime+ge+$dateTime"

# Set the webrequest headers
$headers = @{
    'Content-Type' = 'application/json'
    'Accept' = 'application/json'
    'Authorization' = "Bearer $token"
}

# Send the request and get the results.
$response = Invoke-WebRequest -Method Get -Uri $url -Headers $headers -ErrorAction Stop

# Extract the incidents from the results.
$incidents =  ($response | ConvertFrom-Json).value | ConvertTo-Json -Depth 99

# Get a string containing the execution time. We concatenate that string to the name 
# of the output file to avoid overwriting the file on consecutive runs of the script.
$dateTimeForFileName = Get-Date -Format o | foreach {$_ -replace ":", "."}

# Save the result as json
$outputJsonPath = "./Latest Incidents $dateTimeForFileName.json"

Out-File -FilePath $outputJsonPath -InputObject $incidents

これで完了です。 これで次の操作が正常に完了しました。

  • アプリケーションを作成して登録しました。
  • そのアプリケーションにアラートを読み取るためのアクセス許可を付与しました。
  • API に接続されています。
  • PowerShell スクリプトを使用して、過去 48 時間以内に更新されたインシデントを返しました。

ヒント

さらに多くの情報を得るには、 Tech Community: Microsoft Defender XDR Tech Community の Microsoft Security コミュニティとEngageします。