📴

Microsoft Defender for EndpointをAPIでオフボードする

2023/02/18に公開

API

はじめに

Microsoft Defender for Endpoint(以下、MDE)をAPI経由でオフボードできないかな？となったのでまとめてみました。

オフボードとは

MDEにオンボードされたデバイスによるMDEへのテレメトリを停止することです。(意訳)

オフボードされたデバイスは管理センター上で「センサーの正常性状態」が「非アクティブ」に7日後に変わります。
また、「前回のデバイス更新日時」も更新が行われなくなるので、オフボードして24時間後に更新されていなければオフボードが完了したと判断できます。

注意点としてオフボードされたデバイスを管理センターから意図的に削除することはできません。
いつデータが削除されるかというと、テナント全体に設定してある保持期間(既定では180日)を過ぎるとデータが削除され、データ削除後180日以内にデバイスリストに表示されなくなります。(下記公式ドキュメントのとらえ方が間違えていたらご指摘ください)

Offboarded devices' data (such as Timeline, Alerts, Vulnerabilities, etc.) will remain in the portal until the configured retention period expires.
The device's profile (without data) will remain in the Devices List for no longer than 180 days.

不思議な仕様かと思いますが、例えば管理者アカウントが乗っ取られた時に攻撃者が管理センターでデバイスのデータを削除できないので追跡できる、というメリットがあります。

このあたりのMicrosoft Learnが役に立ちました。

Intuneによるオフボードの課題

Intune経由でオフボードする場合、Microsot 365 Defender管理センターでオフボードパッケージをダウンロードし、構成プロファイル(OMA-URI)を設定する作業が必要になります。

Intuneによるオフボードの課題として次のようなものがあります。

オフボードのパッケージの有効期間の~~30日間~~3日間なのでオフボードのたびに構成プロファイルを設定する必要がある
構成プロファイルの適用履歴のタイムラグ
デバイスをリタイヤ後にMEMでオフボード結果を確認できない

うっかりWindowsのオフボードを行わなかった場合、デバイスをIntuneからリタイヤ・利用者のライセンスの削除・アカウントのサインインを停止してもMDEへのテレメトリは停止されない仕組みになっています。
オフボードする機会は少ないと思いますが、場合によってはライセンス違反につながることもあると思うのでオンボードだけではなくオフボードの計画も十分に検討する必要があります。

とはいってもオフボードの方法は限られているので今回はAPI経由でのオフボードを検討しました。

MDEのAPIの概要

Windows Defender ATP APIがメインとなりますが、一部の機能(アラートやインシデントのリスト等)はMicrosoft Graphにも実装されています。

詳細は国井さんがまとめてくださっています。
https://azuread.net/archives/12787

ただし、Microsoft GraphにはデバイスをオフボードするためのAPIは未実装なので、Windows Defender ATP APIを使います。

Windows Defender ATP API アクセス許可

デバイスをオフボードするためのAPIのドキュメントになります。

制限事項に1分あたり100 呼び出しと1 時間あたり1500 呼び出しとあるので台数が多いときは注意してください。
また、現時点では一部のWindowsクライアントとサーバーで利用可能です。

Azure ADに登録したアプリで利用する場合は、
Azure AD > アプリの登録 > APIのアクセス許可 > アクセス許可の追加 > 所属する組織で使用しているAPIで「WindowsDefenderATP」と検索するとでてきます。

この中のMachine.Offboardです。

APIエクスプローラーで手軽に試してみる

PowerShellでもいいですが、手軽に試すにはMicrosoft 365 Defender > エンドポイント > パートナーとAPI > APIエクスプローラーがおすすめです。

サンプルクエリが多く用意されている

試しに特定のデバイスをオフボードしてみます。
デバイスIDが必要になるので、あらかじめデバイスIDを取得しておきます。

デバイス情報から取得できます

APIエクスプローラーで以下のように記載し「クエリを実行」をクリックすると、デバイスとMDEが通信次第オフボードされます。

post

https://api.securitycenter.microsoft.com/api/machines/デバイスID/offboard

body

{
  "Comment": "Offboard machine by automation"
}

コメントの中身は変えても大丈夫ですが必須です

実行したアクションの履歴もAPIエクスプローラーのサンプルクエリで簡単に確認できます。

普通に便利

オフボード作業だけ確認したい場合は次のクエリで取得できます。

GET

https://api-us.securitycenter.windows.com/api/machineactions?$filter=type eq 'Offboard'

MDEの管理者が行った作業の履歴を確認できるアクションセンターでも確認できます。

分かりやすい

オフボードしたデバイスはデバイスリストにしばらく表示されるのでデバイスタイムラインでも確認できます。

オフボード後はテレメトリを送信していなことがわかる

オフボードした後にログを確認できるのでこのあたりは活用できそうですが、エンタープライズ規模のデバイス台数だとPower AutomateやAzure Logic Appsで運用を固める必要があります。

デバイスタグを活用して効率よく管理

MDEではデバイスタグをデバイスに付与してデバイスを効率よく管理することができます。
特定のデバイスタグが付与されたデバイスをデバイスグループにまとめたり、そのグループに対してアクションを実行したり。

もちろんAPIでデバイスにデバイスタグを付与できるので、Power AutomateやAzure Logic Appsで運用の自動化もできます。
(海外の方がやっていたので紹介いたします)

おわりに

macのオフボードAPIも是非実装してほしいです。