高度なハンティング API のMicrosoft Defender XDR

2025-04-18
適用対象: Microsoft Defender XDR

警告

この高度なハンティング API は、機能が制限された古いバージョンです。高度なハンティング API のより包括的なバージョンは、 Microsoft Graph セキュリティ API で既に利用できます。 「Microsoft Graph セキュリティ API を使用した高度なハンティング」を参照してください

重要

一部の情報は、市販される前に大幅に変更される可能性があるプレリリース製品に関するものです。 Microsoft は、ここに記載された情報に関して、明示または黙示を問わず、いかなる保証も行いません。

高度なハンティングは、特別に構築されたクエリを使用して、Microsoft Defender XDRの過去 30 日間のイベントデータを調べる脅威ハンティングツールです。高度なハンティングクエリを使用して、異常なアクティビティの検査、考えられる脅威の検出、攻撃への対応を行うことができます。高度なハンティング API を使用すると、プログラムによってイベントデータを照会できます。

クォータとリソース割り当て

次の条件は、すべてのクエリに関連します。

クエリは、過去 30 日間のデータを探索して返します。
結果は最大 100,000 行を返すことができます。
テナントごとに 1 分あたり最大 45 回の呼び出しを行うことができます。呼び出しの数は、そのサイズに基づいてテナントごとに異なります。
各テナントには、テナントサイズに基づいて CPU リソースが割り当てられます。次の 15 分のサイクルの後まで、テナントが割り当てられたリソースの 100% に達した場合、クエリはブロックされます。過剰消費によるブロックされたクエリを回避するには、「 CPU クォータに達しないようにクエリを最適化する」のガイダンスに従います。
1 つの要求が 3 分を超えて実行されると、タイムアウトになり、エラーが返されます。
429 HTTP 応答コードは、割り当てられた CPU リソースに到達したことを示します。送信された要求の数、または割り当てられた実行時間のいずれかです。応答本文を読んで、到達した制限を理解します。

アクセス許可

高度なハンティング API を呼び出すには、次のいずれかのアクセス許可が必要です。アクセス許可の選択方法など、詳細については、「Microsoft Defender XDR Protection API にアクセスする」を参照してください。

アクセス許可の種類	アクセス許可	アクセス許可の表示名
アプリケーション	AdvancedHunting.Read.All	高度なクエリを実行する
委任 (職場または学校のアカウント)	AdvancedHunting.Read	高度なクエリを実行する

注:

ユーザー資格情報を使用してトークンを取得する場合:

ユーザーは "データの表示" ロールを持っている必要があります。
ユーザーは、デバイスグループの設定に基づいて、デバイスにアクセスできる必要があります。

HTTP 要求

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

要求ヘッダー

ヘッダー	値
Authorization	ベアラー {token} 注: 必須
Content-Type	application/json

要求本文

要求本文で、JSON オブジェクトに次のパラメーターを指定します。

パラメーター	型	説明
クエリ	テキスト	実行するクエリ。 (必須)

応答

成功した場合、このメソッドは応答本文に 200 OKと QueryResponse オブジェクトを返します。

応答オブジェクトには、次の 3 つの最上位のプロパティが含まれています。

Stats - クエリパフォーマンス統計のディクショナリ。
スキーマ - 応答のスキーマ。各列の Name-Type ペアの一覧。
結果 - 高度なハンティングイベントの一覧。

例

次の例では、ユーザーが以下のクエリを送信し、 Stats、 Schema、 Resultsを含む API 応答オブジェクトを受け取ります。

クエリ

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

Response オブジェクト

{
    "Stats": {
        "ExecutionTime": 4.621215,
        "resource_usage": {
            "cache": {
                "memory": {
                    "hits": 773461,
                    "misses": 4481,
                    "total": 777942
                },
                "disk": {
                    "hits": 994,
                    "misses": 197,
                    "total": 1191
                }
            },
            "cpu": {
                "user": "00:00:19.0468750",
                "kernel": "00:00:00.0156250",
                "total cpu": "00:00:19.0625000"
            },
            "memory": {
                "peak_per_node": 236822432
            }
        },
        "dataset_statistics": [
            {
                "table_row_count": 2,
                "table_size": 102
            }
        ]
    },
    "Schema": [
        {
            "Name": "Timestamp",
            "Type": "DateTime"
        },
        {
            "Name": "FileName",
            "Type": "String"
        },
        {
            "Name": "InitiatingProcessFileName",
            "Type": "String"
        }
    ],
    "Results": [
        {
            "Timestamp": "2020-08-30T06:38:35.7664356Z",
            "FileName": "conhost.exe",
            "InitiatingProcessFileName": "powershell.exe"
        },
        {
            "Timestamp": "2020-08-30T06:38:30.5163363Z",
            "FileName": "conhost.exe",
            "InitiatingProcessFileName": "powershell.exe"
        }
    ]
}

ヒント

さらに多くの情報を得るには、 Tech Community 内の Microsoft Security コミュニティにご参加ください: 「Microsoft Defender XDR Tech Community」。

次の方法で共有