Announcing live response API public preview

This post has been republished via RSS; it originally appeared at: New blog articles in Microsoft Tech Community.

As part of our ongoing effort to provide a rich set of APIs to allow customers and partners to benefit from the power of the Microsoft Defender for Endpoint platform, we are happy to announce the public preview of the live response API.

live response API request examplelive response API request example

Time plays a critical role when collecting forensic evidence. Due to frequent changes that occur in the memory and storage of a device, it's critical to collect forensic evidence swiftly. Forensic evidence must be gathered as soon as suspicious activity is identified on a device.

 

The live response APIs allow you to collect information and take real-time actions on a remote endpoint using APIs. These actions include the ability to upload and download files and execute scripts on the endpoint.

The live response APIs are currently supported on Windows 10 and Windows Server 2019, support for other platforms is coming very soon.

In fact, the new functionality inevitably includes a number of new APIs that join the Microsoft Defender for Endpoint scheme. These include:

In addition to the APIs listed above, we highly recommend to use the existing Get Machine Action API and List Machine Action API.

Check out the tutorial below where you’ll be guided on how to use the live response API to export and collect artifacts from a compromised device.

 

How to use the live response API

In this tutorial we will show you how to use the live response API to collect forensic evidence, that indicates the current state of the device such as running processes, scheduled tasks etc. You can later set the script to run automatically when a specific alert is raised, so you can investigate threats and respond in real time. 

 

Step 1 – Create/download a script that collects any artifact that may interest you. For basic usage, you can use the sample script below.

 

 

<# .Synopsis Sample script to export all Scheduled Tasks #> Get-ScheduledTask | Get-ScheduledTaskInfo | Export-csv "C:\Windows\Temp\ScheduledTasks.csv" -NoTypeInformation -Force Get-Service | Export-csv "C:\Windows\Temp\Services.csv" -NoTypeInformation -Force Get-Process | Export-csv "C:\Windows\Temp\Processes.csv" -NoTypeInformation -Force

 

 

 

Step 2 – Upload the script to the Live response library.

Before you can run a script, you must first upload it to the library. If you plan to use an unsigned script in the session, you'll need to enable the setting in the Advanced Features settings.

 

israelcp_0-1626089865211.png

 

Step 3 – Run a new live response session.

We will initiate a session and execute commands: RunScript for taking a memory dump of a process and GetFile to collect the dump file. Please note that the process name or ID must be passed to the script.

Request:

Type: HTTP POST

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

 

 

 

{ "Commands":[ { "type":"RunScript", "params":[ { "key":"ScriptName", "value":"foo.ps1" }, ] }, { "type":"GetFile", "params":[ { "key":"Path", "value":"C:\\windows\\Temp\\Services.csv" } ] }, { "type":"GetFile", "params":[ { "key":"Path", "value":"C:\\windows\\Temp\\Processes.csv" } ] }, { "type":"GetFile", "params":[ { "key":"Path", "value":"C:\\windows\\Temp\\ScheduledTasks.csv" } ] } ], "Comment":"Testing Live Response API" }

 

 

 

You will then get a response with the ID of the session (machine action) that was just created. With this ID you can track the status of the session, cancel it, and collect its outputs.

 

Step 4 – Check the session status.

Once you have initiated the session, you can check its progress and the status of executed commands using the following request:

Request:

Type: HTTP GET

https://api.securitycenter.microsoft.com/api/machines/machineactions/{machine_action_id}

 

Step 5 – Get script transcript.

If a command has ended successfully, the response will include a link to the script output (for RunScript) or collected file (for GetFile). The link will expire within 30 minutes.

Request:

Type: HTTP GET

https://api.securitycenter.microsoft.com/api/machines/machineactions/{machine_action_id}/GetLiveResponseResultDownloadLink(index=0)

 

Response:

 

 

{ "@odata.context": "https://api.securitycenter.microsoft.com/api/$metadata#Edm.String", "value": "https://core.windows.net/investigation-actions-data/ID/CustomPlaybookCommandOutput/4ed5e7807ad1fe59b00b664fe06a0f07?se=2021-02-04T16%3A13%3A50Z&sp=r&sv=2019-07-07&sr=b&sig=1dYGe9rPvUlXBPvYSmr6/OLXPY98m8qWqfIQCBbyZTY%3D" }

 

 

 

File content:

 

 

{ "script_name": "foo.ps1", "exit_code": 0, "script_output": "Transcript started, output file is C:\\ProgramData\\Microsoft\\Windows Defender Advanced Threat Protection\\Temp\\PSScriptOutputs\\PSScript_Transcript_{TRANSCRIPT_ID}.txt \u0000\u0000\u0000", "script_error":”” }

 

 

 

Step 6 – Download the collected files.

Generate a download-link for each of the collected files, and then download them to your local machine. The link will expire within 30 minutes.

 

Request:

Type: HTTP GET

https://api.securitycenter.microsoft.com/api/machines/machineactions/{machine_action_id}/GetLiveResponseResultDownloadLink(index=1)

 

Response:

 

 

{ "@odata.context": "https://api.securitycenter.microsoft.com/api/$metadata#Edm.String", "value":"https://core.windows.net/f10/41/sha256/cf1041e3e2a4c2d36c72bcc53b1fcf7d7c65a175e6385110d4659de38c80dd79?sv=2015-12-11&sr=b&sig=BXM9Q1ZAAZ9Is1PqzmErbNihk6xPt8csOvuFqsMkDaI%3D&spr=https&st=2021-02-04T15%3A44%3A53Z&se=2021-02-04T17%3A31%3A35Z&sp=r&rscd=attachment%3B%20filename%3D%22ScheduledTasks.csv.zip" }

 

 

 

 

Summary

We’re excited to hear your feedback as you explore the new APIs and we will continue to update the documentation throughout the preview. Our mission is to provide you a generic platform that allows you to develop a customized IR solution on top of it. Additional new capabilities are expected to be released soon, such as managing the live response library via API, and support for macOS and Linux.

If you’ve enabled public preview features, you can check out the new live response APIs today! If not, we encourage you to turn on preview features for Microsoft Defender for Endpoint to get access to the newest capabilities. These features can be turned on in the Microsoft Defender Security Center or the Microsoft 365 security center.

 

 

 

 

Microsoft Defender for Endpoint is an industry-leading, cloud-powered endpoint security solution offering vulnerability management, endpoint protection, endpoint detection and response, and mobile threat defense in a single unified platform. With our solution, threats are no match. If you are not yet taking advantage of Microsoft’s unrivaled threat optics and proven capabilities, sign up for a free trial of Microsoft Defender for Endpoint today. 

Leave a Reply

Your email address will not be published. Required fields are marked *

*

This site uses Akismet to reduce spam. Learn how your comment data is processed.