Microsoft Graph security API を使ってセキュリティ運用を自動化している組織は、まず レガシ アラート API、アラート v2、インシデント、Advanced Hunting、権限、証拠データのパーサー を確認すべきです。特に /security/alerts を使っているアプリや SIEM 連携、Power BI レポート、Power Automate フローは、単なるエンドポイント差し替えでは済まない可能性があります。
結論として、既存環境で最優先に確認すべき点は3つです。1つ目は、レガシ アラート API の /security/alerts が 2026年8月31日に廃止予定であり、/security/alerts_v2 と /security/incidents への移行が必要なこと。2つ目は、Advanced Hunting の旧エンドポイントが 2027年2月1日にデータを返さなくなる予定であること。3つ目は、2026年5月12日に更新された関連リソース型を含め、alertEvidence の証拠データがより細かい型で扱われるため、連携アプリ側のデータモデルやフィルター条件を見直す必要があることです。(Microsoft Learn)
Microsoft Graph security APIで何ができるのか
Microsoft Graph security API は、Microsoft とエコシステム パートナーのセキュリティ ソリューションを統合するための API です。複数のセキュリティ プロバイダーに対するクエリを集約し、アラート、インシデント、証拠、セキュア スコア、脅威インテリジェンス、監査、eDiscovery などを Microsoft Graph 経由で扱えるようにします。(Microsoft Learn)
実務での用途は、単に「アラート一覧を取得する」だけではありません。たとえば、SOC のトリアージ画面にインシデント情報を取り込む、SIEM に Microsoft Defender のアラートを送る、Power BI で月次の検知傾向を可視化する、重大度の高いインシデントだけをチケット化する、といった使い方が想定されます。
| 確認項目 | 影響を受ける場面 | 最初にやること |
|---|---|---|
| レガシ アラート API | /security/alerts を使うアプリ、スクリプト、SIEM 連携 | /security/alerts_v2 と /security/incidents への移行対象を洗い出す |
| インシデント中心の設計 | 複数アラートを手作業で関連付けている運用 | インシデント単位で一覧・詳細・更新する設計に変える |
| 証拠データの型 | JSON パース、ETL、Power BI、チケット項目 | userStates など旧フィールド前提の処理を typed evidence に置き換える |
| Advanced Hunting | 旧 Advanced Hunting API、Power Platform、Power BI | エンドポイント、権限、リクエスト本文、レスポンス形式を見直す |
| 権限とロール | 委任アクセス、アプリケーション権限、管理者同意 | 最小権限と Microsoft Entra ロールを再確認する |
| Microsoft Sentinel | Sentinel アラートを Graph で取得する運用 | Sentinel ワークスペースが Defender ポータルに接続済みか確認する |
重要な変更点は「アラート中心」から「インシデント中心」への移行
今回の要点は、Microsoft Graph security API のアラート管理が、従来の単独アラート中心から、インシデントと証拠を軸にしたモデルへ移っていることです。
レガシ アラート API は /security/alerts で利用されてきましたが、Microsoft はこのエンドポイントを非推奨とし、2026年8月31日に廃止予定としています。移行先は /security/alerts_v2 と /security/incidents です。さらに、新 API はレガシ API の一対一の置き換えではなく、Microsoft 365 Defender エコシステム内のアラートとインシデントを扱うモデルです。(Microsoft Learn)
| 操作 | 旧API | 新API |
|---|---|---|
| アラート一覧取得 | GET /v1.0/security/alerts | GET /v1.0/security/alerts_v2 |
| アラート詳細取得 | GET /v1.0/security/alerts/{id} | GET /v1.0/security/alerts_v2/{id} |
| アラート更新 | PATCH /v1.0/security/alerts/{id} | PATCH /v1.0/security/alerts_v2/{id} |
| インシデント一覧取得 | なし | GET /v1.0/security/incidents |
| インシデント詳細取得 | なし | GET /v1.0/security/incidents/{id} |
旧 API では、アプリ側で複数のアラートを集約し、同じ攻撃かどうかを判断する実装が必要になりがちでした。新しい alerts and incidents API では、関連するアラートがインシデントとしてまとめられ、攻撃の開始地点、使われた戦術、影響範囲、関連データを把握しやすくなります。(Microsoft Learn)
既存アプリで壊れやすいポイント
移行時に失敗しやすいのは、エンドポイントだけを置き換えてしまうケースです。たとえば、旧 API の vendorInformation.provider をもとに製品別集計をしていた場合、新 API では serviceSource や productName を使う設計に変える必要があります。また、userStates、hostStates、fileStates、networkConnections のような旧フィールドは、v2 では typed evidence に置き換えて考える必要があります。(Microsoft Learn)
つまり、移行作業では次の3点を分けて確認してください。
| 観点 | 確認内容 |
|---|---|
| API呼び出し | 旧エンドポイントを使っていないか |
| データモデル | 旧フィールド名や旧JSON構造を前提にしていないか |
| 業務フロー | アラート単位の対応からインシデント単位の対応へ変更できるか |
2026年5月12日更新の関連リソースで見る証拠データの拡張
Microsoft Graph security API の alertEvidence は、アラートに関係する証拠を表す基底型です。公式ドキュメントでは、ユーザー、デバイス、IP、URL、ファイル、クラウドリソースなど多数の派生型が定義されています。これにより、アラート本文の自由記述を解析するのではなく、型付きの証拠データとして処理しやすくなります。(Microsoft Learn)
2026年5月12日に更新された関連リソース型では、GitHub、サービス プリンシパル、SAS トークン、マルウェア、ホストログオン セッションなど、調査時に重要な証拠を扱うページが確認できます。(Microsoft Learn)
| 証拠リソース型 | 表す内容 | 実務上の見どころ |
|---|---|---|
gitHubOrganizationEvidence | GitHub 組織 | 組織ID、ログイン名、表示名、URLをSOCや資産台帳と突合できる |
gitHubUserEvidence | GitHub ユーザー | ユーザーID、ログイン名、メールアドレスを開発者アカウント管理と照合できる |
gitHubRepoEvidence | GitHub リポジトリ | リポジトリID、オーナー、オーナー種別をサプライチェーン調査に使える |
servicePrincipalEvidence | セキュリティ検出に関係するサービス プリンシパル | appId、tenantId、servicePrincipalType をもとに不審なアプリ権限を追跡できる |
sasTokenEvidence | Storage コンテナー向け SAS トークン | 有効期限、許可IP、権限、プロトコル、署名元キーを確認できる |
malwareEvidence | 検出アラートに含まれるマルウェア | マルウェア名、カテゴリ、関連ファイル、関連プロセスを紐づけられる |
hostLogonSessionEvidence | ホストへのサインイン セッション | アカウント、ホスト、セッションID、開始・終了時刻を調査できる |
この変更の価値は、アラートの説明文を人間が読むだけでなく、開発者が自動処理しやすい形で証拠を扱える点にあります。たとえば、SAS トークンの期限が長すぎるアラートだけを抽出する、GitHub リポジトリに関係する検知を開発部門のチケットへ自動転送する、サービス プリンシパルの appId を Microsoft Entra ID のアプリ登録と照合するといった展開がしやすくなります。
unknownFutureValueを前提に実装する
Microsoft Graph security API の証拠リソースには、unknownFutureValue を含む列挙型が複数あります。さらに一部の列挙値は、Prefer: include-unknown-enum-members ヘッダーを使うことで取得できるとされています。(Microsoft Learn)
実装時は、未知の列挙値が来たときに処理を落とさないようにしてください。悪い実装例は、switch 文で既知の値だけを処理し、それ以外を例外にするパターンです。SOC 連携やチケット起票のような継続運用では、未知値は「その他」や「未分類」として保持し、ログに残すほうが安全です。
管理者が確認すべき設定
アプリ登録の権限を最小権限で見直す
alerts_v2 の読み取りでは、委任権限・アプリケーション権限ともに最小権限として SecurityAlert.Read.All が示されています。読み書きには SecurityAlert.ReadWrite.All が必要です。委任アクセスの場合、サインイン ユーザーには Security Reader、Global Reader、Security Operator、Security Administrator などの対応する Microsoft Entra ロールも必要です。(Microsoft Learn)
インシデントの読み取りでは SecurityIncident.Read.All、読み書きでは SecurityIncident.ReadWrite.All が使われます。こちらも委任アクセスでは対応する Microsoft Entra ロールが必要です。(Microsoft Learn)
| 目的 | 最小権限の例 | 注意点 |
|---|---|---|
| アラートを読む | SecurityAlert.Read.All | レポートやSIEM取り込み向け |
| アラートを更新する | SecurityAlert.ReadWrite.All | status、classification、determination、assignedTo などを更新する運用向け |
| インシデントを読む | SecurityIncident.Read.All | インシデント一覧、詳細、ダッシュボード向け |
| インシデントを更新する | SecurityIncident.ReadWrite.All | SOC の割り当て、ステータス更新、ワークフロー連携向け |
管理者が見落としやすいのは、API 権限を付けただけで終わってしまうことです。アプリケーション権限を追加した場合は管理者同意が必要です。委任アクセスでは、ユーザー側のロール不足で API 呼び出しが失敗することがあります。
Microsoft Sentinelを使っている場合はDefenderポータル接続を確認する
Microsoft Sentinel のアラートとインシデントを v2 API で扱いたい場合、Sentinel ワークスペースを Microsoft Defender ポータルに接続する必要があります。接続されていない Sentinel 由来のアラートや、Microsoft 365 Defender のインシデント モデルに入っていないスタンドアロン アラートは、新しい v2 API で返らない可能性があります。(Microsoft Learn)
確認すべきポイントは次の通りです。
| 確認項目 | 判断基準 |
|---|---|
| Sentinel ワークスペース | Defender ポータルにオンボード済みか |
| 既存の Sentinel 連携 | Graph v2 API で取得するのか、Sentinel REST API も併用するのか |
| スタンドアロン検知 | Defender のインシデントに昇格しない検知を別経路で取得する必要があるか |
| チケット連携 | Sentinel と Defender の二重起票になっていないか |
特に、移行直後は「旧 API では取れていたアラートが v2 で見えない」という問い合わせが起きやすくなります。これは不具合ではなく、v2 API の対象範囲や Sentinel の接続状態による場合があります。
国内外リージョンや政府クラウドの対応状況を確認する
alerts_v2 と incidents の API は、Global、US Government L4、US Government L5 では利用可能とされていますが、China operated by 21Vianet は非対応とされています。多国籍企業や政府機関向けテナントを扱う場合は、利用可能なクラウド環境を移行計画に入れてください。(Microsoft Learn)
開発者が確認すべき移行ポイント
alerts_v2の一覧取得はフィルターとページングを前提にする
GET /security/alerts_v2 は、$count、$filter、$skip、$top をサポートします。フィルター対象として、assignedTo、classification、determination、createdDateTime、lastUpdateDateTime、severity、serviceSource、status が示されています。ページングには @odata.nextLink を使います。(Microsoft Learn)
GET /v1.0/security/alerts_v2?$filter=severity eq 'high' and status eq 'new'大量のアラートを定期取得する場合は、毎回全件取得しないでください。lastUpdateDateTime を使った差分取得、@odata.nextLink によるページング、取得失敗時の再実行設計を入れる必要があります。
インシデントは$expand=alertsで関連アラートを取得できる
インシデント一覧は GET /security/incidents で取得できます。OData クエリとして $count、$filter、$skip、$top、$expand がサポートされています。関連アラートを含めたい場合は $expand=alerts を使えます。(Microsoft Learn)
GET /v1.0/security/incidents?$filter=status eq 'active' and severity eq 'high'GET /v1.0/security/incidents?$expand=alerts運用上は、アラート単位でチケットを切るより、インシデント単位でチケット化するほうが重複を減らせます。同じ攻撃に関係する複数アラートを別々に処理すると、SOC の対応履歴が分断され、原因分析やクローズ判断が難しくなります。
アラート更新は更新可能なプロパティだけを送る
PATCH /security/alerts_v2/{alertId} では、リクエスト本文に更新したい値だけを指定します。更新可能なプロパティとして、status、classification、customDetails、determination、assignedTo が示されています。(Microsoft Learn)
PATCH /v1.0/security/alerts_v2/{alertId}
Content-Type: application/json
{
"assignedTo": "[email protected]",
"classification": "truePositive",
"determination": "malware",
"status": "inProgress"
}注意点は、アプリ側で「更新してよい項目」と「読み取り専用の調査情報」を明確に分けることです。たとえば、外部チケットシステムから戻ってきたステータスを Graph 側へ同期する場合、誤って分類や判定を上書きしないように、更新対象フィールドを固定してください。
Advanced Hunting API利用者の注意点
Advanced Hunting を使っている場合は、別の移行期限にも注意が必要です。Microsoft Graph の Advanced Hunting API は、旧エンドポイントである https://api.security.microsoft.com/api/advancedhunting/run と https://api.security.microsoft.com/api/advancedqueries/run を置き換える位置付けで、旧 API は 2027年2月1日にデータを返さなくなる予定です。(Microsoft Learn)
変更点はエンドポイントだけではありません。リソース URI、API 権限、リクエスト本文、レスポンス形式も変わります。Microsoft Learn の表では、新しい権限として ThreatHunting.Read.All、リクエスト本文として Query と Timespan、レスポンスとして huntingQueryResults が示されています。(Microsoft Learn)
| 項目 | 旧APIで見直す点 | Microsoft Graph側で確認する点 |
|---|---|---|
| エンドポイント | Defender系の旧URLを直接呼んでいないか | Graph の security/runHuntingQuery に変更する |
| 権限 | AdvancedQuery.Read.All や AdvancedHunting.Read.All 前提か | ThreatHunting.Read.All を使う |
| リクエスト本文 | Query だけで実行していないか | Query と Timespan の指定を確認する |
| レスポンス | Stats、Schema、Results を直接参照していないか | schema、results に合わせてパーサーを修正する |
Power Platform フローにも注意が必要です。Microsoft Graph には、以前 Microsoft Defender ATP 用 Power Platform コネクタで使えた Advanced Hunting アクションが組み込まれていないため、継続利用にはカスタム コネクタの作成が必要とされています。Power BI レポートでも、旧 API を使ったクエリは Microsoft Graph のパラメーターに合わせて更新する必要があります。(Microsoft Learn)
展開時に失敗しやすいポイント
エンドポイント変更だけで移行完了と判断する
/security/alerts から /security/alerts_v2 へURLを変えるだけでは不十分です。Microsoft の移行ドキュメントでは、新 API はレガシ API の一対一の置き換えではないとされています。特に、フィールド名、証拠データ、フィルター、インシデント中心の設計が変わります。(Microsoft Learn)
取得件数の差をすぐ不具合扱いする
v2 API では、Microsoft 365 Defender エコシステムに含まれないアラート、Defender ポータルに接続されていない Sentinel ワークスペースのアラート、スタンドアロン アラート、チューニングで抑制されたアラートなどが返らない場合があります。移行前後で件数比較をする場合は、API の対象範囲をそろえてください。(Microsoft Learn)
UTC時刻をJSTとして扱ってしまう
Microsoft Graph の日時フィールドは ISO 8601 形式の UTC として扱われることが多く、証拠リソースの createdDateTime や SAS トークンの expiryDateTime なども UTC で説明されています。日本向けのレポートやチケットに表示する場合は、JST 変換を表示層で行い、保存データは UTC のまま扱う設計が安全です。(Microsoft Learn)
読み取り権限と更新権限を分けていない
ダッシュボードや月次レポートだけなら、原則として読み取り権限で足ります。アラートやインシデントを更新する自動化だけに読み書き権限を与えることで、誤更新や過剰権限のリスクを抑えられます。
テスト環境でGraph Explorerだけ確認して本番差分を見ない
Graph Explorer でクエリが動いても、本番アプリのアプリケーション権限、管理者同意、条件付きアクセス、対象テナント、クラウド環境、レート制限、ページング処理が同じとは限りません。検証では、Graph Explorer、開発環境、本番相当のアプリ登録の3段階で確認するのが現実的です。
管理者・開発者向けの移行チェックリスト
| ステップ | 担当 | 確認内容 | 完了条件 |
|---|---|---|---|
| 既存API利用の棚卸し | 管理者・開発者 | /security/alerts、旧 Advanced Hunting API、Power BI、Power Automate、SIEM連携を洗い出す | 呼び出し元一覧が作成済み |
| 権限の見直し | 管理者 | SecurityAlert.*、SecurityIncident.*、ThreatHunting.Read.All の必要性を確認 | 最小権限で管理者同意済み |
| Sentinel接続確認 | セキュリティ管理者 | Defender ポータルへの接続状態を確認 | v2 APIで必要なアラートが取得できる |
| データモデル修正 | 開発者 | 旧フィールドを typed evidence に置き換える | JSON パーサーとDBスキーマが更新済み |
| フィルター修正 | 開発者 | serviceSource、evidence/any()、status、severity などに変更 | 主要検索条件が再現できる |
| レポート再検証 | SOC・情シス | 件数、重大度、分類、対応状況の差分を確認 | 旧レポートとの差分理由を説明できる |
| 段階展開 | 管理者・開発者 | 一部テナントまたは一部ワークフローで先行適用 | 問題なければ全体展開できる |
| 廃止前の停止計画 | 管理者 | 旧API呼び出しを止める日を決める | 旧エンドポイント依存が残っていない |
今すぐ取るべき行動
Microsoft Graph security API の今回のポイントは、セキュリティ運用をより統合的に扱える一方で、旧 API との互換性に頼った実装が危険になっていることです。
まず、既存環境で /security/alerts と旧 Advanced Hunting API を使っている箇所を洗い出してください。次に、alerts_v2 と incidents を使った取得・更新の検証を行い、権限、ロール、Sentinel 接続、typed evidence のパース処理を確認します。最後に、Power BI、SIEM、SOAR、チケットシステムなど下流のワークフローで、件数やフィールドの差分が業務上問題ないかを確認してください。
移行の判断基準は「APIが呼べるか」ではなく、「SOCが同じ、またはそれ以上の精度で調査・対応できるか」です。インシデント中心の設計に切り替え、証拠データを活用できる形に整えることで、Microsoft Graph security API は単なるデータ取得APIではなく、セキュリティ運用の自動化基盤として使いやすくなります。
コメント