インシデント API の更新

  • 適用対象: Microsoft Defender XDR

注:

MS Graph セキュリティ API を使用して、新しい API をお試しください。 詳細情報: Microsoft Graph セキュリティ API を使用する - Microsoft Graph |Microsoft Learn。 MS Graph セキュリティ API を使用した新しい 更新インシデント API の詳細については、「 インシデントの更新」を参照してください。

重要

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

API の説明

既存のインシデントのプロパティをUpdatesします。 更新可能なプロパティは、 status、 determination、 classification、 assignedTo、 tags、および commentsです。

クォータ、リソースの割り当て、およびその他の制約

  1. 調整のしきい値に達する前に、1 分あたり最大 50 呼び出しまたは 1 時間あたり 1,500 呼び出しを行うことができます。
  2. determination プロパティは、classificationが TruePositive に設定されている場合にのみ設定できます。

要求が調整されると、 429 応答コードが返されます。 応答本文は、新しい呼び出しを開始できる時刻を示します。

アクセス許可

この API を呼び出すには、次のいずれかのアクセス許可が必要です。 アクセス許可の選択方法など、詳細については、Microsoft Defender API へのアクセスに関するページを参照してください。

アクセス許可の種類 アクセス許可 アクセス許可の表示名
アプリケーション Incident.ReadWrite.All すべてのインシデントの読み取りと書き込み
委任 (職場または学校のアカウント) Incident.ReadWrite インシデントの読み取りと書き込み

注:

ユーザー資格情報を使用してトークンを取得する場合、ユーザーはポータルでインシデントを更新するためのアクセス許可を持っている必要があります。

HTTP 要求

PATCH /api/incidents/{id}

要求ヘッダー

名前 タイプ 説明
Authorization String ベアラー {token}。 必須。
Content-Type String application/json. 必須。

要求本文

要求本文で、更新する必要があるフィールドの値を指定します。 要求本文に含まれていない既存のプロパティは、関連する値の変更のために再計算する必要がない限り、値を保持します。 最適なパフォーマンスを得るには、変更されなかった既存の値を省略する必要があります。

プロパティ タイプ 説明
状態 列挙 インシデントの現在の状態を指定します。 可能な値は、Active、Resolved、InProgress、および Redirected です。
assignedTo 文字列 インシデントの所有者。
classification 列挙 インシデントの仕様。 使用可能な値は、 TruePositive (True 陽性)、 InformationalExpectedActivity (情報、期待されるアクティビティ)、および FalsePositive (False Positive) です。
決定 列挙 インシデントの決定を指定します。

分類ごとに考えられる決定値は次のとおりです。

  • 真陽性: MultiStagedAttack (多段階攻撃)、 MaliciousUserActivity (悪意のあるユーザー アクティビティ)、 CompromisedAccount (侵害されたアカウント) - それに応じて、パブリック API の列挙型名、 Malware (マルウェア)、 Phishing (フィッシング)、 UnwantedSoftware (不要なソフトウェア)、 Other (その他) を変更することを検討してください。
  • 情報提供、期待されるアクティビティ:SecurityTesting (セキュリティ テスト)、 LineOfBusinessApplication (基幹業務アプリケーション)、 ConfirmedActivity (確認されたアクティビティ) - それに応じてパブリック API の列挙型名を変更し、 Other (その他) を検討してください。
  • 誤検知:Clean (悪意がない) - パブリック API の列挙型名を適宜変更し、 NoEnoughDataToValidate (検証するのに十分なデータがありません)、 Other (その他) を変更することを検討してください。
    		•
    tags 文字列リスト インシデント タグの一覧。
    コメント 文字列 インシデントに追加するコメント。

    注:

    2022 年 8 月 29 日ごろ、以前にサポートされていたアラート判定値 ('Apt' と 'SecurityPersonnel') は非推奨となり、API を介して使用できなくなります。

    応答

    成功した場合、このメソッドは 200 OKを返します。 応答本文には、更新されたプロパティを持つインシデント エンティティが含まれています。 指定した ID を持つインシデントが見つからなかった場合、メソッドは 404 Not Foundを返します。

    例

    要求の例

    要求の例を次に示します。

     PATCH https://api.security.microsoft.com/api/incidents/{id}

    要求データの例

    {
    "status": "Resolved",
    "assignedTo": "secop2@contoso.com",
    "classification": "TruePositive",
    "determination": "Malware",
    "tags": ["Yossi's playground", "Don't mess with the Zohan"],
    "comment": "pen testing"
}

    ヒント

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

    • Last updated on