オンプレミス管理コンソールのアラート管理 API リファレンス
[アーティクル] 04/11/2023
3 人の共同作成者
フィードバック
この記事の内容
この記事では、Microsoft Defender for IoT オンプレミス管理コンソールでサポートされているアラート管理 REST API の一覧を示します。
オンプレミスの管理コンソールからすべてまたはフィルター処理されたアラートを取得するには、この API を使用します。
URI : /external/v1/alerts または /external/v2/alerts
GET
クエリ パラメーター :
名前
説明
例
必須/省略可能
状態
処理されたか処理されなかったアラートのみを取得します。 サポートされる値:handledunhandled
/api/v1/alerts?state=handledオプション
fromTime
指定した時刻 (エポック時間からのミリ秒数、UTC タイムゾーン) 以降に作成されたアラートを取得します。
/api/v1/alerts?fromTime=<epoch>オプション
toTime
指定した時刻 (エポック時間からのミリ秒数、UTC タイムゾーン) 以前に作成されたアラートのみを取得します。
/api/v1/alerts?toTime=<epoch>オプション
siteId
アラートが検出されたサイト。
/api/v1/alerts?siteId=1オプション
zoneId
アラートが検出されたゾーン。
/api/v1/alerts?zoneId=1オプション
sensorId
アラートが検出されたセンサー。
/api/v1/alerts?sensorId=1省略可能
型 : JSON
次のフィールドを含むアラートの一覧。
名前
Type
Null 許容 / Null 非許容
［値の一覧］
Id
数値
NULL 値は許可されません
-
sensorId
数値
NULL 値は許可されません
-
zoneId
数値
NULL 値は許可されません
-
time
数値
NULL 値は許可されません
エポック時間 からのミリ秒数 (UTC タイムゾーン)
title
String
NULL 値は許可されません
-
message
String
NULL 値は許可されません
-
severity
String
NULL 値は許可されません
Warning、Minor、Major、または Critical
engine
String
NULL 値は許可されません
Protocol Violation、Policy Violation、Malware、Anomaly、または Operational
sourceDevice
数値
Nullable
デバイス ID
destinationDevice
数値
Nullable
デバイス ID
remediationSteps
String
Nullable
アラートに表示される修復手順
additionalInformation
追加情報オブジェクト
Nullable
-
handled
ブール値、アラートの状態
NULL 値は許可されません
true または false
追加情報フィールド :
名前
Type
Null 許容 / Null 非許容
［値の一覧］
description
String
NULL 値は許可されません
-
information
JSON 配列
NULL 値は許可されません
String
V2 に追加されたもの :
名前
Type
Null 許容 / Null 非許容
［値の一覧］
sourceDeviceAddress
String
Nullable
IP または MAC アドレス
destinationDeviceAddress
String
Nullable
IP または MAC アドレス
remediationSteps
JSON 配列
NULL 値は許可されません
文字列。アラートで説明されている修復手順
sensorName
String
NULL 値は許可されません
ユーザーが定義したセンサーの名前
zoneName
String
NULL 値は許可されません
センサーに関連付けられているゾーンの名前
SiteName
String
NULL 値は許可されません
センサーに関連付けられているサイトの名前
詳しくは、「Sensor API バージョン リファレンス 」をご覧ください。
応答の例
[
{
"engine": "Operational",
"handled": false,
"title": "Traffic Detected on sensor Interface",
"additionalInformation": null,
"sourceDevice": 0,
"zoneId": 1,
"siteId": 1,
"time": 1594808245000,
"sensorId": 1,
"message": "The sensor resumed detecting network traffic on ens224.",
"destinationDevice": 0,
"id": 1,
"severity": "Warning"
},
{
"engine": "Anomaly",
"handled": false,
"title": "Address Scan Detected",
"additionalInformation": null,
"sourceDevice": 4,
"zoneId": 1,
"siteId": 1,
"time": 1594808260000,
"sensorId": 1,
"message": "Address scan detected.\nScanning address: 10.10.10.22\nScanned subnet: 10.11.0.0/16\nScanned addresses: 10.11.1.1, 10.11.20.1, 10.11.20.10, 10.11.20.100, 10.11.20.2, 10.11.20.3, 10.11.20.4, 10.11.20.5, 10.11.20.6, 10.11.20.7...\nIt is recommended to notify the security officer of the incident.",
"destinationDevice": 0,
"id": 2,
"severity": "Critical"
},
{
"engine": "Operational",
"handled": false,
"title": "Suspicion of Unresponsive MODBUS Device",
"additionalInformation": null,
"sourceDevice": 194,
"zoneId": 1,
"siteId": 1,
"time": 1594808285000,
"sensorId": 1,
"message": "Outstation device 10.13.10.1 (Protocol Address 53) seems to be unresponsive to MODBUS requests.",
"destinationDevice": 0,
"id": 3,
"severity": "Minor"
}
]
型 : GET
API :
curl -k -H "Authorization: <AUTH_TOKEN>" 'https://<>IP_ADDRESS>/external/v1/alerts?state=&zoneId=&fromTime=&toTime=&siteId=&sensor='
例 :
curl -k -H "Authorization: 1234b734a9244d54ab8d40aedddcabcd" 'https://127.0.0.1/external/v1/alerts?state=unhandled&zoneId=1&fromTime=0&toTime=1594551777000&siteId=1&sensor=1'
UUID (UUID に基づいてアラートを管理する)
Defender for IoT によって検出された特定のアラートに対して指定したアクションを実行するには、この API を使います。
たとえば、この API を使って、データを QRadar に転送する転送規則を作成できます。 詳しくは、「Qradar を Microsoft Defender for IoT と統合する 」をご覧ください。
URI : /external/v1/alerts/<UUID>
PUT
型 : JSON
クエリ パラメーター :
名前
説明
例
必須/省略可能
UUID
処理する、または処理して学習するアラートのユニバーサル一意識別子 (UUID) を定義します。
/api/v1/alerts/7903F632-H7EJ-4N69-F40F-4B1E689G00Q0必須
本文のパラメーター
名前
説明
例
必須/省略可能
action
String
handle または handleAndLearn のいずれか
必須
要求の例
{
"action": "handle"
}
型 : JSON
デバイスを表す JSON オブジェクトの配列。
応答のフィールド :
名前
Type
必須/省略可能
説明
content / error
String
必須
要求が成功すると、content プロパティが表示されます。 それ以外の場合は、error プロパティが表示されます。
可能性のある content の値 :
status code
Message
説明
200
Alert update request finished successfully. (アラートの更新要求が正常に完了しました。)
更新要求が正常に完了しました。 コメントはありません。
200
Alert was already handled (handle ). (アラートは既に処理されています (handle )。)
このアラートは、アラートの処理要求を受信した時には既に処理されていました。handled のままになります。
200
Alert was already handled and learned. (handleAndLearn ) (アラートは既に処理および学習されています (handleAndLearn )。)
このアラートは、handleAndLearn への要求を受信したときにはすでに処理され、学習されていました。handledAndLearn 状態のままになります。
200
Alert was already handled. (handled ) (アラートはすでに処理されています (handled )。)handleAndLearn ) was performed on the alert. (アラートに対して処理と学習 (handleAndLearn ) が実行されました。)
このアラートは、handleAndLearn への要求を受信したときにはすでに処理されていました。handleAndLearn になります。
200
Alert was already handled and learned. (handleAndLearn ) (アラートは既に処理および学習されています (handleAndLearn )。) Ignored handle request. (ハンドル要求は無視されました。)
このアラートは、アラートを処理する要求を受信したときにはすでに handleAndLearn でした。 このアラートは handleAndLearn のままになります。
500
Invalid action. (無効なアクション。)
送信されたアクションは、アラートで実行する有効なアクションではありません。
500
Unexpected error occurred. (予期しないエラーが発生しました。)
予期しないエラーが発生しました。 この問題を解決するには、テクニカル サポートにお問い合わせください。
500
Couldn't execute request because no alert was found for this UUID. (この UUID のアラートが見つからなかったため、要求を実行できませんでした。)
指定されたアラート UUID がシステムで見つかりませんでした。
応答の例: 成功
{
"content": "Alert update request finished successfully"
}
応答の例: 失敗
{
"error": "Invalid action"
}
型 : PUT
API :
curl -k -X PUT -d '{"action": "<ACTION>"}' -H "Authorization: <AUTH_TOKEN>" https://<IP_ADDRESS>/external/v1/alerts/<UUID>
例 :
curl -k -X PUT -d '{"action": "handle"}' -H "Authorization: 1234b734a9244d54ab8d40aedddcabcd" https://127.0.0.1/external/v1/alerts/1-1594550943000
maintenanceWindow (アラートの除外を作成する)
アラートが送信されないメンテナンス期間を管理します。 アラートをトリガーするときに除外する停止時刻と開始時刻、デバイス、またはサブネットを定義および更新するには、または除外する必要がある Defender for IoT エンジンを定義および更新するには、この API を使います。
例としては、メンテナンス期間中は、重要なデバイスのマルウェア アラートを除き、すべてのアラートの配信を停止するなどです。
maintenanceWindow API で定義したメンテナンス期間は、Maintenance-{token name}-{ticket ID} という形式の名前が付けられた読み取り専用の除外ルールとして、オンプレミス管理コンソールの [Alert Exclusions] (アラートの除外) ウィンドウに表示されます。
重要
この API は、メンテナンス目的でのみ、限られた期間についてサポートされており、アラート除外ルール の代わりに使うことを意図したものではありません。 この API は、1 回限りの一時的なメンテナンス操作にのみ使ってください。
URI : /external/v1/maintenanceWindow
POST
新しいメンテナンス期間を作成します。
本文のパラメーター :
名前
説明
例
必須/省略可能
ticketId
文字列 をオンにします。 ユーザーのシステムのメンテナンス チケット ID を定義します。 チケット ID が既存のオープン期間にリンクされていないことを確認します。
2987345p98234必須
ttl
正の整数。 TTL (有効期限) を定義します。これは、分単位のメンテナンス期間です。 定義した期間が完了すると、メンテナンス期間は終了し、システムは再び通常の動作になります。
180必須
engines
文字列の JSON 配列。 メンテナンス期間中にアラートを抑制するエンジンを定義します。 指定できる値ANOMALYMALWAREOPERATIONALPOLICY_VIOLATIONPROTOCOL_VIOLATION
ANOMALY,OPERATIONALオプション
sensorIds
文字列の JSON 配列。 メンテナンス期間中にアラートを抑制するセンサーを定義します。 これらのセンサー ID は、appliances (OT センサー アプライアンスを管理する) API から取得できます。
1,35,63オプション
サブネット
文字列の JSON 配列。 メンテナンス期間中にアラートを抑制するサブネットを定義します。 各サブネットを CIDR 表記で定義します。
192.168.0.0/16,138.136.80.0/14,112.138.10.0/8オプション
status code
Message
説明
201 (作成されました)
-
アクションは正常に完了しました。
400 (無効な要求)
TicketId がありません
API 要求に ticketId の値がありませんでした。
400 (無効な要求)
無効な TTL
API 要求に、正以外または数値以外の TTL 値が含まれていました。
400 (無効な要求)
要求を解析できませんでした。
正しくないパラメーターや無効な値など、本文の解析に関する問題。
400 (無効な要求)
同じパラメーターのメンテナンス期間が既に存在します。
同じ詳細を持つメンテナンス期間が既に存在する場合に発生します。
404 (見つかりません)
不明なセンサー ID
要求の一覧に含まれるセンサーの 1 つが存在しません。
409 (競合)
チケット ID には既に開いているウィンドウがあります。
チケット ID は、別のオープン メンテナンス期間にリンクされています。
500 (内部サーバー エラー)
-
その他の予期しないエラー。
型 : POST
API :
curl -k -X POST -d '{"ticketId": "<TICKET_ID>",ttl": <TIME_TO_LIVE>,"engines": [<ENGINE1, ENGINE2...ENGINEn>],"sensorIds": [<SENSOR_ID1, SENSOR_ID2...SENSOR_IDn>],"subnets": [<SUBNET1, SUBNET2....SUBNETn>]}' -H "Authorization: <AUTH_TOKEN>" https://<IP address>/external/v1/maintenanceWindow
例 :
curl -k -X POST -d '{"ticketId": "a5fe99c-d914-4bda-9332-307384fe40bf","ttl": "20","engines": ["ANOMALY"],"sensorIds": ["5","3"],"subnets": ["10.0.0.0/16"]}' -H "Authorization: 1234b734a9244d54ab8d40aedddcabcd" https://127.0.0.1/external/v1/maintenanceWindow
DELETE
既存のメンテナンス期間を閉じます。
クエリ パラメーター :
名前
説明
例
必須/省略可能
ticketId
ユーザーのシステムのメンテナンス チケット ID を定義します。 チケット ID が既存のオープン期間にリンクされていることを確認します。
2987345p98234必須
エラー コード :
コード
Message
説明
200 (OK)
-
アクションは正常に完了しました。
400 (無効な要求)
TicketId がありません
ticketId パラメーターが要求に含まれていません。
404 (Not Found) :
メンテナンス期間が見つかりません。
チケット ID は、オープン メンテナンス期間にリンクされていません。
500 (内部サーバー エラー)
-
その他の予期しないエラー。
型 : DELETE
API :
curl -k -X DELETE -d '{"ticketId": "<TICKET_ID>"}' -H "Authorization: <AUTH_TOKEN>" https://<IP address>/external/v1/maintenanceWindow
例 :
curl -k -X DELETE -d '{"ticketId": "a5fe99c-d914-4bda-9332-307384fe40bf"}' -H "Authorization: 1234b734a9244d54ab8d40aedddcabcd" https://127.0.0.1/external/v1/maintenanceWindow
GET
メンテナンス期間を処理するためにこの API を使って実行されたすべての オープン (POST )、クローズ (DELETE )、更新 (PUT ) アクションのログを取得します。 T
クエリ パラメーター :
名前
説明
例
必須/省略可能
fromDate
定義済みの日付以降のログをフィルター処理します。 形式は YYYY-MM-DD です。
2022-08-10省略可能
toDate
定義されている日付までのログをフィルター処理します。 形式は YYYY-MM-DD です。
2022-08-10オプション
ticketId
特定のチケット ID に関連するログをフィルター処理します。
9a5fe99c-d914-4bda-9332-307384fe40bfオプション
tokenName
特定のトークン名に関連するログをフィルター処理します。
quarterly-sanity-window
オプション
エラー コード :
コード
Message
説明
200
OK
アクションは正常に完了しました。
204 :
コンテンツなし
表示するデータがありません。
400
正しくない要求
日付の形式が正しくありません。
500
内部サーバー エラー
その他の予期しないエラー。
型 : JSON
メンテナンス期間の操作を表す JSON オブジェクトの配列。
応答の構造 :
名前
Type
Null 許容 / Null 非許容
［値の一覧］
id
Long integer
NULL 値は許可されません
現在のログの内部 ID
dateTime
String
NULL 値は許可されません
アクティビティが発生した時刻 (例: 2022-04-23T18:25:43.511Z )
ticketId
String
NULL 値は許可されません
メンテナンス期間 ID。 例: 9a5fe99c-d914-4bda-9332-307384fe40bf
tokenName
String
NULL 値は許可されません
メンテナンス期間のトークン名。 例: quarterly-sanity-window
engines
文字列の配列
Nullable
メンテナンス期間の作成時に指定された、メンテナンス期間が適用されるエンジン: Protocol Violation、Policy Violation、Malware、Anomaly、または Operational
sensorIds
文字列の配列
Nullable
メンテナンス期間の作成時に指定された、メンテナンス期間が適用されるセンサー。
サブネット
文字列の配列
Nullable
メンテナンス期間の作成時に指定された、メンテナンス期間が適用されるサブネット。
ttl
数値
Nullable
メンテナンス期間の作成時または更新時に指定された、メンテナンス期間の有効期限 (TTL)。
operationType
String
NULL 値は許可されません
次の値のいずれか: OPEN、UPDATE、CLOSE
型 : GET
API :
curl -k -H "Authorization: <AUTH_TOKEN>" 'https://<IP_ADDRESS>/external/v1/maintenanceWindow?fromDate=&toDate=&ticketId=&tokenName='
例 :
curl -k -H "Authorization: 1234b734a9244d54ab8d40aedddcabcd" 'https://127.0.0.1/external/v1/maintenanceWindow?fromDate=2020-01-01&toDate=2020-07-14&ticketId=a5fe99c-d914-4bda-9332-307384fe40bf&tokenName=a'
PUT
ttl パラメーターを変更することにより、メンテナンス プロセスを開始した後でメンテナンス期間の持続時間を更新できます。 新しい持続時間の定義は、以前の定義を上書きします。
このメソッドは、現在構成されている期間よりも長い期間を設定する場合に便利です。 たとえば、元の定義が 180 分で、90 分が経過したときに、さらに 30 分追加する場合は、ttl を 120 に更新して持続時間をリセットします。
クエリ パラメーター :
名前
説明
例
必須/省略可能
ticketId
文字列 をオンにします。 ユーザーのシステムのメンテナンス チケット ID を定義します。
2987345p98234必須
ttl
正の整数。 期間を分単位で定義します。
210必須
エラー コード :
コード
Message
説明
200 (OK)
-
アクションは正常に完了しました。
400 (無効な要求)
TicketId がありません
要求に ticketId の値がありません。
400 (無効な要求)
無効な TTL
定義されている TTL が、数値または正の整数ではありません。
400 (無効な要求)
要求を解析できませんでした
要求に ttl パラメーターの値がありません。
404 (見つかりません)
メンテナンス期間が見つかりません
チケット ID は、オープン メンテナンス期間にリンクされていません。
500 (内部サーバー エラー)
-
その他の予期しないエラー。
型 : PUT
API :
curl -k -X PUT -d '{"ticketId": "<TICKET_ID>",ttl": "<TIME_TO_LIVE>"}' -H "Authorization: <AUTH_TOKEN>" https://<IP address>/external/v1/maintenanceWindow
例 :
curl -k -X PUT -d '{"ticketId": "a5fe99c-d914-4bda-9332-307384fe40bf","ttl": "20"}' -H "Authorization: 1234b734a9244d54ab8d40aedddcabcd" https://127.0.0.1/external/v1/maintenanceWindow
pcap (アラートの PCAP を要求する)
この API を使用して、アラートに関連する PCAP ファイルを要求します
URI : /external/v2/alerts/
GET
クエリ パラメーター :
名前
説明
例
必須/省略可能
id
オンプレミスの管理コンソールからのアラート ID
/external/v2/alerts/pcap/<id>必須
型 : JSON
動作状態の詳細を含むメッセージ文字列:
status code
Message
説明
200 (OK)
-
要求された PCAP ファイルに関するデータを含む JSON オブジェクト。 詳しくは、「データ フィールド 」をご覧ください。
500 (内部サーバー エラー)
警告が見つからない
指定されたアラート ID が、オンプレミスの管理コンソールに見つかりませんでした。
500 (内部サーバー エラー)
xsense ID <number> に対するトークンの取得中にエラーが発生しました
指定されたセンサー ID に対するセンサーのトークンを取得するときにエラーが発生しました
500 (内部サーバー エラー)
-
その他の予期しないエラー。
データ フィールド
名前
Type
Null 許容 / Null 非許容
［値の一覧］
id
数値
NULL 値は許可されません
オンプレミスの管理コンソールのアラート ID
xsenseId
数値
NULL 値は許可されません
センサー ID
xsenseAlertId
数値
NULL 値は許可されません
センサー コンソールのアラート ID
downloadUrl
String
NULL 値は許可されません
PCAP ファイルのダウンロードに使われる URL
token
String
NULL 値は許可されません
PCAP ファイルをダウンロードするときに使われるセンサーのトークン
応答の例: 成功
{
"downloadUrl": "https://10.1.0.2/api/v2/alerts/pcap/1",
"xsenseId": 1,
"token": "d2791f58-2a88-34fd-ae5c-2651fe30a63c",
"id": 1,
"xsenseAlertId": 1
}
応答の例: エラー
{
"error": "alert not found"
}
型 : GET
API
curl -k -H "Authorization: <AUTH_TOKEN>" 'https://<IP_ADDRESS>/external/v2/alerts/pcap/<ID>'
*
例 :
curl -k -H "Authorization: 1234b734a9244d54ab8d40aedddcabcd" 'https://10.1.0.1/external/v2/alerts/pcap/1'
次のステップ
詳細については、Defender for IoT API リファレンスの概要 に関するページを参照してください。