Microsoft GraphからMicrosoft Defender for Endpointを操作

Microsoft Defender

皆さんこんにちは。国井です。
EDRの世界では一定の市民権を得たMicrosoft Defender for Endpoint (MDE) ですが、お客さんと話をしているとAPIアクセスで自動化を実現したいという声をよく聞きます。
Microsoft 365のAPIと言えばMicrosoft Graphですが、残念ながらつい最近までMDEはWindows Defender ATP APIという別のAPIからのアクセスが必要だったんですよね…
それが最近、Microsoft GraphからMDEにアクセスできるようになったと聞いたので早速使ってみることにしました。

TECHCOMMUNITY.MICROSOFT.COM
 
The new Microsoft 365 Defender APIs in Microsoft Graph are now available in p...
https://techcommunity.microsoft.com/t5/microsoft-365-defender-blog/the-new-microsoft-365-defender-apis-in-microsoft-graph-are-now/ba-p/3603099
Customers have been asking for unified APIs that are part of the Microsoft Graph with a single endpoint, permissions, auth model, and access token. We’re happy to share that the new Microsoft 365 Defender APIs in MS Graph: Incidents, Alerts, and Hunting, are now in public preview! What’s new Alert...

アラートを取得してみる

今回はMDEからアラートを取得する設定を行ってみたいと思います。
やることは次の2つです。

1．APIアクセスに必要なアプリの登録
2．Microsoft Graphからアラートを取得するためのPowerShellスクリプト

では早速始めましょう。

アプリの登録

Azure AD管理センター改め、Microsoft Entra管理センターにアクセスしてアプリを新規作成します。MDEという名前だけを設定してアプリを作成し、出来上がったアプリからアプリケーションIDを控えておきます。

image

次に[証明書とシークレット]からクライアントシークレットを作成します。
作成したら値を控えておきましょう。言うまでもないことですが、作成したシークレットには有効期限があるので、定期的な再生成が必要なのでご注意を。

image

次に[APIのアクセス許可]にアクセスしてMDEのアラートにアクセスするために必要なAPIへのアクセス許可を設定します。Microsoft Learnによるとアラートを一覧表示するために必要なアクセス許可はSecurityAlert.Read.Allとのことなので、

learn.microsoft.com
alerts_v2を一覧表示する - Microsoft Graph v1.0
https://learn.microsoft.com/ja-jp/graph/api/security-list-alerts_v2?view=graph-rest-1.0&tabs=http
セキュリティ アラート オブジェクトとそのプロパティの一覧を取得します。

アクセス許可の追加 > Microsoft Graph > アプリケーションの許可 > SecurityAlert.Read.All を追加します。
追加したら管理者の同意を与える設定を行ってください。

image

PowerShellスクリプトの作成

続いてPowerShellスクリプトを作りましょう。Microsoft GraphへアクセスするためのPowerShellスクリプトは… って書こうと思ったら既に紹介してくださっている方がいらしたので参考にさせていただくことにしました (ありがとうございます！)。

Qiita
 
Microsoft GraphAPIをつかってみよう。-- 実践 編-- - Qiita
https://qiita.com/kura_yu/items/772d68498eb47de09cf8
・はじめに前回は、Microsoft Graph APIを利用するためのアプリ登録手順についてお話ししました。※Microsoft Graph APIをつかってみよう。-- 事前準備 編--今回は、登録したアプリを使って...

ここからAPIアクセスする先を変えましょう。
今回アクセスするAPIは

GET /security/alerts_v2

なので、これを踏まえてこんな感じで書いてみました。

#######################GraphAPI接続 start
$clientid = "アプリケーション（クライアント）ID"
$tenantName = "アプリを登録したテナントのドメイン　例（QiitaTest2020.onmicrosoft.com）"
$clientSecret = "クライアント シークレット"

$ReqTokenBody = @{
Grant_Type    = "client_credentials"
Scope         = "https://graph.microsoft.com/.default"
client_Id     = $clientID
Client_Secret = $clientSecret
}

$TokenResponse = Invoke-RestMethod -Uri "https://login.microsoftonline.com/$tenantName/oauth2/v2.0/token" -Method POST -Body $ReqTokenBody
#######################GraphAPI接続 end

#######################GraphAPIで情報取得
$apiUrl = 'https://graph.microsoft.com/v1.0/security/alerts_v2'
$Data = Invoke-RestMethod -Headers @{Authorization = "Bearer $($Tokenresponse.access_token)"} -Uri $apiUrl -Method Get
$Alert = ($Data | select-object Value ).Value
$Alert

出力結果を絞り込む

本編はここまでで終わりなのですが、もうひとつだけ。
アラートをせっかく出したので一部の内容だけに絞り込みたい！というニーズもあるでしょう。例えばアラートの状態が「進行中」に設定されているものだけ出力したい場合。
本来であればODataクエリパラメータというのを利用してフィルター設定をします。
ところが、これがうまく動かったんですよね..
ということで最後の行を

$Alert

の代わりに次のように設定してみました。

$Alert | Where-Object {$_.status -eq “inProgress”}

するとこんな感じで進行中 (inProgress) のアラートだけが表示されました。

image

MDEだとアラートが出力されたら xxx する、みたいなインシデント対応が必要になるケースもありますが、そうしたときに便利だと思うんですよね。
今回はPowerShellスクリプトから実行する方法でしたが、Logic AppsやPower Automateと組み合わせて利用する応用なんかもできるので是非活用してみてください。

Suguru KUNII