온-프레미스 관리 콘솔에 대한 경고 관리 API 참조
이 문서에는 Microsoft Defender for IoT 온-프레미스 관리 콘솔에 지원되는 경고 관리 REST API가 나와 있습니다.
이 API를 사용하여 온-프레미스 관리 콘솔에서 모든 또는 필터링된 경고를 검색합니다.
URI: /external/v1/alerts 또는 /external/v2/alerts
GET
쿼리 매개 변수:
| Name |
Description |
예제 |
필수/선택 |
|
상태 |
처리되거나 처리되지 않은 경고만 가져옵니다. 지원되는 값:
- handled
- unhandled
그 외의 값은 무시됩니다. |
/api/v1/alerts?state=handled |
옵션 |
|
fromTime |
Epoch 시간 및 UTC 표준 시간대에서 지정된 시간(밀리초)에 시작하여 만든 경고를 가져옵니다. |
/api/v1/alerts?fromTime=<epoch> |
옵션 |
|
toTime |
Epoch 시간 및 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
다음 필드가 있는 경고 목록입니다.
| Name |
유형 |
null 허용/null 허용 안 함 |
값 목록 |
|
ID |
숫자 |
null 허용 안 함 |
- |
|
sensorId |
숫자 |
null 허용 안 함 |
- |
|
zoneId |
숫자 |
null 허용 안 함 |
- |
|
time |
숫자 |
null 허용 안 함 |
Epoch 시간(UTC 표준 시간대)의 밀리초 |
|
title |
String |
null 허용 안 함 |
- |
|
message |
String |
null 허용 안 함 |
- |
|
severity |
String |
null 허용 안 함 |
Warning, Minor, Major 또는 Critical |
|
엔진 |
String |
null 허용 안 함 |
Protocol Violation, Policy Violation, Malware, Anomaly 또는 Operational |
|
sourceDevice |
숫자 |
Nullable |
디바이스 ID |
|
destinationDevice |
숫자 |
Nullable |
디바이스 ID |
|
remediationSteps |
String |
Nullable |
경고에 표시된 수정 단계 |
|
additionalInformation |
추가 정보 개체 |
Nullable |
- |
|
handled |
부울, 경고 상태 |
null 허용 안 함 |
true 또는 false |
추가 정보 필드:
| Name |
유형 |
null 허용/null 허용 안 함 |
값 목록 |
|
description |
String |
null 허용 안 함 |
- |
|
정보 |
JSON 배열 |
null 허용 안 함 |
String |
V2에 대해 추가됨:
| Name |
유형 |
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 기반 경고 관리)
이 API를 사용하여 Defender for IoT에서 검색한 특정 경고에 대해 지정된 작업을 수행합니다.
예를 들어 이 API를 사용하여 데이터를 QRadar에 전달하는 전달 규칙을 만들 수 있습니다. 자세한 내용은 Microsoft Defender for IoT와 Qradar 통합을 참조하세요.
URI: /external/v1/alerts/<UUID>
PUT
형식: JSON
쿼리 매개 변수:
| Name |
Description |
예제 |
필수/선택 |
|
UUID |
처리하거나 처리하고 학습하려는 경고에 대한 UUID(Universally Unique Identifier)를 정의합니다. |
/api/v1/alerts/7903F632-H7EJ-4N69-F40F-4B1E689G00Q0 |
필수 |
본문 매개 변수
| Name |
Description |
예제 |
필수/선택 |
|
action |
String |
handle 또는 handleAndLearn |
필수 |
요청 예제
{
"action": "handle"
}
형식: JSON
디바이스를 나타내는 JSON 개체의 배열입니다.
응답 필드:
| Name |
유형 |
필수/선택 |
Description |
|
내용/오류 |
String |
필수 |
요청에 성공하면 콘텐츠 속성이 나타납니다. 그렇지 않으면 오류 속성이 나타납니다. |
가능한 콘텐츠 값:
| 상태 코드 |
메시지 |
Description |
|
200 |
경고 업데이트 요청이 성공적으로 완료되었습니다. |
업데이트 요청이 성공적으로 완료되었습니다. 설명 없음. |
|
200 |
경고가 이미 처리되었습니다(처리). |
경고에 대한 핸들 요청을 받았을 때 경고가 이미 처리되었습니다.
경고는 처리된 상태로 유지됩니다. |
|
200 |
경고를 이미 핸들하고 학습했습니다(Handleandlearn). |
Handleandlearn 요청이 수신될 때 경고가 이미 핸들되고 학습되었습니다.
경고는 handledAndLearn 상태로 유지됩니다. |
|
200 |
경고가 이미 처리되었습니다(처리됨).
경고에 대해 핸들 및 학습(Handleandlearn)이 수행되었습니다. |
Handleandlearn 요청이 수신될 때 경고가 이미 핸들되고 학습되었습니다.
이 경고는 Handleandlearn될 수 있습니다. |
|
200 |
경고를 이미 핸들하고 학습했습니다(Handleandlearn). 핸들 요청이 무시되었습니다. |
경고 핸들에 대한 요청을 받았을 때 경고가 이미 Handleandlearn이었습니다. 이 경고는 Handleandlearn로 유지됩니다. |
|
500 |
잘못된 작업. |
전송된 작업은 경고에 대해 수행할 수 있는 유효한 작업이 아닙니다. |
|
500 |
예기치 않은 오류가 발생했습니다. |
예기치 않은 오류가 발생했습니다. 이 문제를 해결하려면 지원 팀에 문의하십시오. |
|
500 |
이 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(경고 제외 만들기)
경고가 전송되지 않는 유지 관리 기간을 관리합니다. 이 API를 사용하여 경고를 트리거할 때 제외해야 하는 중지 및 시작 시간, 디바이스 또는 서브넷을 정의하고 업데이트하거나 제외해야 하는 Defender for IoT 엔진을 정의하고 업데이트합니다.
예를 들어 유지 관리 기간 동안 중요한 디바이스에 대한 맬웨어 경고를 제외하고 모든 경고의 경고 제공을 중지할 수 있습니다.
maintenanceWindow API를 사용하여 정의하는 유지 관리 기간은 온-프레미스 관리 콘솔의 [경고 제외] 창에 Maintenance-{token name}-{ticket ID} 구문으로 명명된 읽기 전용 제외 규칙으로 표시됩니다.
중요
이 API는 유지 관리 목적으로만 제한된 기간 동안 지원되며, 경고 제외 규칙 대신 사용할 수 없습니다. 이 API는 일시적인 일회성 유지 관리 작업에만 사용합니다.
URI: /external/v1/maintenanceWindow
POST
새 유지 관리 기간을 만듭니다.
본문 매개 변수:
| Name |
Description |
예제 |
필수/선택 |
|
TicketId |
문자열입니다. 사용자 시스템의 유지 관리 티켓 ID를 정의합니다. 티켓 ID가 기존에 열려 있는 창에 연결되지 않았는지 확인합니다. |
2987345p98234 |
필수 |
|
ttl |
양의 정수입니다. 유지 관리 기간인 TTL(Time to Live)을 분 단위로 정의합니다. 정의된 기간이 완료되면 유지 관리 기간이 종료되고 시스템이 다시 정상적으로 작동합니다. |
180 |
필수 |
|
엔진 |
문자열의 JSON 배열입니다. 유지 관리 기간 동안 경고를 표시하지 않을 엔진을 정의합니다. 가능한 값은 다음과 같습니다.
- ANOMALY
- MALWARE
- OPERATIONAL
- POLICY_VIOLATION
- PROTOCOL_VIOLATION |
ANOMALY,OPERATIONAL |
옵션 |
|
sensorIds |
문자열의 JSON 배열입니다. 유지 관리 기간 동안 경고를 표시하지 않을 센서를 정의합니다. 이러한 센서 ID는 어플라이언스(OT 센서 어플라이언스 관리) API에서 가져올 수 있습니다. |
1,35,63 |
옵션 |
|
서브넷 |
문자열의 JSON 배열입니다. 유지 관리 기간 동안 경고를 표시하지 않을 서브넷을 정의합니다. 각 서브넷을 CIDR 표기법으로 정의합니다. |
192.168.0.0/16,138.136.80.0/14,112.138.10.0/8 |
옵션 |
| 상태 코드 |
메시지 |
Description |
|
201(만들어짐) |
- |
작업이 완료되었습니다. |
|
400(잘못된 요청) |
ticketId 없음 |
API 요청에 ticketId 값이 없습니다. |
|
400(잘못된 요청) |
잘못된 TTL |
API 요청에 양수가 아니거나 숫자가 아닌 TTL 값이 포함되었습니다. |
|
400(잘못된 요청) |
요청을 구문 분석할 수 없습니다. |
잘못된 매개 변수 또는 잘못된 값과 같은 본문 구문 분석 문제입니다. |
|
400(잘못된 요청) |
동일한 매개 변수가 있는 유지 관리 기간이 이미 있습니다. |
동일한 세부 정보가 있는 기존 유지 관리 기간이 이미 있는 경우 표시됩니다. |
|
404(찾을 수 없음) |
알 수 없는 센서 ID |
요청에 나열된 센서 중 하나가 없습니다. |
|
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
기존 유지 관리 기간을 닫습니다.
쿼리 매개 변수:
| Name |
Description |
예제 |
필수/선택 |
|
TicketId |
사용자 시스템의 유지 관리 티켓 ID를 정의합니다. 티켓 ID가 기존에 열려 있는 창에 연결되지 않았는지 확인합니다. |
2987345p98234 |
필수 |
오류 코드:
| 코드 |
메시지 |
Description |
|
200(OK) |
- |
작업이 완료되었습니다. |
|
400(잘못된 요청) |
ticketId 없음 |
요청에서 ticketId 매개 변수가 누락되었습니다. |
|
404(찾을 수 없음): |
유지 관리 기간을 찾을 수 없습니다. |
티켓 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를 사용하여 수행된 모든 open(POST), close(DELETE) 및 update(PUT) 작업의 로그를 검색합니다. T
쿼리 매개 변수:
| Name |
Description |
예제 |
필수/선택 |
|
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 |
옵션 |
오류 코드:
| 코드 |
메시지 |
Description |
|
200 |
정상 |
작업이 완료되었습니다. |
|
204: |
내용 없음 |
표시할 데이터가 없습니다. |
|
400 |
잘못된 요청 |
날짜 형식이 잘못되었습니다. |
|
500 |
내부 서버 오류 |
기타 예기치 않은 오류입니다. |
형식: JSON
유지 관리 기간 작업을 나타내는 JSON 개체의 배열입니다.
응답 구조:
| Name |
유형 |
null 허용/null 허용 안 함 |
값 목록 |
|
id |
정수(Long) |
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 |
|
엔진 |
문자열 배열 |
Nullable |
유지 관리 기간을 만드는 중에 제공되는 유지 관리 기간이 적용되는 엔진(Protocol Violation, Policy Violation, Malware, Anomaly 또는 Operational)입니다. |
|
sensorIds |
문자열 배열 |
Nullable |
유지 관리 기간을 만드는 중에 제공되는 유지 관리 기간이 적용되는 센서입니다. |
|
서브넷 |
문자열 배열 |
Nullable |
유지 관리 기간을 만드는 중에 제공되는 유지 관리 기간이 적용되는 서브넷입니다. |
|
ttl |
숫자 |
Nullable |
유지 관리 기간을 만들거나 업데이트하는 중에 제공되는 유지 관리 기간의 TTL(Time to Live)입니다. |
|
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분으로 업데이트하여 기간 수를 다시 설정합니다.
쿼리 매개 변수:
| Name |
Description |
예제 |
필수/선택 |
|
TicketId |
문자열입니다. 사용자 시스템의 유지 관리 티켓 ID를 정의합니다. |
2987345p98234 |
필수 |
|
ttl |
양의 정수입니다. 기간(분)을 정의합니다. |
210 |
필수 |
오류 코드:
| 코드 |
메시지 |
Description |
|
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
쿼리 매개 변수:
| Name |
Description |
예제 |
필수/선택 |
|
id |
온-프레미스 관리 콘솔의 경고 ID |
/external/v2/alerts/pcap/<id> |
필수 |
형식: JSON
작업 상태 세부 정보를 포함하는 메시지 문자열:
| 상태 코드 |
메시지 |
Description |
|
200(OK) |
- |
요청된 PCAP 파일에 대한 데이터가 있는 JSON 개체입니다. 자세한 내용은 데이터 필드를 참조하세요. |
|
500(내부 서버 오류) |
경고를 찾을 수 없음 |
온-프레미스 관리 콘솔에서 제공된 경고 ID를 찾을 수 없습니다. |
|
500(내부 서버 오류) |
<number> xsense ID에 대한 토큰을 가져오는 동안 오류 발생 |
지정된 센서 ID에 대한 센서의 토큰을 가져오는 동안 오류가 발생했습니다. |
|
500(내부 서버 오류) |
- |
기타 예기치 않은 오류입니다. |
데이터 필드
| Name |
유형 |
null 허용/null 허용 안 함 |
값 목록 |
|
id |
숫자 |
null 허용 안 함 |
온-프레미스 관리 콘솔 경고 ID |
|
xsenseId |
숫자 |
null 허용 안 함 |
센서 ID |
|
xsenseAlertId |
숫자 |
null 허용 안 함 |
센서 콘솔 경고 ID |
|
downloadUrl |
String |
null 허용 안 함 |
PCAP 파일을 다운로드하는 데 사용되는 URL |
|
토큰 |
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 참조 개요를 참조하세요.