インシデント API の更新

  • [アーティクル]

適用対象:

注:

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

重要

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

API の説明

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

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

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

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

アクセス許可

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

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

注:

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

HTTP 要求

PATCH /api/incidents/{id}

要求ヘッダー

名前 型 説明
Authorization String ベアラー {token}。 必須。
Content-Type 文字列 application/json. 必須。

要求本文

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

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

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

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

    注:

    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"],
    "comments": [
          {
              "comment": "pen testing",
              "createdBy": "secop2@contoso.com",
              "createdTime": "2021-05-02T09:34:21.5519738Z"
          },
          {
              "comment": "valid incident",
              "createdBy": "secop2@contoso.comt",
              "createdTime": "2021-05-02T09:36:27.6652581Z"
          }
      ]
}

    ヒント

    さらに多くの情報を得るには、 Tech Community: Microsoft Defender XDR Tech Community の Microsoft Security コミュニティとEngageします。