Run live response commands on a device

Applies to:

Important

Some information relates to prereleased product which may be substantially modified before it's commercially released. Microsoft makes no warranties, express or implied, with respect to the information provided here.

Want to experience Microsoft Defender for Endpoint? Sign up for a free trial.

Note

If you are a US Government customer, please use the URIs listed in Microsoft Defender for Endpoint for US Government customers.

Tip

For better performance, you can use server closer to your geo location:

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

API description

Runs a sequence of live response commands on a device

Limitations

  1. Rate limitations for this API are 10 calls per minute (additional requests are responded with HTTP 429).

  2. 25 concurrently running sessions (requests exceeding the throttling limit will receive a "429 - Too many requests" response).

  3. If the machine is not available, the session will be queued for up to 3 days.

  4. RunScript command timeouts after 10 minutes.

  5. When a live response command fails all followed actions will not be executed.

Permissions

One of the following permissions is required to call this API. To learn more, including how to choose permissions, see Get started.

Permission type Permission Permission display name
Application Machine.LiveResponse Run live response on a specific machine
Delegated (work or school account) Machine.LiveResponse Run live response on a specific machine

HTTP request

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

Request headers

Name Type Description
Authorization String Bearer<token>. Required.
Content-Type string application/json. Required.

Request body

Parameter Type Description
Comment String Comment to associate with the action.
Commands Array Commands to run. Allowed values are PutFile, RunScript, GetFile.

Commands:

Command Type Parameters Description
PutFile Key: FileName

Value: <file name>
Puts a file from the library to the device. Files are saved in a working folder and are deleted when the device restarts by default.
RunScript Key: ScriptName
Value: <Script from library>

Key: Args
Value: <Script arguments>
Runs a script from the library on a device.

The Args parameter is passed to your script.

Timeouts after 10 minutes.
GetFile Key: Path
Value: <File path>
Collect file from a device. NOTE: Backslashes in path must be escaped.

Response

  • If successful, this method returns 200, Ok. Action entity. If machine with the specified ID was not found - 404 Not Found.

Example

Request

Here is an example of the request.


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"
}

Response

Here is an example of the response.

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"
                    }
                ]
            }
        }
    ]
}