アラート API を作成する

[アーティクル]
07/04/2024

適用対象:

Microsoft Defender ATP を試してみたいですか? 無料試用版にサインアップしてください。

注:

米国政府機関のお客様は、 Microsoft Defender for Endpoint for US Government のお客様に記載されている URI を使用してください。

ヒント

パフォーマンスを向上させるために、地理的な場所に近いサーバーを使用できます。

us.api.security.microsoft.com
eu.api.security.microsoft.com
uk.api.security.microsoft.com
au.api.security.microsoft.com
swa.api.security.microsoft.com
ina.api.security.microsoft.com

API の説明

イベントの上に新しいアラートを作成 します。

アラートの作成には、Microsoft Defender for Endpoint イベント が必要です。
要求の Event から、イベント時間、 マシン ID、 レポート ID の 3 つのパラメーターを指定する必要があります。次の例を参照してください。
Advanced Hunting API またはポータルで見つかったイベントを使用できます。
同じデバイスに同じタイトルの開いているアラートが存在する場合は、新しく作成されたアラートがそれにマージされます。
API を介して作成されたアラートに対して、自動調査が自動的に開始されます。

制限事項

この API のレート制限は、1 分あたり 15 回の呼び出しです。

アクセス許可

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

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

注:

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

ユーザーは、少なくとも次のロールのアクセス許可を持っている必要があります: アラートの調査。詳細については、「ロールの作成と管理」を参照してください。
ユーザーは、デバイスグループの設定に基づいて、アラートに関連付けられているデバイスにアクセスできる必要があります。詳細については、「デバイスグループの作成と管理」を参照してください。

デバイスグループの作成は、Defender for Endpoint Plan 1 とプラン 2 の両方でサポートされています

HTTP 要求

POST https://api.securitycenter.microsoft.com/api/alerts/CreateAlertByReference

要求ヘッダー

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

要求本文

要求本文で、次の値を指定します (すべて必須)。

プロパティ	型	説明
eventTime	DateTime(UTC)	高度なハンティングから取得した文字列としてのイベントの正確な時刻。たとえば、 `2018-08-03T16:45:21.7115183Z`Required です。
reportId	String	高度なハンティングから取得したイベントの reportId。必須。
MachineId	String	イベントが識別されたデバイスの ID。必須。
severity	String	アラートの重大度。プロパティの値は、'Low'、'Medium'、および 'High' です。必須。
title	String	アラートのタイトル。必須。
説明	String	アラートの説明。必須。
recommendedAction	String	セキュリティ責任者は、アラートを分析するときにこのアクションを実行する必要があります。必須。
category	String	アラートのカテゴリ。プロパティの値は、"General"、"CommandAndControl"、"Collection"、"CredentialAccess"、"DefenseEvasion"、"Discovery"、"Exfiltration"、"Exploit"、"Execution"、"InitialAccess"、"LateralMovement"、"Malware"、"Persistence"、"PrivilegeEscalation"、"ランサムウェア"、"SuspiciousActivity" 必須です。

応答

成功した場合、このメソッドは 200 OK を返し、応答本文に新しいアラートオブジェクトを返します。指定したプロパティ (reportId、 eventTime 、 machineId) を持つイベントが見つからなかった場合 - 404 Not Found。

例

要求

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

POST https://api.securitycenter.microsoft.com/api/alerts/CreateAlertByReference

{
    "machineId": "1e5bc9d7e413ddd7902c2932e418702b84d0cc07",
    "severity": "Low",
    "title": "example",
    "description": "example alert",
    "recommendedAction": "nothing",
    "eventTime": "2018-08-03T16:45:21.7115183Z",
    "reportId": "20776",
    "category": "Exploit"
}

ヒント

さらに多くの情報を得るには、 Tech Community 内の Microsoft Security コミュニティ (Microsoft Defender for Endpoint Tech Community) にご参加ください。

次の方法で共有