Microsoft Defender XDR advanced hunting API更新ポイント：旧API移行と管理者確認事項

Microsoft Defender XDR advanced hunting API を使って高度なハンティングクエリを自動実行している場合、最初に確認すべき結論は「旧APIを使い続ける前提で設計しない」ことです。Microsoft は、従来の https://api.security.microsoft.com/api/advancedhunting/run ではなく、Microsoft Graph security API の runHuntingQuery への移行を案内しています。従来APIは機能が限定された旧バージョンとして位置付けられており、Microsoft Graph 側の Advanced Hunting API が移行先になります。(Microsoft Learn)

特に影響を受けるのは、SOCの定型調査、Power Automate／Logic Apps、Power BIレポート、自社スクリプト、SIEM連携、チケット起票の自動化などで Advanced Hunting API を呼び出している環境です。単にエンドポイントを書き換えるだけではなく、権限、トークンの取得先、リクエスト本文、レスポンスのプロパティ名、クォータ、スキーマ変更まで確認する必要があります。

Microsoft Defender XDR advanced hunting API の位置付け

Microsoft Defender XDR advanced hunting API は、Microsoft Defender XDR の高度なハンティングクエリをAPI経由で実行するための仕組みです。KQLで記述したクエリを送信し、端末、メール、ID、クラウドアプリなどのセキュリティイベントをプログラムから取得できます。

従来APIの基本エンドポイントは次の形式です。

POST https://api.security.microsoft.com/api/advancedhunting/run

リクエスト本文には Query を指定し、成功時は Stats、Schema、Results を含むレスポンスが返ります。Microsoftの公式ドキュメントでは、従来APIについて「機能が制限された古いバージョン」と明記され、より包括的なAPIとして Microsoft Graph security API が案内されています。(Microsoft Learn)

実務上は、従来APIを「今から新規採用するAPI」ではなく、「既存資産の棚卸しと移行対象」と見なすべきです。

2026年6月24日更新情報で押さえるべき変更点

2026年6月24日に更新された Microsoft Defender XDR APIアクセス情報では、Microsoft Defender APIを利用する一般的な流れとして、Microsoft Entra アプリケーションの作成、アクセストークンの取得、トークンを使ったAPIアクセスが示されています。APIアクセスには OAuth 2.0 認証が必要で、バックグラウンドサービスやデーモンのようにサインインユーザーなしで動くアプリでは Application context が推奨されています。(Microsoft Learn)

管理者視点で重要なのは、次の3点です。

確認項目	従来の見方	今後の実務判断
APIの選定	Defender XDR の旧 Advanced Hunting API を直接呼び出す	Microsoft Graph security API の runHuntingQuery を優先する
認証設計	既存の Defender API 用アプリ登録と権限で運用	Microsoft Graph 用の権限、同意、トークン発行先を再確認する
自動化の保守	KQLが動けば十分と考える	レスポンス形式、クォータ、スキーマ変更まで含めて移行テストする

ここで失敗しやすいのは、「KQLの中身は同じだから、そのまま動く」と判断してしまうことです。実際には、APIの呼び出し先、権限名、レスポンス構造、期間指定の扱いが変わるため、連携先のJSONパース処理やCSV出力処理まで確認が必要です。

旧APIと Microsoft Graph security API の違い

Microsoft Graph security API では、Advanced Hunting の実行に POST /security/runHuntingQuery を使います。Microsoftの移行情報では、旧APIの https://api.security.microsoft.com/api/advancedhunting/run と https://api.securitycenter.microsoft.com/api/advancedqueries/run は、Microsoft Graph の https://graph.microsoft.com/beta/security/runHuntingQuery へ移行する対象として整理されています。また、旧APIは2027年2月1日にデータを返さなくなると説明されています。(Microsoft Learn)

現行の Microsoft Graph v1.0 ドキュメントでは、runHuntingQuery のHTTP要求は次の形式です。(Microsoft Learn)

POST https://graph.microsoft.com/v1.0/security/runHuntingQuery
Content-Type: application/json
Authorization: Bearer {token}

リクエスト例は次のようになります。

{
  "Query": "DeviceProcessEvents | where InitiatingProcessFileName =~ \"powershell.exe\" | project Timestamp, FileName, InitiatingProcessFileName | order by Timestamp desc | limit 2"
}

必要に応じて Timespan も指定できます。

{
  "Query": "DeviceProcessEvents",
  "Timespan": "P30D"
}

ただし、期間指定を広げれば必ず過去データを無制限に取得できるわけではありません。Advanced Hunting には保持期間やクォータがあり、テーブルやサービス側のデータ保持条件にも依存します。既存レポートで30日を超える分析をしている場合は、移行時に結果件数と対象期間を必ず比較してください。

旧APIと移行先APIの比較

項目	従来の Microsoft Defender XDR advanced hunting API	Microsoft Graph security API
主な用途	Defender XDR の高度なハンティングをAPI実行	Microsoft Graph 経由で高度なハンティングを実行
エンドポイント	https://api.security.microsoft.com/api/advancedhunting/run	https://graph.microsoft.com/v1.0/security/runHuntingQuery
権限	AdvancedHunting.Read.All、AdvancedHunting.Read	ThreatHunting.Read.All
リクエスト本文	Query	Query、必要に応じて Timespan
レスポンス	Stats、Schema、Results	schema、results
移行上の注意	旧バージョンとして扱われる	新規実装・移行先として検討する

旧APIのレスポンスでは Schema と Results が大文字始まりですが、Microsoft Graph の huntingQueryResults では schema と results が使われます。JSONをそのままオブジェクト変換しているPowerShell、Python、JavaScript、Power BI Mクエリでは、この違いで後続処理が失敗することがあります。(Microsoft Learn)

影響範囲：どの管理者・システムが確認すべきか

Microsoft Defender XDR advanced hunting API の変更で影響を受けるのは、Defenderポータルを手動で使う担当者だけではありません。むしろ、見落としやすいのはバックグラウンドで動いている自動化です。

影響を受ける対象	具体例	確認ポイント
SOC運用	日次の不審プロセス抽出、IoC照合、端末調査	APIエンドポイント、KQL、結果件数、タイムアウト
SIEM連携	Splunk、Sentinel、独自ログ基盤への転送	旧APIコネクタの利用有無、Graph対応状況
Power Automate／Logic Apps	検知結果をTeams通知、チケット作成	コネクタの有無、カスタムコネクタ化の必要性
Power BI	Advanced Hunting結果の可視化	Power Query内のURL、レスポンス列名、更新スケジュール
自社スクリプト	PowerShell、Python、Node.jsでの定期実行	トークン取得先、権限、429時の再試行制御
MSSP／マルチテナント運用	顧客テナント横断のハンティング	テナントごとの同意、クォータ、各国クラウド対応

Microsoft Graph security API の説明では、Power Platform フローで従来の Microsoft Defender ATP コネクタの Advanced Hunting アクションを使っている場合、継続利用には Microsoft Graph のパラメータを使ったカスタムコネクタ作成が必要になる旨も示されています。Power BI のカスタムレポートも、Microsoft Graph のパラメータに合わせた更新が必要です。(Microsoft Learn)

移行期限：2027年2月1日を待たずに対応する

Microsoft Graph security API の移行説明では、従来の Advanced Hunting API は retired とされ、2027年2月1日にデータを返さなくなると説明されています。したがって、管理者は2027年2月1日を「作業開始日」ではなく「旧API依存を残してはいけない期限」として扱うべきです。(Microsoft Learn)

実務では、少なくとも次のように逆算すると安全です。

時期	推奨アクション
すぐに	旧エンドポイントを使っているスクリプト、フロー、BI、コネクタを棚卸しする
移行設計時	Microsoft Graph 用のEntraアプリ、権限、管理者同意を整理する
検証時	旧APIとGraph APIで同じKQLを実行し、件数・列・型・時間範囲を比較する
本番移行前	429、タイムアウト、空結果、権限不足時のエラー処理を確認する
2027年1月中	旧APIを呼ぶ本番処理を停止またはGraph API版へ切り替える

特に24時間365日の監視運用では、API停止後に初めて気づくと、定期レポートの欠落やインシデント初動の遅れにつながります。監視ジョブのログに api.security.microsoft.com や api.securitycenter.microsoft.com が残っていないか、早めに検索してください。

必要な権限と認証の見直し

従来の Microsoft Defender XDR advanced hunting API では、アプリケーション権限として AdvancedHunting.Read.All、委任権限として AdvancedHunting.Read が示されています。ユーザー資格情報でトークンを取得する場合は、ユーザーに View Data ロールが必要で、さらにデバイスグループ設定に基づくアクセス権も必要です。(Microsoft Learn)

一方、Microsoft Graph の runHuntingQuery では、最小権限として委任・アプリケーションのいずれも ThreatHunting.Read.All が示されています。個人用 Microsoft アカウントはサポート対象外です。(Microsoft Learn)

設定変更で確認すべき項目

設定項目	確認内容
Entraアプリ登録	旧API専用のアプリを流用するか、新規にGraph用アプリを作成するか決める
APIアクセス許可	Microsoft Graph の ThreatHunting.Read.All を付与しているか
管理者同意	アプリケーション権限を使う場合、テナント管理者の同意が完了しているか
トークンのaudience	graph.microsoft.com 向けのトークンを取得しているか
実行主体	ユーザー委任か、アプリケーション権限かを明確にしているか
秘密情報管理	クライアントシークレットや証明書をKey Vault等で安全に管理しているか
ロール設計	SOC担当者、開発者、MSSPに過剰権限を与えていないか

バックグラウンドで定期実行する用途では、ユーザーの退職やロール変更に左右されない Application context が実務上扱いやすいケースが多いです。ただし、アプリケーション権限は影響範囲が広くなりやすいため、用途ごとにアプリを分け、アクセスログを追跡できる設計にしておくと事故調査が容易になります。

クォータと制限：API移行後も性能問題は残る

Advanced Hunting API は、大量データを自由に取り出すための無制限APIではありません。従来APIでは、過去30日間のデータ探索、最大100,000行の結果、テナントごとの呼び出し数、CPUリソース、3分を超えるリクエストのタイムアウト、429応答などの制約が示されています。(Microsoft Learn)

Microsoft Graph security API 側でも、Advanced Hunting は過去30日のデータ、最大100,000行、少なくとも45 calls/min/tenant、CPUリソース、3分超のタイムアウト、429応答、さらに結果全体のサイズ制限に注意が必要です。(Microsoft Learn)

運用で避けたいのは、次のようなクエリです。

DeviceProcessEvents
| where Timestamp > ago(30d)

このように全列・広範囲で取得すると、CPUや結果サイズを消費しやすくなります。APIで定期実行する場合は、最初から列を絞り、時間範囲を短くし、必要な集計をKQL側で済ませるのが基本です。

改善例は次の通りです。

DeviceProcessEvents
| where Timestamp > ago(1d)
| where InitiatingProcessFileName =~ "powershell.exe"
| project Timestamp, DeviceName, FileName, ProcessCommandLine, InitiatingProcessFileName
| take 5000

さらに定期実行ジョブでは、429が返った場合に即時リトライを繰り返さない設計が必要です。レスポンス本文を確認し、再開可能な時刻や制限内容をログに残すようにしてください。

クエリリソースレポートで重いAPIクエリを見つける

Microsoft Defender XDR には、過去30日間に実行されたクエリをもとに、ハンティング用CPUリソースの消費状況を確認できるクエリリソースレポートがあります。このレポートでは、ポータル、カスタム検出、APIクエリなど、どのインターフェイスから実行されたか、実行ユーザーまたはアプリ、リソース使用量、状態、クエリ時間、時間範囲などを確認できます。(Microsoft Learn)

API移行前には、次の観点で確認すると効果的です。

観点	見るべきポイント	対応例
リソース使用量が高い	API経由で高負荷クエリが定期実行されていないか	project、summarize、時間範囲短縮で最適化
失敗が多い	タイムアウト、権限不足、スキーマ変更の影響がないか	エラー内容を分類し、KQLと権限を修正
429が発生	同時実行や短周期実行が多すぎないか	スケジュール分散、指数バックオフを実装
利用アプリが不明	古いアプリ登録や退職者作成の自動化が残っていないか	Entraアプリの所有者と用途を棚卸し

移行作業では、単に「Graph APIで動いた」だけでは不十分です。本番と同じ頻度、同じテナント規模、同じ件数でテストし、リソース使用量が許容範囲に収まるか確認してください。

スキーマ変更にも注意：KQLが突然動かなくなる原因

Advanced Hunting API の移行で見落としやすいのが、APIそのものではなく「KQLが参照するテーブルや列の変更」です。Microsoft Defender XDR の高度なハンティングスキーマは、新しいテーブルや列の追加に伴って名前変更が行われる場合があります。Microsoft Defender XDRに保存されたクエリやカスタム検出ルールは自動更新される場合がありますが、APIで実行するクエリやDefender XDR外部に保存されたクエリは手動更新が必要です。(Microsoft Learn)

2026年6月の変更では、AIAgentsInfo テーブルが AgentsInfo テーブルへ移行し、AIAgentsInfo は移行期間として2026年7月1日までアクセス可能と説明されています。2026年7月時点で外部スクリプトやPower BI、SIEM側に AIAgentsInfo が残っている場合、優先的に修正すべきです。(Microsoft Learn)

確認すべき場所は、Defenderポータル内だけではありません。

保存場所	確認方法
PowerShell／Pythonスクリプト	リポジトリ内で旧テーブル名・旧列名を全文検索
Logic Apps／Power Automate	HTTPアクション、カスタムコネクタ、変数内のKQLを確認
Power BI	Power Query、パラメータ、データソース設定を確認
SIEM	検索マクロ、保存済み検索、アドオン設定を確認
チケット連携	WebhookやFunction内のクエリ文字列を確認

API移行とスキーマ変更を別々に管理すると、切り替え後に「APIは成功しているが結果が空」「列が存在しない」「JSON変換で失敗する」といった障害が起きます。移行テストでは、KQLの実行可否だけでなく、結果の列名と型まで確認してください。

Microsoft Sentinel 連携環境での注意点

Microsoft Defender XDR と Microsoft Sentinel を統合している環境では、「Defender XDR Advanced Huntingで動くクエリ」と「Sentinel側で同じように使えるクエリ」を混同しないことが重要です。

たとえば、2026年6月24日に更新された DeviceTvmSoftwareVulnerabilitiesKB の公式情報では、この Defender Vulnerability Management のTVMテーブルは Microsoft Sentinel に取り込まれず、Sentinel側ではスキーマ可視性のために公開されるだけで、直接クエリしても結果を返さないと説明されています。実データを取得するには Defender XDR Advanced Hunting 側でクエリを実行する必要があります。(Microsoft Learn)

これは、API移行時の設計に大きく影響します。脆弱性管理やTVM系テーブルを使ったレポートをSentinel分析ルールへそのまま移すと、期待した結果が返らない可能性があります。Defender XDR APIで取得するのか、Sentinelに別経路で取り込むのか、最初にデータの所在を確認してください。

グローバル環境での対応ポイント

Microsoft Graph の runHuntingQuery は、グローバルサービス、US Government L4、US Government L5では利用可能とされていますが、中国の21Vianet環境は対象外として示されています。グローバル企業やMSSPでは、テナントのクラウド種別ごとに同じ実装を使えるか確認が必要です。(Microsoft Learn)

グローバル運用で特に確認したいのは次の点です。

項目	確認ポイント
クラウド種別	Global、GCC、GCC High、DoD、21VianetでAPI対応が異なる可能性
時刻	Advanced HuntingのクエリはUTCで記述する
権限管理	国・地域ごとのSOC担当者に過剰なGraph権限を与えていないか
データ所在地	データ保持、ログ転送、法務要件とAPI取得範囲が矛盾しないか
運用時間帯	テナントごとのクォータを考慮し、定期実行時刻を分散する

Advanced Hunting はクエリでUTCを使い、結果は設定されたタイムゾーンに変換されます。日本時間や米国時間でレポートを作る場合でも、KQL内部の期間指定はUTC基準で設計してください。(Microsoft Learn)

管理者が今すぐ実施すべきチェックリスト

Microsoft Defender XDR advanced hunting API の移行では、次の順番で確認すると抜け漏れを減らせます。

旧API利用の棚卸し

まず、ソースコード、ジョブ定義、Power Automate、Logic Apps、Power BI、SIEM設定で次の文字列を検索します。

api.security.microsoft.com/api/advancedhunting/run
api.securitycenter.microsoft.com/api/advancedqueries/run
AdvancedHunting.Read
AdvancedHunting.Read.All

見つかった場合は、用途、実行頻度、所有者、重要度、停止時の影響を一覧化します。所有者不明のジョブは、移行対象として最優先で確認してください。

Microsoft Graph APIへの変更

次に、呼び出し先を Microsoft Graph の runHuntingQuery に変更します。

POST https://graph.microsoft.com/v1.0/security/runHuntingQuery

あわせて、Entraアプリに ThreatHunting.Read.All を付与し、必要な管理者同意を完了します。アプリケーション権限で動かす場合は、テナント全体のセキュリティデータへアクセスできる可能性があるため、用途別のアプリ分割と監査ログの確認を行ってください。

レスポンス処理の修正

旧APIからGraph APIへ移行すると、レスポンス構造の扱いが変わります。

{
  "schema": [],
  "results": []
}

旧APIの Schema、Results を前提にしている処理は修正が必要です。Power BIで列展開している場合や、Pythonで response["Results"] のように大文字キーを参照している場合は、移行後に失敗します。

クエリとスキーマの点検

KQL内で古いテーブル名や列名を参照していないか確認します。特に、Defender XDR外部に保存されたクエリは自動更新されないため、リポジトリやBI、SIEM内のKQLを全文検索してください。

確認例です。

AIAgentsInfo
AADSignInEventsBeta
AADSpnSignInEventsBeta
AadDeviceId

該当があれば、現在のAdvanced Huntingスキーマに合わせて修正し、同じ条件で旧結果と新結果を比較します。

エラー処理と監視の追加

API移行後は、成功・失敗だけでなく、次の情報をログに残します。

ログ項目	目的
HTTPステータスコード	401、403、429、5xxを分類する
実行したKQLの識別子	問題のあるクエリを特定する
実行時間	タイムアウトや高負荷クエリを検出する
結果件数	空結果や上限到達を検知する
利用アプリID	どの自動化が実行したか追跡する
テナントID	マルチテナント運用で影響範囲を特定する

特に429は、単なる一時エラーではなくクォータやCPUリソース消費のサインです。短時間に再試行を繰り返すと、さらに調整を悪化させる可能性があります。

失敗しやすいポイント

エンドポイントだけ変更して権限を変えていない

旧API用の権限を持つアプリでGraph APIを呼び出しても、必要なMicrosoft Graph権限がなければ失敗します。AdvancedHunting.Read.All から ThreatHunting.Read.All への見直しを忘れないでください。

JSONの大文字・小文字差を見落とす

旧APIの Results を前提にしている処理は、Graph APIの results では動かないことがあります。JavaScriptやPythonではキー名の大文字小文字が区別されるため、移行テストで必ず確認してください。

ポータルで動くKQLをAPIでも同じ条件で動くと考える

ポータルとAPIでは制限や実行条件が異なる場合があります。特に、結果サイズ、タイムアウト、クォータ、テーブルのデータ所在に注意が必要です。

Sentinelとの統合範囲を誤解する

Defender XDRのAdvanced Huntingテーブルが、必ずSentinelでデータとして利用できるとは限りません。TVM系テーブルのように、Sentinel側ではスキーマ可視性のみで結果が返らないケースがあります。(Microsoft Learn)

旧クエリをDefenderポータル外に保存している

Defender XDR内の保存クエリやカスタム検出は自動更新される場合がありますが、外部保存されたクエリは管理者が直す必要があります。API移行時には、KQLの保管場所をすべて洗い出してください。(Microsoft Learn)

実務での移行手順

最後に、管理者が実行しやすい形で移行手順を整理します。

手順	作業内容	完了条件
1	旧APIエンドポイントを検索	対象スクリプト・フロー・レポートが一覧化されている
2	重要度を分類	SOC運用、監査、経営レポートなど影響度が分かる
3	Graph用Entraアプリを準備	ThreatHunting.Read.All と管理者同意が完了している
4	API呼び出しを変更	graph.microsoft.com/v1.0/security/runHuntingQuery で実行できる
5	レスポンス処理を修正	schema と results を正しく処理できる
6	KQLを点検	古いテーブル名・列名が残っていない
7	旧APIと結果比較	件数、列、型、期間、NULL値の差分を説明できる
8	クォータ対策	429、タイムアウト、空結果時の処理が実装されている
9	本番切り替え	旧APIジョブを停止し、Graph API版に切り替わっている
10	監視を継続	実行ログ、失敗率、結果件数を定期確認している

Microsoft Defender XDR advanced hunting API の更新ポイントは、APIの使い方そのものよりも「旧API依存をいつ、どの範囲で、どう安全にGraphへ移すか」にあります。まずは旧エンドポイントの棚卸しを行い、権限、レスポンス処理、KQLスキーマ、クォータの4点をセットで確認してください。2027年2月1日を待つのではなく、既存自動化の重要度が高いものから順に Microsoft Graph security API へ移行することが、運用停止を避ける最も確実な対応です。