디바이스에서 라이브 응답 명령 실행

  • 아티클

적용 대상:

중요

이 게시물의 일부 정보는 상용으로 출시되기 전에 실질적으로 수정될 수 있는 사전 릴리스된 제품과 관련이 있습니다. Microsoft는 여기에서 제공되는 정보와 관련하여 명시적이거나 묵시적인 어떠한 보증도 하지 않습니다.

엔드포인트용 Microsoft Defender를 경험하고 싶으신가요? 무료 평가판을 신청하세요.

참고

미국 정부 고객인 경우 미국 정부 고객을 위해 엔드포인트용 Microsoft Defender 나열된 URI를 사용하세요.

팁

성능을 향상시키려면 서버를 지리적 위치에 더 가깝게 사용할 수 있습니다.

  • api-us.securitycenter.microsoft.com
  • api-eu.securitycenter.microsoft.com
  • api-uk.securitycenter.microsoft.com
  • api-au.securitycenter.microsoft.com

API 설명

디바이스에서 라이브 응답 명령 시퀀스 실행

제한 사항

  1. 이 API의 속도 제한은 분당 10개 호출입니다(추가 요청은 HTTP 429로 응답됨).

  2. 동시에 실행되는 세션 25개(제한 제한을 초과하는 요청은 "429 - 너무 많은 요청" 응답을 받습니다).

  3. 컴퓨터를 사용할 수 없는 경우 세션은 최대 3일 동안 대기됩니다.

  4. RunScript 명령 시간 제한은 10분 후입니다.

  5. 라이브 응답 명령은 큐에 대기할 수 없으며 한 번에 하나씩만 실행할 수 있습니다.

  6. 이 API 호출을 실행하려는 컴퓨터가 자동화된 수정 수준이 할당되지 않은 RBAC 디바이스 그룹에 있는 경우 지정된 디바이스 그룹에 대해 최소 수정 수준을 사용하도록 설정해야 합니다.

    참고

    디바이스 그룹 만들기는 엔드포인트용 Defender 플랜 1 및 플랜 2에서 지원됩니다.

  7. 단일 API 호출에서 여러 라이브 응답 명령을 실행할 수 있습니다. 그러나 라이브 응답 명령이 실패하면 모든 후속 작업이 실행되지 않습니다.

  8. 동일한 컴퓨터에서 여러 라이브 응답 세션을 실행할 수 없습니다(라이브 응답 작업이 이미 실행 중인 경우 후속 요청은 HTTP 400 - ActiveRequestAlreadyExists로 응답됨).

참고

디바이스 페이지에서 시작된 라이브 응답 작업은 machineactions API에서 사용할 수 없습니다.

최소 요구 사항

디바이스에서 세션을 시작하기 전에 다음 요구 사항을 충족하는지 확인합니다.

권한

이 API를 호출하려면 다음 권한 중 하나가 필요합니다. 사용 권한을 선택하는 방법을 포함하여 자세한 내용은 시작을 참조하세요.

사용 권한 유형 사용 권한 사용 권한 표시 이름
응용 프로그램 Machine.LiveResponse 특정 컴퓨터에서 라이브 응답 실행
위임됨(회사 또는 학교 계정) Machine.LiveResponse 특정 컴퓨터에서 라이브 응답 실행

HTTP 요청

POST https://api.securitycenter.microsoft.com/API/machines/{machine_id}/runliveresponse

요청 헤더

이름 유형 설명
권한 부여 String 전달자<토큰>입니다. 필수 특성입니다.
Content-Type 문자열 application/json. 필수 특성입니다.

요청 본문

매개 변수 형식 설명
Comment String 작업과 연결할 주석입니다.
명령 배열 실행할 명령입니다. 허용되는 값은 PutFile, RunScript, GetFile입니다(반복에 대한 제한 없이 이 순서에 있어야 합니다).

명령

명령 유형 매개 변수 설명
PutFile 키: FileName

값: <파일 이름>

 라이브러리에서 디바이스로 파일을 넣습니다. 파일은 작업 폴더에 저장되며 디바이스가 기본적으로 다시 시작될 때 삭제됩니다. 참고: 응답 결과가 없습니다.
RunScript 키: ScriptName
값: <라이브러리의 스크립트>

키: 인수
값: <스크립트 인수>

 디바이스의 라이브러리에서 스크립트를 실행합니다.

Args 매개 변수가 스크립트에 전달됩니다.

10분 후의 시간 제한.
GetFile 키: 경로
값: <파일 경로>		 디바이스에서 파일을 수집합니다. 참고: 경로의 백슬라이쉬는 이스케이프해야 합니다.

응답

  • 성공하면 이 메서드는 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"
}

응답 예제

다음은 응답의 예입니다.

각 명령 상태 가능한 값은 "Created", "Completed" 및 "Failed"입니다.

HTTP/1.1 200 Ok

Content-type: 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"
                    }
                ]
            }
        }
    ]
}

팁

더 자세히 알아보고 싶으신가요? 기술 커뮤니티: 엔드포인트용 Microsoft Defender Tech Community의 Microsoft 보안 커뮤니티와 Engage.