Microsoft Defender for Endpoint API - Hello World

[アーティクル]
11/19/2024

適用対象:

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

注:

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

ヒント

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

us.api.security.microsoft.com
eu.api.security.microsoft.com
uk.api.security.microsoft.com
au.api.security.microsoft.com
swa.api.security.microsoft.com
ina.api.security.microsoft.com

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

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

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

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

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

アプリケーション登録ステージでは、Microsoft Entra テナントに適切なロールが割り当てられている必要があります。ロールの詳細については、「アクセス許可オプション」を参照してください。

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

Azure portal にサインインし
[Microsoft Entra ID>アプリの登録>新しい登録] に移動します。
登録フォームで、アプリケーションの名前を選択し、[ 登録] を選択します。
アプリケーションが Defender for Endpoint にアクセスし 、"すべてのアラートの読み取り" アクセス許可を割り当てることを許可します。
- アプリケーションページで、[API のアクセス許可]>、[アクセス許可の追加>AP organizationで使用する API を選択し>「WindowsDefenderATP」と入力し、[WindowsDefenderATP] を選択します。
  
  注:
  
  WindowsDefenderATP は元の一覧に表示されません。テキストボックスに名前を書き込んで表示する必要があります。
- [ アプリケーションのアクセス許可>Alert.Read.All] を選択し、[ アクセス許可の追加] を選択します。
  
  重要
  
  関連するアクセス許可を選択する必要があります。 すべてのアラートの読み取り は一例にすぎません。
  
  以下に例を示します。
  - 高度なクエリを実行するには、[詳細クエリの実行] アクセス許可を選択します。
  - マシンを分離するには、[マシンの分離] アクセス許可を選択します。
  - 必要なアクセス許可を決定するには、呼び出す API の アクセス許可 に関するセクションを参照してください。
[ 同意の付与] を選択します。

注:

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

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

重要

[追加] をクリックした後、 生成されたシークレット値をコピーします。出発後は取得できません。
アプリケーション 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 時間に作成されたアラートを返しました

ヒント

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

次の方法で共有

Microsoft Defender for Endpoint API - Hello World

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

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

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

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

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

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

フィードバック

その他のリソース

次の方法で共有

Microsoft Defender for Endpoint API - Hello World

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

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

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

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

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

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

関連記事

フィードバック

その他のリソース