Edit

Share via

Run live response commands on a device

  • Applies to: Microsoft Defender for Endpoint Plan 1 and Plan 2

Important

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

Prerequisites

Before you can initiate a session on a device, make sure you fulfill the following requirements:

Supported operating systems

API description

Runs a sequence of live response commands on a device

Limitations

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

  • 50 concurrently running sessions (requests exceeding the throttling limit receives a "429 - Too many requests" response).

  • If the machine isn't available, the session is queued for up to 2 hours.

  • RunScript command time-outs after 10 minutes.

  • Live response commands can't be queued up and can only be executed one at a time.

  • If the machine that you're trying to run this API call is in an RBAC device group that doesn't have an automated remediation level assigned to it, you need to at least enable the minimum Remediation Level for a given Device Group.

  • Multiple live response commands can be run on a single API call. However, when a live response command fails all the subsequent actions won't be executed.

  • Multiple live response sessions can't be executed on the same machine (if live response action is already running, subsequent requests are responded to with HTTP 400 - ActiveRequestAlreadyExists).

  • Live response actions initiated from the Device page aren't available in the machineactions API.

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.security.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 (must be in this order with no limit on repetitions).

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. NOTE: Doesn't have a response result.
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.
Time-outs 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 201 Created.

  • Action entity. If machine with the specified ID wasn't found, you see 404 Not Found.

Example

Request example

Here's an example of the request.

POST https://api.security.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 example

Here's an example of the response.

Possible values for each command status are "Created", "Completed", and "Failed".

HTTP/1.1 200 Ok

Content-type: application/json

{
    "@odata.context": "https://api.security.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"
                    }
                ]
            }
        }
    ]
}
  • Last updated on