DocumentationIntegrations
Documentation
Contact Us

Microsoft Defender for Endpoint

Version: 4.2.0

Suggest Edits

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 LogicHub

  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.
    • 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 LogicHub 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.
  4. 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 NameDescriptionRequired
ODataJinja 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
LimitLimit 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
{
  "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 NameDescriptionRequired
IP AddressRequested internal IP address.Required
TimestampRequested 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 NameDescriptionRequired
Machine ID Column NameColumn name from the parent table that contains ID or name of the machine.Required
Related DataSelect 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.
{
    "@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

{
  "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 NameDescriptionRequired
File Hash Column NameColumn 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 NameDescriptionRequired
File Hash Column NameColumn 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 NameDescriptionRequired
Machine ID Column NameColumn name from the parent table that contains the ID or name of the machine.Required
CommentJinja Template for comment to associate with the action.
Example: This is {{comment_column_name}}.		Required
Isolation TypeType 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 NameDescriptionRequired
Machine ID Column NameColumn name from the parent table that contains the ID or name of the machine.Required
CommentJinja 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 NameDescriptionRequired
QueryJinja 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 NameDescriptionRequired
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 NameDescriptionRequired
Domain Address Column NameColumn 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 NameDescriptionRequired
Domain Address Column NameColumn 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 NameDescriptionRequired
Indicator Value Column NameColumn name from the parent table that contains the value of the indicator entity.Required
TitleJinja-template for the title of the indicator. Example: This is {{title_column_name}}.Required
DescriptionJinja-template for a description of the indicator. Example: This is {{description_column_name}}.Required
Indicator TypeType of the indicator (Default is FileSha1).Optional
ActionAction that will be taken if the indicator will be discovered in the organization (Default is Alert action).Optional
SeveritySeverity of the indicator (Default is Informational).Optional
Application Column NameColumn name from the parent table that contains the application associated with the indicator (Default is empty value).Optional
Recommended Actions Column NameColumn name from the parent table that contains TI indicator alert recommended actions (Default is nothing).Optional
RBAC Group Names Column NameColumn 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 NameThe 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 NameDescriptionRequired
Indicator Id Column NameColumn 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 NameDescriptionRequired
User ID Column NameColumn 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 NameDescriptionRequired
User Id Column NameColumn 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 NameDescriptionRequired
OData QueryJinja-templated 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
LimitLimit 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
{
  "has_error": false,
  "error": null,
  "id": "da637308392288907382_-880718168",
  "incidentId": 7587,
  "investigationId": 723156,
  "assignedTo": "[email protected]",
  "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": "[email protected]",
      "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 NameDescriptionRequired
Machine IdJinja-templated query containing machine id. Example: {{machine_id_column_name}}.Required
CommentJinja-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
{
  "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 NameDescriptionRequired
Machine IdJinja-templated query containing machine id.
Example: {{machine_id_column_name}}.		Required
CommentJinja-templated query containing comment to associate with the action.
Example: This is {{comment_column_name}}.		Required
Sha1Jinja-templated 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 NameDescriptionRequired
Machine IdJinja-templated query containing machine id. Example: {{machine_id_column_name}}.Required
CommentJinja-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
{
  "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 NameDescriptionRequired
Machine IdJinja-templated query containing machine id.
Example: {{machine_id_column_name}}.		Required
CommentJinja-templated query containing comment to associate with the action.
Example: This is {{comment_column_name}}.		Required
Scan TypeSelect 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
{
  "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
}

Submit Indicator

Submits new indicator entity

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 NameDescriptionRequired
BodyJinja templated JSON field containing the body of the request for submitting indicator. Example: '{"indicatorValue": "220e7d15b011d7fac48f2bd61114db1022197f7f","indicatorType": "FileSha1","title": "test","application": "demo-test","expirationTime": "2020-12-12T00:00:00Z","action": "AlertAndBlock","severity": "Informational","description": "test","recommendedActions": "nothing","rbacGroupNames": ["group1", "group2"]}'Required

Output

JSON containing the following items:

{
    "indicatorValue": "220e7d15b011d7fac48f2bd61114db1022197f7f",
    "indicatorType": "FileSha1",
    "title": "test",
    "application": "demo-test",
    "expirationTime": "2020-12-12T00:00:00Z",
    "action": "AlertAndBlock",
    "severity": "Informational",
    "description": "test",
    "recommendedActions": "nothing",
    "rbacGroupNames": ["group1", "group2"],
    "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 NameDescriptionRequired
Machine IdJinja-templated query containing machine id. Example: {{machine_id_column_name}}Required
CommentJinja-templated query containing comment to associate with the action. e.g. This is {{comment_column_name}}Required
CommandJinja 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:

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

Get Live Response Results

Retrieves a specific live response command result by its index.

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 NameDescriptionRequired
Machine Action IdJinja-templated query containing machine id. Example: {{machine_id_column_name}}Required
Command IndexCommand IndexRequired

Output

JSON containing the following items:

{
"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

Updated 9 months ago

© Devo Technology Inc. All Rights Reserved.