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

  • [アーティクル]

適用対象:

  • Microsoft Defender XDR

警告

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

重要

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

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

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

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

  1. クエリは、過去 30 日間のデータを探索して返します。
  2. 結果は最大 100,000 行を返すことができます。
  3. テナントごとに 1 分あたり最大 45 回の呼び出しを行うことができます。 呼び出しの数は、そのサイズに基づいてテナントごとに異なります。
  4. 各テナントには、テナント サイズに基づいて CPU リソースが割り当てられます。 次の 15 分のサイクルの後まで、テナントが割り当てられたリソースの 100% に達した場合、クエリはブロックされます。 過剰消費によるブロックされたクエリを回避するには、「 CPU クォータに達しないようにクエリを最適化する」のガイダンスに従います。
  5. 1 つの要求が 3 分を超えて実行されると、タイムアウトになり、エラーが返されます。
  6. 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 オブジェクトに次のパラメーターを指定します。

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

応答

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

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

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

例

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

クエリ

{
    "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 Defender XDR Tech Community の Microsoft Security コミュニティとEngageします。