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
Navigate to Automations > Integrations.
Search for Microsoft Defender for Endpoint.
Click Details, then the + icon. Enter the required information in the following fields.
Label: Enter a connection name.
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.
Verify SSL: Select option to verify connecting server's SSL certificate (Default is Verify SSL Certificate).
Remote Agent: Run this integration using the Devo SOAR Remote Agent.
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".
Tenant ID: Tenant ID of the registered application.
Application ID: Application ID of the registered application.
Secret Key: Secret key of registered application.
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 |
---|---|---|
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: | 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 |
---|---|---|
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 |
---|---|---|
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 |
---|---|---|
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 ActionsGet Live Response Results
andRun Live Response Action
v4.1.0
- Deprecated old actionSubmit Indicator
and added new one.v4.0.0
- Updated architecture to support IO via filesystem