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
Rate limitations for this API are 10 calls per minute (additional requests are responded with HTTP 429).
25 concurrently running sessions (requests exceeding the throttling limit will receive a "429 - Too many requests" response).
If the machine is not available, the session will be queued for up to 3 days.
RunScript command timeouts after 10 minutes.
Live response commands cannot be queued up and can only be executed one at a time.
If the machine that you are trying to run this API call is in an RBAC device group that does not have an automated remediation level assigned to it, you'll need to at least enable the minimum Remediation Level for a given Device Group.
Note
Device group creation is supported in Defender for Endpoint Plan 1 and Plan 2.
Multiple live response commands can be run on a single API call. However, when a live response command fails all the subsequent actions will not be executed.
Minimum Requirements
Before you can initiate a session on a device, make sure you fulfill the following requirements:
Verify that you're running a supported version of Windows.
Devices must be running one of the following versions of Windows
Windows 11
Windows 10
- Version 1909 or later
- Version 1903 with KB4515384
- Version 1809 (RS 5) with with KB4537818
- Version 1803 (RS 4) with KB4537795
- Version 1709 (RS 3) with KB4537816
Windows Server 2019 - Only applicable for Public preview
Windows Server 2022
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 |
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 201 Created.
Action entity. If machine with the specified ID was not found - 404 Not Found.
Example
Request example
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 example
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"
}
]
}
}
]
}
Related topics
Feedback
Submit and view feedback for