Microsoft Defender for Endpoint API - Hello World

適用対象:

• Microsoft Defender for Endpoint Plan 1
• Microsoft Defender for Endpoint Plan 2

Microsoft Defender ATP を試してみたいですか? 無料試用版にサインアップしてください。

注:

米国政府機関のお客様の場合は、米国政府機関のお客様のMicrosoft Defender for Endpointに記載されている URI を使用してください。

ヒント

パフォーマンスを向上させるために、地理的な場所に近いサーバーを使用できます。

• api-us.securitycenter.microsoft.com
• api-eu.securitycenter.microsoft.com
• api-uk.securitycenter.microsoft.com
• api-au.securitycenter.microsoft.com

単純な PowerShell スクリプトを使用してアラートを取得する

この例を実行するのにどのくらいの時間がかかりますか?

次の 2 つの手順で 5 分しか実行されません。

• アプリケーションの登録
• 例を使用する: 短い PowerShell スクリプトのコピー/貼り付けのみが必要です

接続にアクセス許可が必要ですか?

アプリケーション登録ステージでは、Microsoft Entra テナントにグローバル管理者ロールが必要です。

手順 1 - Microsoft Entra IDでアプリをCreateする

1. グローバル管理者 ユーザーと共に Azure にログオンします。

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

   

3. 登録フォームで、アプリケーションの名前を選択し、[ 登録] をクリックします。

4. アプリケーションが Defender for Endpoint にアクセスし 、"すべてのアラートの読み取り" アクセス許可を割り当てることを許可します。

   • アプリケーション ページで、[API アクセス許可][アクセス許可>>の追加]API をクリックし、organizationがWindowsDefenderATP 型を使用>して WindowsDefenderATP をクリックします。

     注:

     WindowsDefenderATP は元の一覧に表示されません。 テキスト ボックスに名前を書き込んで表示する必要があります。

     

   • [ アプリケーションのアクセス許可>] [Alert.Read.All> ] [ アクセス許可の追加] の順にクリックします。

     

     重要

     関連するアクセス許可を選択する必要があります。 "すべてのアラートの読み取り" は一例にすぎません。

     以下に例を示します。

     • 高度なクエリを実行するには、[詳細クエリの実行] アクセス許可を選択します。
     • マシンを分離するには、[マシンの分離] アクセス許可を選択します。
     • 必要なアクセス許可を特定するには、呼び出す API の [アクセス許可] セクションを参照してください。

5. [ 同意の付与] をクリックします。

   注:

   アクセス許可を追加するたびに、[同意の 付与 ] をクリックして新しいアクセス許可を有効にする必要があります。

   

6. アプリケーションにシークレットを追加します。

   [ 証明書 & シークレット] をクリックし、シークレットに説明を追加し、[ 追加] をクリックします。

   重要

   [追加] をクリックした後、 生成されたシークレット値をコピーします。 出発後は取得できません。

   

7. アプリケーション ID とテナント ID を書き留めます。

   アプリケーション ページで、[ 概要 ] に移動し、次の内容をコピーします。

   

完了! アプリケーションが正常に登録されました。

手順 2 - アプリを使用してトークンを取得し、このトークンを使用して API にアクセスします。

• 次のスクリプトを PowerShell ISE またはテキスト エディターにコピーし、 Get-Token.ps1として保存します。

• このスクリプトを実行すると、トークンが生成され、 Latest-token.txtという名前 の作業フォルダーに保存されます。

  # That code gets the App Context Token and save it to a file named "Latest-token.txt" under the current directory
  # Paste below your Tenant ID, App ID and App Secret (App key).
  
  $tenantId = '' ### Paste your tenant ID here
  $appId = '' ### Paste your Application ID here
  $appSecret = '' ### Paste your Application secret here
  
  $resourceAppIdUri = 'https://api.securitycenter.microsoft.com'
  $oAuthUri = "https://login.microsoftonline.com/$TenantId/oauth2/token"
  $authBody = [Ordered] @{
       resource = "$resourceAppIdUri"
       client_id = "$appId"
       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
  

• サニティ チェック:

  • スクリプトを実行します。
  • ブラウザーで、 に移動します https://jwt.ms/。
  • トークン (Latest-token.txt ファイルの内容) をコピーします。
  • 上部のボックスに貼り付けます。
  • [ロール] セクションを探します。 Alert.Read.All ロールを見つけます。

  

アラートを取得しましょう。

• 次のスクリプトでは、 Get-Token.ps1 を使用して API にアクセスし、過去 48 時間のアラートを取得します。

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

• スクリプトは、スクリプトと同じフォルダーにデータを含む 2 つのファイル (json と csv) を作成します。

  # Returns Alerts created in the past 48 hours.
  
  $token = ./Get-Token.ps1       #run the script Get-Token.ps1  - make sure you are running this script from the same folder of Get-Token.ps1
  
  # Get Alert from the last 48 hours. Make sure you have alerts in that time frame.
  $dateTime = (Get-Date).ToUniversalTime().AddHours(-48).ToString("o")
  
  # The URL contains the type of query and the time filter we create above
  # Read more about [other query options and filters](get-alerts.md).
  $url = "https://api.securitycenter.microsoft.com/api/alerts?`$filter=alertCreationTime ge $dateTime"
  
  # Set the WebRequest headers
  $headers = @{
      'Content-Type' = 'application/json'
      Accept = 'application/json'
      Authorization = "Bearer $token"
  }
  
  # Send the webrequest and get the results.
  $response = Invoke-WebRequest -Method Get -Uri $url -Headers $headers -ErrorAction Stop
  
  # Extract the alerts from the results.
  $alerts =  ($response | ConvertFrom-Json).value | ConvertTo-Json
  
  # Get string with the execution time. We concatenate that string to the output file to avoid overwrite the file
  $dateTimeForFileName = Get-Date -Format o | foreach {$_ -replace ":", "."}
  
  # Save the result as json and as csv
  $outputJsonPath = "./Latest Alerts $dateTimeForFileName.json"
  $outputCsvPath = "./Latest Alerts $dateTimeForFileName.csv"
  
  Out-File -FilePath $outputJsonPath -InputObject $alerts
  ($alerts | ConvertFrom-Json) | Export-CSV $outputCsvPath -NoTypeInformation
  

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

• 作成および登録およびアプリケーション
• そのアプリケーションにアラートを読み取るためのアクセス許可が付与されました
• API の接続
• PowerShell スクリプトを使用して、過去 48 時間に作成されたアラートを返しました

関連トピック

• Microsoft Defender for Endpoint API
• アプリケーション コンテキストを使用してMicrosoft Defender for Endpointにアクセスする
• ユーザー コンテキストを使用してMicrosoft Defender for Endpointにアクセスする

ヒント

さらに多くの情報を得るには、 Tech Community 内の Microsoft Security コミュニティ (Microsoft Defender for Endpoint Tech Community) にご参加ください。