온-프레미스 관리 콘솔에 대한 경고 관리 API 참조

이 문서에서는 Microsoft Defender for IoT 온-프레미스 관리 콘솔에 대해 지원되는 경고 관리 REST API를 나열합니다.

경고(경고 정보 검색)

이 API를 사용하여 온-프레미스 관리 콘솔에서 모든 경고 또는 필터링된 경고를 검색합니다.

URI: /external/v1/alerts 또는 /external/v2/alerts

가져오기

요청

쿼리 매개 변수:

이름	묘사	본보기	필수/선택 사항
상태	처리되거나 처리되지 않은 경고만 가져옵니다. 지원되는 값: - 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	선택적

메모

사이트 및 영역 ID가 없을 수 있습니다. 이 경우 먼저 모든 디바이스를 쿼리하여 사이트 및 영역 ID를 검색합니다. 자세한 내용은 온-프레미스 관리 콘솔(공개 미리 보기)대한 Integration API 참조를 참조하세요.

응답

형식: JSON

다음 필드가 있는 경고 목록입니다.

이름	형	Nullable/ nullable이 아님	값 목록
ID	숫자	nullable이 아님	-
sensorId	숫자	nullable이 아님	-
zoneId	숫자	nullable이 아님	-
시간	숫자	nullable이 아님	Epoch 시간(UTC 표준 시간대)의 밀리초
제목	문자열	nullable이 아님	-
메시지	문자열	nullable이 아님	-
심각도	문자열	nullable이 아님	Warning, Minor, Major또는 Critical
엔진	문자열	nullable이 아님	Protocol Violation, Policy Violation, Malware, Anomaly또는 Operational
sourceDevice	숫자	Nullable	디바이스 ID
destinationDevice	숫자	Nullable	디바이스 ID
remediationSteps	문자열	Nullable	경고에 표시된 수정 단계
추가 정보	추가 정보 개체	Nullable	-
처리된	부울, 경고의 상태	nullable이 아님	true 또는 false

추가 정보 필드:

이름	형	Nullable/ nullable이 아님	값 목록
설명	문자열	nullable이 아님	-
정보	JSON 배열	nullable이 아님	문자열

V2대해 추가된 :

이름	형	Nullable/ nullable이 아님	값 목록
sourceDeviceAddress	문자열	Nullable	IP 또는 MAC 주소
destinationDeviceAddress	문자열	Nullable	IP 또는 MAC 주소
remediationSteps	JSON 배열	nullable이 아님	경고에 설명된 문자열, 수정 단계
sensorName	문자열	nullable이 아님	사용자가 정의한 센서의 이름
zoneName	문자열	nullable이 아님	센서와 연결된 영역의 이름
siteName	문자열	nullable이 아님	센서와 연결된 사이트의 이름

자세한 내용은 센서 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 IoTQradar 통합을 참조하세요.

URI: /external/v1/alerts/<UUID>

놓다

요청

형식: JSON

쿼리 매개 변수:

이름	묘사	본보기	필수/선택 사항
UUID	처리하거나 처리하고 학습하려는 경고에 대한 UUID(범용 고유 식별자)를 정의합니다.	/api/v1/alerts/7903F632-H7EJ-4N69-F40F-4B1E689G00Q0	필수

본문 매개 변수

이름	묘사	본보기	필수/선택 사항
작업	문자열	handle 또는 handleAndLearn	필수

요청 예제

{
    "action": "handle"
}

응답

형식: JSON

디바이스를 나타내는 JSON 개체의 배열입니다.

응답 필드:

이름	형	필수/선택 사항	묘사
콘텐츠/오류	문자열	필수	요청이 성공하면 콘텐츠 속성이 나타납니다. 그렇지 않으면 오류 속성이 나타납니다.

가능한 콘텐츠 값:

상태 코드	메시지	묘사
200	경고 업데이트 요청이 성공적으로 완료되었습니다.	업데이트 요청이 성공적으로 완료되었습니다. 메모가 없습니다.
200	경고가 이미 처리되었습니다(핸들).	경고에 대한 핸들 요청이 수신되었을 때 경고가 이미 처리되었습니다. 경고는 처리된남아 있습니다.
200	경고가 이미 처리되고 학습되었습니다(handleAndLearn).	경고는 handleAndLearn 수신되었을 때 이미 처리되고 학습되었습니다. 경고는 처리된AndLearn 상태로 유지됩니다.
200	경고가 이미 처리되었습니다(처리됨). 경고에서 처리 및 학습(handleAndLearn)이 수행되었습니다.	경고는 handleAndLearn 대한 요청이 수신되었을 때 이미 처리되었습니다. 경고가 처리되고AndLearn.
200	경고가 이미 처리되고 학습되었습니다(handleAndLearn). 무시된 핸들 요청입니다.	경고 처리 요청이 수신되었을 때 경고가 이미 처리되지 . 경고는AndLearn유지됩니다.
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

올리기

새 유지 관리 기간을 만듭니다.

요청

본문 매개 변수:

이름	묘사	본보기	필수/선택 사항
ticketId	문자열. 사용자 시스템에서 유지 관리 티켓 ID를 정의합니다. 티켓 ID가 기존 열린 창에 연결되지 않았는지 확인합니다.	2987345p98234	필수
ttl	양의 정수입니다. 유지 관리 기간의 기간(분)인 TTL(TTL(TTL-TTL)을 정의합니다. 정의된 기간이 완료되면 유지 관리 기간이 종료되고 시스템이 정상적으로 다시 작동합니다.	180	필수
엔진	문자열의 JSON 배열입니다. 유지 관리 기간 동안 경고를 표시하지 않을 엔진을 정의합니다. 가능한 값: - ANOMALY - MALWARE - OPERATIONAL - POLICY_VIOLATION - PROTOCOL_VIOLATION	ANOMALY,OPERATIONAL	선택적
sensorIds	문자열의 JSON 배열입니다. 유지 관리 기간 동안 경고를 표시하지 않을 센서를 정의합니다. 어플라이언스(OT 센서 어플라이언스 관리) API에서 이러한 센서 ID를 가져올 수 있습니다.	1,35,63	선택적
서브넷	문자열의 JSON 배열입니다. 유지 관리 기간 동안 경고를 표시하지 않도록 서브넷을 정의합니다. CIDR 표기법에서 각 서브넷을 정의합니다.	192.168.0.0/16,138.136.80.0/14,112.138.10.0/8	선택적

응답

상태 코드	메시지	묘사
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

삭제하다

기존 유지 관리 기간을 닫습니다.

요청

쿼리 매개 변수:

이름	묘사	본보기	필수/선택 사항
ticketId	사용자 시스템에서 유지 관리 티켓 ID를 정의합니다. 티켓 ID가 기존 열린 창에 연결되어 있는지 확인합니다.	2987345p98234	필수

응답

오류 코드:

코드	메시지	묘사
200(확인)	-	작업이 성공적으로 완료되었습니다.
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

가져오기

유지 관리 기간을 처리하기 위해 이 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	특정 토큰 이름과 관련된 로그를 필터링합니다.	분기별 정신 창	선택적

오류 코드:

코드	메시지	묘사
200	그래	작업이 성공적으로 완료되었습니다.
204:	콘텐츠 없음	표시할 데이터가 없습니다.
400	잘못된 요청	날짜 형식이 잘못되었습니다.
500	내부 서버 오류	다른 예기치 않은 오류입니다.

응답

형식: JSON

유지 관리 기간 작업을 나타내는 JSON 개체의 배열입니다.

응답 구조:

이름	형	Nullable/ nullable이 아님	값 목록
ID	정수(Long)	nullable이 아님	현재 로그의 내부 ID
dateTime	문자열	nullable이 아님	활동이 발생한 시간(예: 2022-04-23T18:25:43.511Z
ticketId	문자열	nullable이 아님	유지 관리 기간 ID입니다. 예: 9a5fe99c-d914-4bda-9332-307384fe40bf
tokenName	문자열	nullable이 아님	유지 관리 기간 토큰 이름입니다. 예: quarterly-sanity-window
엔진	문자열 배열	Nullable	유지 관리 기간을 만드는 동안 제공된 대로 유지 관리 기간이 적용되는 엔진: Protocol Violation, Policy Violation, Malware, Anomaly또는 Operational
sensorIds	문자열 배열	Nullable	유지 관리 기간을 만드는 동안 제공된 대로 유지 관리 기간이 적용되는 센서입니다.
서브넷	문자열 배열	Nullable	유지 관리 기간을 만드는 동안 제공된 대로 유지 관리 기간이 적용되는 서브넷입니다.
ttl	숫자	Nullable	유지 관리 기간을 만들거나 업데이트하는 동안 제공된 유지 관리 기간의 TTL(Time to Live)입니다.
operationType	문자열	nullable이 아님	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'

놓다

ttl 매개 변수를 변경하여 유지 관리 프로세스를 시작한 후 유지 관리 기간을 업데이트할 수 있습니다. 새 기간 정의는 이전 기간을 재정의합니다.

이 메서드는 현재 구성된 기간보다 더 긴 기간을 설정하려는 경우에 유용합니다. 예를 들어 원래 180분을 정의한 경우 90분이 지났고 30분을 더 추가하려면 ttl120 분으로 업데이트하여 기간 수를 다시 설정합니다.

요청

쿼리 매개 변수:

이름	묘사	본보기	필수/선택 사항
ticketId	문자열. 사용자 시스템에서 유지 관리 티켓 ID를 정의합니다.	2987345p98234	필수
ttl	양의 정수입니다. 기간(분)을 정의합니다.	210	필수

응답

오류 코드:

코드	메시지	묘사
200(확인)	-	작업이 성공적으로 완료되었습니다.
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/

가져오기

요청

쿼리 매개 변수:

이름	묘사	본보기	필수/선택 사항
ID	온-프레미스 관리 콘솔의 경고 ID	/external/v2/alerts/pcap/<id>	필수

응답

형식: JSON

작업 상태 세부 정보가 포함된 메시지 문자열:

상태 코드	메시지	묘사
200(확인)	-	요청된 PCAP 파일에 대한 데이터가 있는 JSON 개체입니다. 자세한 내용은 데이터 필드참조하세요.
500(내부 서버 오류)	경고를 찾을 수 없음	온-프레미스 관리 콘솔에서 제공된 경고 ID를 찾을 수 없습니다.
500(내부 서버 오류)	xsense ID <number> 대한 토큰을 가져오는 동안 오류가 발생했습니다.	지정된 센서 ID에 대한 센서 토큰을 가져올 때 오류가 발생했습니다.
500(내부 서버 오류)	-	다른 예기치 않은 오류입니다.

데이터 필드

이름	형	Nullable/ nullable이 아님	값 목록
ID	숫자	nullable이 아님	온-프레미스 관리 콘솔 경고 ID
xsenseId	숫자	nullable이 아님	센서 ID
xsenseAlertId	숫자	nullable이 아님	센서 콘솔 경고 ID
downloadUrl	문자열	nullable이 아님	PCAP 파일을 다운로드하는 데 사용되는 URL
토큰	문자열	nullable이 아님	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 참조 개요참조하세요.