장치에서 라이브 응답 명령 실행
적용 대상:
중요
일부 정보는 상용으로 출시되기 전에 실질적으로 수정될 수 있는 사전 릴리스된 제품과 관련이 있습니다. Microsoft는 여기에서 제공하는 정보와 관련하여 명시적이거나 묵시적인 어떠한 보증도 제공하지 않습니다.
엔드포인트용 Microsoft Defender를 경험하고 싶으신가요? 무료 평가판을 신청하세요.
참고
미국 정부 고객인 경우 미국 정부 고객용 끝점용 Microsoft Defender에나열된 URIS를 사용하시기 바랍니다.
팁
성능을 향상시키려면 서버를 지리적 위치에 더 가깝게 사용할 수 있습니다.
- api-us.securitycenter.microsoft.com
- api-eu.securitycenter.microsoft.com
- api-uk.securitycenter.microsoft.com
API 설명
디바이스에서 일련의 라이브 응답 명령 실행
제한 사항
이 API에 대한 속도 제한은 분당 10통입니다(추가 요청은 HTTP 429로 응답).
25개 세션을 동시 실행합니다(제한 제한을 초과하는 요청은 "429 - 요청 수가 너무 많음" 응답이 수신됩니다).
머신을 사용할 수 없는 경우 세션은 최대 3일 동안 대기됩니다.
RunScript 명령 시간 제한은 10분 후입니다.
라이브 응답 명령은 대기할 수 없습니다. 한 번만 실행할 수 있습니다.
이 API 호출을 실행하려는 컴퓨터는 자동화된 수정 수준이 할당되지 않은 RBAC 장치 그룹에 있는 경우 지정된 장치 그룹에 대해 최소 수정 수준을 사용하도록 설정해야 합니다.
단일 API 호출 시 여러 라이브 응답 명령을 실행할 수 있습니다. 그러나 라이브 응답 명령이 실패하면 이후의 모든 작업이 실행되지 않습니다.
최소 요구 사항
장치에서 세션을 시작하려면 먼저 다음 요구 사항을 충족해야 합니다.
지원되는 버전의 설치를 실행 중인지 Windows.
장치에서 다음 버전의 디바이스 중 하나를 실행해야 Windows
Windows 11
Windows 10
- 버전 1909 이상
- 버전 1903(KB4515384)
- KB4537818이 있는 버전 1809(RS 5)
- KB4537795가 있는 버전 1803(RS 4)
- KB4537816이 있는 버전 1709(RS 3)
Windows Server 2019 - 공개 미리 보기에만 해당
Windows Server 2022
사용 권한
이 API를 호출하려면 다음 권한 중 하나가 필요합니다. 사용 권한을 선택하는 방법을 포함하여 자세한 내용은 시작 을 참조합니다.
| 사용 권한 유형 | 사용 권한 | 사용 권한 표시 이름 |
|---|---|---|
| 응용 프로그램 | Machine.LiveResponse | 특정 컴퓨터의 실시간 응답 실행 |
| 위임(직장 또는 학교 계정) | Machine.LiveResponse | 특정 컴퓨터의 실시간 응답 실행 |
HTTP 요청
POST https://api.securitycenter.microsoft.com/API/machines/{machine_id}/runliveresponse
요청 헤더
| 이름 | 유형 | 설명 |
|---|---|---|
| 권한 부여 | String | Bearer<token>. 필수 특성입니다. |
| Content-Type | 문자열 | application/json. 필수 특성입니다. |
요청 본문
| 매개 변수 | 유형 | 설명 |
|---|---|---|
| Comment | String | 작업과 연결되는 설명입니다. |
| 명령 | 배열 | 실행할 명령입니다. 허용되는 값은 PutFile, RunScript, GetFile입니다. |
명령
| 명령 유형 | 매개 변수 | 설명 |
|---|---|---|
| PutFile | 키: FileName 값: <file name> |
라이브러리에서 장치로 파일을 넣습니다. 파일은 작업 폴더에 저장되고 장치가 기본적으로 다시 시작될 때 삭제됩니다. |
| RunScript | 키: ScriptName 값: <Script from library> 키: Args |
디바이스의 라이브러리에서 스크립트를 실행합니다. Args 매개 변수는 스크립트로 전달됩니다. 10분 후의 시간 제한입니다. |
| GetFile | 키: Path 값: <File path> |
장치에서 파일을 수집합니다. 참고: 경로의 백슬래시를 이스케이프해야 합니다. |
응답
성공하면 이 메서드는 201 Created를 반환합니다.
작업 엔터티. 지정한 ID가 있는 머신을 찾을 수 없는 경우 - 404 찾을 수 없습니다.
예제
요청 예제
다음은 요청의 예입니다.
POST https://api.securitycenter.microsoft.com/api/machines/1e5bc9d7e413ddd7902c2932e418702b84d0cc07/runliveresponse
```JSON
{
"Commands":[
{
"type":"RunScript",
"params":[
{
"key":"ScriptName",
"value":"minidump.ps1"
},
{
"key":"Args",
"value":"OfficeClickToRun"
}
]
},
{
"type":"GetFile",
"params":[
{
"key":"Path",
"value":"C:\\windows\\TEMP\\OfficeClickToRun.dmp.zip"
}
]
}
],
"Comment":"Testing Live Response API"
}
응답 예제
다음은 응답의 예입니다.
HTTP/1.1 200 Ok
콘텐츠 형식: application/json
{
"@odata.context": "https://api.securitycenter.microsoft.com/api/$metadata#MachineActions/$entity",
"id": "{machine_action_id}",
"type": "LiveResponse",
"requestor": "analyst@microsoft.com",
"requestorComment": "Testing Live Response API",
"status": "Pending",
"machineId": "{machine_id}",
"computerDnsName": "hostname",
"creationDateTimeUtc": "2021-02-04T15:36:52.7788848Z",
"lastUpdateDateTimeUtc": "2021-02-04T15:36:52.7788848Z",
"errorHResult": 0,
"commands": [
{
"index": 0,
"startTime": null,
"endTime": null,
"commandStatus": "Created",
"errors": [],
"command": {
"type": "RunScript",
"params": [
{
"key": "ScriptName",
"value": "minidump.ps1"
},{
"key": "Args",
"value": "OfficeClickToRun"
}
]
}
}, {
"index": 1,
"startTime": null,
"endTime": null,
"commandStatus": "Created",
"errors": [],
"command": {
"type": "GetFile",
"params": [{
"key": "Path", "value": "C:\\windows\\TEMP\\OfficeClickToRun.dmp.zip"
}
]
}
}
]
}