インシデント API の更新
適用対象:
注:
MS Graph セキュリティ API を使用して、新しい API をお試しください。 詳細情報: Microsoft Graph セキュリティ API を使用する - Microsoft Graph |Microsoft Learn。 MS Graph セキュリティ API を使用した新しい 更新インシデント API の詳細については、「 インシデントの更新」を参照してください。
重要
一部の情報は、市販される前に大幅に変更される可能性があるプレリリース製品に関するものです。 Microsoft は、ここに記載された情報に関して、明示または黙示を問わず、いかなる保証も行いません。
API の説明
既存のインシデントのプロパティを更新します。 更新可能なプロパティは、 status、 determination、 classification、 assignedTo、 tags、および commentsです。
クォータ、リソースの割り当て、およびその他の制約
- 調整のしきい値に達する前に、1 分あたり最大 50 呼び出しまたは 1 時間あたり 1,500 呼び出しを行うことができます。
-
determinationプロパティは、classificationが TruePositive に設定されている場合にのみ設定できます。
要求が調整されると、 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 (True 陽性)、 InformationalExpectedActivity (情報、期待されるアクティビティ)、および FalsePositive (False Positive) です。 |
| 決定 | 列挙 | インシデントの決定を指定します。 分類ごとに考えられる決定値は次のとおりです。 MultiStagedAttack (多段階攻撃)、 MaliciousUserActivity (悪意のあるユーザー アクティビティ)、 CompromisedAccount (侵害されたアカウント) - それに応じて、パブリック API の列挙型名、 Malware (マルウェア)、 Phishing (フィッシング)、 UnwantedSoftware (不要なソフトウェア)、 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"],
"comment": "pen testing"
}
関連記事
ヒント
さらに多くの情報を得るには、 Tech Community: Microsoft Defender XDR Tech Community で Microsoft セキュリティ コミュニティに参加します。