Document toolboxDocument toolbox

Microsoft Defender for Endpoint

Microsoft Defender for Endpoint is a platform designed to help enterprise networks prevent, detect, investigate, and respond to advanced threats.

Connect Microsoft Defender for Endpoint with Devo SOAR

  1. Navigate to Automations > Integrations.

  2. Search for Microsoft Defender for Endpoint.

  3. Click Details, then the + icon. Enter the required information in the following fields.

  4. Label: Enter a connection name.

  5. Reference Values: Define variables here to templatize integration connections and actions. For example, you can use https://www.{{hostname}}.com where, hostname is a variable defined in this input. For more information on how to add data, see 'Add Data' Input Type for Integrations.

  6. Verify SSL: Select option to verify connecting server's SSL certificate (Default is Verify SSL Certificate).

  7. Remote Agent: Run this integration using the Devo SOAR Remote Agent.

  8. Server Address: URL of the server. Please enter the one that is closer to your geo-location. It is usually "https://api.securitycenter.windows.com".

  9. Tenant ID: Tenant ID of the registered application.

  10. Application ID: Application ID of the registered application.

  11. Secret Key: Secret key of registered application.

  12. After you've entered all the details, click Connect.

Actions for Microsoft Defender for Endpoint

List Machines

Retrieves a collection of Machines that have communicated with Microsoft Defender for Endpoint cloud.

Permission Required(Application): Machine.Read.All, Machine.ReadWrite.All

Input Field

Choose a connection that you have previously created and then fill in the necessary information in the following input fields to complete the connection.

Input Name

Description

Required

Input Name

Description

Required

OData

Jinja Templated OData v4 query filter. Supported OData operators: $filter on: computerDnsName, lastSeen, healthStatus, osPlatform, riskScore and rbacGroupId. Refer https://docs.microsoft.com/en-us/windows/security/threat-protection/microsoft-defender-atp/get-machines. Example: $filter=computerDnsName eq '{{hostname}}'&$skip=1.

Optional

Limit

Limit number of results per query. Value specified here will override $top operator (if provided) in OData Query (Default is 10000 machines per input row).

Optional

Output

A JSON object containing multiple rows of result:

  • has_error: True/False

  • error: message/null

  • other keys of machine object

``` {json}{ "has_error": false, "error": null, "id": "1e5bc9d7e413ddd7902c2932e418702b84d0cc07", "computerDnsName": "mymachine1.contoso.com", "firstSeen": "2018-08-02T14:55:03.7791856Z", "lastSeen": "2018-08-02T14:55:03.7791856Z", "osPlatform": "Windows10", "version": "1709", "osProcessor": "x64", "lastIpAddress": "172.17.230.209", "lastExternalIpAddress": "167.220.196.71", "osBuild": 18209, "healthStatus": "Active", "rbacGroupId": 140, "rbacGroupName": "The-A-Team", "riskScore": "Low", "exposureLevel": "Medium", "isAadJoined": true, "aadDeviceId": "80fe8ff8-2624-418e-9591-41f0491218f9", "machineTags": [ "test tag 1", "test tag 2" ] }

## Find machines by IP Find Machines seen with the requested internal IP in the time range of 15 minutes prior to and after a given timestamp. **Permission Required(Application):** Machine.Read.All, Machine.ReadWrite.All ### Input Field Choose a connection that you have previously created and then fill in the necessary information in the following input fields to complete the connection. | Input Name | Description | Required | | :--------- | :-------------------------------------------------------------------------------------------- | :------- | | IP Address | Requested internal IP address. | Required | | Timestamp | Requested timestamp(time range of 15 minutes prior and after). Example: YYYY-MM-DDTHH:MM:SSZ. | Required | ### Output A JSON object containing multiple rows of result: - has_error: True/False - error: message/null - result: List of machines. ## Get Machine by ID Retrieves specific Machine by its machine ID or computer name. **Permission Required(Application):** Machine.Read.All, Machine.ReadWrite.All ### Input Field Choose a connection that you have previously created and then fill in the necessary information in the following input fields to complete the connection. | Input Name | Description | Required | | : -------- | : -------- | : -------- | | Machine ID Column Name | Column name from the parent table that contains ID or name of the machine. | Required | | Related Data | Select the option to display related data with respect to the queried machine. (Default is `Machine Details`). 1. Logged On Users 2. Alerts 3. Installed Software 4. Discovered Vulnerabilities 5. Security Recommendations 6. Missing KBs (Security Updates) 7. Machine Details | Optional | ### Output A JSON object containing multiple rows of result: - has_error: True/False - error: message/null - other keys representing machine details. or multiple rows containing related data - has_error: True/False - error: message/null - other keys representing related data queried. ``` {json}{ "@odata.context": "https://api.securitycenter.windows.com/api/$metadata#Machine", "id": "1e5bc9d7e413ddd7902c2932e418702b84d0cc07", "computerDnsName": "mymachine1.contoso.com", "firstSeen": "2018-08-02T14:55:03.7791856Z", "lastSeen": "2018-08-02T14:55:03.7791856Z", "osPlatform": "Windows10", "version": "1709", "osProcessor": "x64", "lastIpAddress": "172.17.230.209", "lastExternalIpAddress": "167.220.196.71", "osBuild": 18209, "healthStatus": "Active", "rbacGroupId": 140, "rbacGroupName": "The-A-Team", "riskScore": "Low", "exposureLevel": "Medium", "isAadJoined": true, "aadDeviceId": "80fe8ff8-2624-418e-9591-41f0491218f9", "machineTags": [ "test tag 1", "test tag 2" ], "has_error": false, "error": null }

Response for Related Data as Security Recommendations

``` {json}{ "id": "va--git-scm--git", "productName": "git", "recommendationName": "Update Git to version 2.24.1.2", "weaknesses": 3, "vendor": "git-scm", "recommendedVersion": "2.24.1.2", "recommendationCategory": "Application", "subCategory": "", "severityScore": 0, "publicExploit": false, "activeAlert": false, "associatedThreats": [], "remediationType": "Update", "status": "Active", "configScoreImpact": 0, "exposureImpact": 0, "totalMachineCount": 0, "exposedMachinesCount": 1, "nonProductivityImpactedAssets": 0, "relatedComponent": "Git", "has_error": false, "error": null }

## Get File Information Retrieves file information by identifier sha1, or sha256. **Permission Required(Application):** File.Read.All ### Input Field Choose a connection that you have previously created and then fill in the necessary information in the following input fields to complete the connection. | Input Name | Description | Required | | :-------------------- | :------------------------------------------------------------------------- | :------- | | File Hash Column Name | Column name from the parent table that contains file hash sha1, or sha256. | Required | ### Output A JSON object containing multiple rows of result: - has_error: True/False - error: message/null - result: File details. ## Get File Related Machines Retrieves a collection of Machines related to a given file hash. **Permission Required(Application):** Machine.Read.All, Machine.ReadWrite.All ### Input Field Choose a connection that you have previously created and then fill in the necessary information in the following input fields to complete the connection. | Input Name | Description | Required | | :-------------------- | :------------------------------------------------------------------------- | :------- | | File Hash Column Name | Column name from the parent table that contains file hash sha1, or sha256. | Required | ### Output A JSON object containing multiple rows of result: - has_error: True/False - error: message/null - result: File details. ## Isolate Machine Isolates a machine from accessing the external network. **Permission Required(Application):** Machine.Isolate **Note:** Rate limitations for this API are 100 calls per minute and 1500 calls per hour. ### Input Field Choose a connection that you have previously created and then fill in the necessary information in the following input fields to complete the connection. | Input Name | Description | Required | | : -------- | : -------- | : -------- | | Machine ID Column Name | Column name from the parent table that contains the ID or name of the machine. | Required | | Comment | Jinja Template for comment to associate with the action. Example: This is {{comment_column_name}}. | Required | | Isolation Type | Type of isolation (default is Full isolation). | Required | ### Output A JSON object containing multiple rows of result: - has_error: True/False - error: message/null - result: Success/Failure message. ## Unisolate Machine Release machine from isolation. **Permission Required(Application):** Machine.Isolate **Note:** Rate limitations for this API are 100 calls per minute and 1500 calls per hour. ### Input Field Choose a connection that you have previously created and then fill in the necessary information in the following input fields to complete the connection. | Input Name | Description | Required | | :--------------------- | :------------------------------------------------------------------------------------------------- | :------- | | Machine ID Column Name | Column name from the parent table that contains the ID or name of the machine. | Required | | Comment | Jinja Template for comment to associate with the action. Example: This is {{comment_column_name}}. | Required | ### Output A JSON object containing multiple rows of result: - has_error: True/False - error: message/null - result: Success/Failure message. ## Advanced Hunting Run advanced queries. **Permission Required(Application):** AdvancedQuery.Read.All ### Input Field Choose a connection that you have previously created and then fill in the necessary information in the following input fields to complete the connection. | Input Name | Description | Required | | :--------- | :-------------------------------------------------------------------------- | :------- | | Query | Jinja Template for query to run. Example: {{table_column_name}} \| limit 2. | Required | ### Output A JSON object containing multiple rows of result: - has_error: True/False - error: message/null - result: Collection of results. ## Get Domain Related Alerts Retrieves a collection of alerts related to a given domain address. **Permission Required(Application):** Alert.Read.All, Alert.ReadWrite.All ### Input Field Choose a connection that you have previously created and then fill in the necessary information in the following input fields to complete the connection. | Input Name | Description | Required | | :-------------------------- | :-------------------------------------------------------------------------------------------------- | :------- | | Domain Address Column Name: | Column name from the parent table that contains domain address to retrieves a collection of alerts. | Required | ### Output A JSON object containing multiple rows of result: - has_error: True/False - error: message/null - result: List of Alerts. ## Get Domain Related Machines Retrieves a collection of machines related to a given domain address. **Permission Required(Application):** Machine.Read.All, Machine.ReadWrite.All ### Input Field Choose a connection that you have previously created and then fill in the necessary information in the following input fields to complete the connection. | Input Name | Description | Required | | :------------------------- | :---------------------------------------------------------------------------------------------------- | :------- | | Domain Address Column Name | Column name from the parent table that contains domain address to retrieves a collection of machines. | Required | ### Output A JSON object containing multiple rows of result: - has_error: True/False - error: message/null - result: List of Machines. ## Get Domain Statistics Retrieves the statistics on the given domain address. **Permission Required(Application):** URL.Read.All ### Input Field Choose a connection that you have previously created and then fill in the necessary information in the following input fields to complete the connection. | Input Name | Description | Required | | :------------------------- | :-------------------------------------------------------------------------------------- | :------- | | Domain Address Column Name | Column name from the parent table that contains domain address to retrieves statistics. | Required | ### Output A JSON object containing multiple rows of result: - has_error: True/False - error: message/null - result: Statistics. ## Submit Indicator (Deprecated) Submits new indicator entity. **Permission Required(Application):** Ti.ReadWrite, Ti.ReadWrite.All ### Input Field Choose a connection that you have previously created and then fill in the necessary information in the following input fields to complete the connection. | Input Name | Description | Required | | : -------- | : -------- | : -------- | | Indicator Value Column Name | Column name from the parent table that contains the value of the indicator entity. | Required | | Title | [Jinja-template](doc:jinja-template) for the title of the indicator. Example: This is {{title_column_name}}. | Required | | Description | [Jinja-template](doc:jinja-template) for a description of the indicator. Example: This is {{description_column_name}}. | Required | | Indicator Type | Type of the indicator (Default is FileSha1). | Optional | | Action | Action that will be taken if the indicator will be discovered in the organization (Default is Alert action). | Optional | | Severity | Severity of the indicator (Default is Informational). | Optional | | Application Column Name | Column name from the parent table that contains the application associated with the indicator (Default is empty value). | Optional | | Recommended Actions Column Name | Column name from the parent table that contains TI indicator alert recommended actions (Default is nothing). | Optional | | RBAC Group Names Column Name | Column name from the parent table that contains a comma-separated list of RBAC group names the indicator would be applied to (Default is nothing). | Optional | | Expiration Time Column Name | The expiration time of the indicator (Default is 1 year). Example: YYYY-MM-DDTHH:MM:SSZ. | Optional | ### Output A JSON object containing multiple rows of result: - has_error: True/False - error: message/null - result: Success/Failure message. ## List Indicators Retrieves a collection of all active Indicators. **Permission Required(Application):** Ti.ReadWrite, Ti.ReadWrite.All ### Input Field Choose a connection that you have previously created to complete the connection. ### Output A JSON object containing multiple rows of result: - has_error: True/False - error: message/null - result: List of Indicators. ## Delete Indicators Deletes an Indicator entity by ID. **Permission Required(Application):** Ti.ReadWrite, Ti.ReadWrite.All ### Input Field Choose a connection that you have previously created and then fill in the necessary information in the following input fields to complete the connection. | Input Name | Description | Required | | :----------------------- | :----------------------------------------------------------------------- | :------- | | Indicator Id Column Name | Column name from the parent table that contains the ID of the indicator. | Optional | ### Output A JSON object containing multiple rows of result: - has_error: True/False - error: message/null - result: Success/Failure message. ## Get User Related Alerts Retrieves a collection of alerts related to a given user ID. **Permission Required(Application):** Alert.Read.All, Alert.ReadWrite.All ### Input Field Choose a connection that you have previously created and then fill in the necessary information in the following input fields to complete the connection. | Input Name | Description | Required | | :------------------ | :------------------------------------------------------------------ | :------- | | User ID Column Name | Column name from the parent table that contains the ID of the user. | Optional | ### Output A JSON object containing multiple rows of result: - has_error: True/False - error: message/null - result: List of Alerts. ## Get User Related Machines Retrieves a collection of machines related to a given user ID. **Permission Required(Application):** Machine.Read.All, Machine.ReadWrite.All ### Input Field Choose a connection that you have previously created and then fill in the necessary information in the following input fields to complete the connection. | Input Name | Description | Required | | :------------------ | :------------------------------------------------------------------ | :------- | | User Id Column Name | Column name from the parent table that contains the ID of the user. | Optional | ### Output A JSON object containing multiple rows of result: - has_error: True/False - error: message/null - result: List of Machines. ## List Alerts Retrieves a collection of Alerts. **Permission Required(Application):** Alert.Read.All, Alert.ReadWrite.All ### Input Field Choose a connection that you have previously created and then fill in the necessary information in the following input fields to complete the connection. | Input Name | Description | Required | | :---------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :------- | | OData Query | [Jinja-templated](doc:jinja-template) OData v4 query filter. Supported OData operators: $filter on: alertCreationTime, lastUpdateTime, incidentId, InvestigationId, status, severity and category properties. $expand of evidence is also supported. Refer <https://docs.microsoft.com/en-us/windows/security/threat-protection/microsoft-defender-atp/get-alerts>. Example: `$filter=incidentId eq '{{incident_id}}'&$skip=1`. | Optional | | Limit | Limit number of results per query. Value specified here will override $top operator (if provided) in OData Query (Default is 10000 alerts per input row). | Optional | ### Output A JSON object containing multiple rows of result: - has_error: True/False - error: message/null - other keys of `alert` object ``` {json}{ "has_error": false, "error": null, "id": "da637308392288907382_-880718168", "incidentId": 7587, "investigationId": 723156, "assignedTo": "secop123@contoso.com", "severity": "Low", "status": "New", "classification": "TruePositive", "determination": null, "investigationState": "Queued", "detectionSource": "WindowsDefenderAv", "category": "SuspiciousActivity", "threatFamilyName": "Meterpreter", "title": "Suspicious 'Meterpreter' behavior was detected", "description": "Malware and unwanted software are undesirable applications that perform annoying, disruptive, or harmful actions on affected machines. Some of these undesirable applications can replicate and spread from one machine to another. Others are able to receive commands from remote attackers and perform activities associated with cyber attacks.\n\nA malware is considered active if it is found running on the machine or it already has persistence mechanisms in place. Active malware detections are assigned higher severity ratings.\n\nBecause this malware was active, take precautionary measures and check for residual signs of infection.", "alertCreationTime": "2020-07-20T10:53:48.7657932Z", "firstEventTime": "2020-07-20T10:52:17.6654369Z", "lastEventTime": "2020-07-20T10:52:18.1362905Z", "lastUpdateTime": "2020-07-20T10:53:50.19Z", "resolvedTime": null, "machineId": "12ee6dd8c833c8a052ea231ec1b19adaf497b625", "computerDnsName": "temp123.middleeast.corp.microsoft.com", "rbacGroupName": "MiddleEast", "aadTenantId": "a839b112-1253-6432-9bf6-94542403f21c", "relatedUser": { "userName": "temp123", "domainName": "MIDDLEEAST" }, "comments": [ { "comment": "test comment for docs", "createdBy": "secop123@contoso.com", "createdTime": "2020-07-21T01:00:37.8404534Z" } ], "evidence": [] }

Offboard Machine

Offboard device from Defender for Endpoint.

Permission Required(Application): Machine.Offboard

Input Field

Choose a connection that you have previously created and then fill in the necessary information in the following input fields to complete the connection.

Input Name

Description

Required

Input Name

Description

Required

Machine Id

Jinja-templated query containing machine id. Example: {{machine_id_column_name}}.

Required

Comment

Jinja-templated query containing comment to associate with the action.

 

Example: This is {{comment_column_name}}.

Required

 

Output

A JSON object containing multiple rows of result:

  • has_error: True/False

  • error: message/null

  • machine action object

``` {json}{ "result": { "@odata.context": "https://api.securitycenter.windows.com/api/$metadata#MachineActions/$entity", "id": "1234-1234-1234-1234-b1234", "type": "Offboard", "title": null, "requestor": "1234-1234-1234-1234-b1234-9498", "requestorComment": "Test", "status": "Pending", "machineId": "7h7g8g0ggh00f957995nf99845bjv9rr455bjh8", "computerDnsName": "dns", "creationDateTimeUtc": "2021-02-15T14:29:35.1205009Z", "lastUpdateDateTimeUtc": "2021-02-15T14:29:35.1205009Z", "cancellationRequestor": null, "cancellationComment": null, "cancellationDateTimeUtc": null, "errorHResult": 0, "scope": null, "externalId": null, "requestSource": "PublicApi", "relatedFileInfo": null, "commands": [], "error": null, "has_error": false }, "error": null, "has_error": false }

## Stop and Quarantine File Stop execution of a file on a device and delete it. **Permission Required(Application):** Machine.StopAndQuarantine, Machine.Read.All, Machine.ReadWrite.All ### Input Field Choose a connection that you have previously created and then fill in the necessary information in the following input fields to complete the connection. | Input Name | Description | Required | | : -------- | : -------- | : -------- | | Machine Id | [Jinja-templated](doc:jinja-template) query containing machine id. Example: {{machine_id_column_name}}. | Required | | Comment | [Jinja-templated](doc:jinja-template) query containing comment to associate with the action. Example: This is {{comment_column_name}}. | Required | | Sha1 | [Jinja-templated](doc:jinja-template) query containing Sha1 of the file to stop and quarantine on the device. Example: {{sha1_column_name}}. | Required | ### Output A JSON object containing multiple rows of result: - has_error: True/False - error: message/null \*machine action object ## Collect Investigation Package Collect investigation package from a device. **Permission Required(Application):** Machine.CollectForensics ### Input Field Choose a connection that you have previously created and then fill in the necessary information in the following input fields to complete the connection. | Input Name | Description | Required | | : -------- | : -------- | : -------- | | Machine Id | [Jinja-templated](doc:jinja-template) query containing machine id. Example: {{machine_id_column_name}}. | Required | | Comment | [Jinja-templated](doc:jinja-template) query containing comment to associate with the action. Example: This is {{comment_column_name}}. | Required | ### Output A JSON object containing multiple rows of result: - has_error: True/False - error: message/null \*machine action object ``` {json}{ "result": { "@odata.context": "https://api.securitycenter.windows.com/api/$metadata#MachineActions/$entity", "id": "b38b45bf-76ae-5628-9bac-3cfbab3d70a9", "type": "CollectInvestigationPackage", "title": null, "requestor": "06410c85-5000-7834-9498-343d267decbd", "requestorComment": "Test", "status": "Pending", "machineId": "5ae75acab7decf0y7r5292ebebf27cb97c40f4a7", "computerDnsName": "6298-614684753", "creationDateTimeUtc": "2021-02-10T15:39:57.0681351Z", "lastUpdateDateTimeUtc": "2021-02-10T15:39:57.0681351Z", "cancellationRequestor": null, "cancellationComment": null, "cancellationDateTimeUtc": null, "errorHResult": 0, "scope": null, "externalId": null, "requestSource": "PublicApi", "relatedFileInfo": null, "commands": [], "error": null, "has_error": false }, "error": null, "has_error": false }

Run Antivirus Scan

Initiate Microsoft Defender Antivirus scan on a device.

Permission Required(Application): Machine.Scan

Input Field

Choose a connection that you have previously created and then fill in the necessary information in the following input fields to complete the connection.

Input Name

Description

Required

Input Name

Description

Required

Machine Id

Jinja-templated query containing machine id.

 

Example: {{machine_id_column_name}}.

Required

 

Comment

Jinja-templated query containing comment to associate with the action.

 

Example: This is {{comment_column_name}}.

Required

 

Scan Type

Select the type of the Scan. (Default is Quick).

Optional

Output

A JSON object containing multiple rows of result:

  • has_error: True/False

  • error: message/null
    *machine action object

``` {json}{ "result": { "@odata.context": "https://api.securitycenter.windows.com/api/$metadata#MachineActions/$entity", "id": "89b47775-c855-46b9-7869-8228be4ed29e", "type": "RunAntiVirusScan", "title": null, "requestor": "06410c85-5000-4587-9498-343d267decbd", "requestorComment": "Test", "status": "Pending", "machineId": "5ae75acab7decfhj788292ebebf27cb97c40f4a7", "computerDnsName": "ui90-614684753", "creationDateTimeUtc": "2021-02-10T15:38:20.6869253Z", "lastUpdateDateTimeUtc": "2021-02-10T15:38:20.6869253Z", "cancellationRequestor": null, "cancellationComment": null, "cancellationDateTimeUtc": null, "errorHResult": 0, "scope": "Quick", "externalId": null, "requestSource": "PublicApi", "relatedFileInfo": null, "commands": [], "error": null, "has_error": false }, "error": null, "has_error": false }

Run Live Response Action

Run live response commands on a device.

Input Field

Choose a connection that you have previously created and then fill in the necessary information in the following input fields to complete the connection.

Input Name

Description

Required

Input Name

Description

Required

Machine Id

Jinja-templated query containing machine id. Example: {{machine_id_column_name}}

Required

Comment

Jinja-templated query containing comment to associate with the action. e.g. This is {{comment_column_name}}

Required

Command

Jinja templated JSON Array containing commands to execute. Allowed values are PutFile, RunScript, GetFile (must be in this order with no limit on repetitions). e.g. [{"type":"RunScript","params":[{"key":"ScriptName","value":"minidump.ps1"},{"key":"Args","value":"OfficeClickToRun"}]},{"type":"GetFile","params":[{"key":"Path","value":"C:\windows\TEMP\OfficeClickToRun.dmp.zip"}]}]

Required

Output

JSON containing the following items:

``` {json}{ "codes": [ { "code":"", "language": "json" } ] }

Release Notes

  • v4.2.0 - New Actions Get Live Response Results and Run Live Response Action

  • v4.1.0 - Deprecated old action Submit Indicator and added new one.

  • v4.0.0 - Updated architecture to support IO via filesystem