Microsoft Defender for Endpoint

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

Integration with LogicHub

Connecting with Microsoft Defender for Endpoint

To connect with Microsoft Defender for Endpoint following details are required:

  • Label: 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.
  • 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.

Actions with Microsoft Defender for Endpoint

List Machines

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

Inputs to this Action

Output of Action
Multiple rows of JSON containing the following items:

  • 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.

Inputs to this Action

  • Connection: Choose a connection that you have created.
  • IP Address: Requested internal IP address.
  • Timestamp: Requested timestamp(time range of 15 minutes prior and after). Example: YYYY-MM-DDTHH:MM:SSZ.

Output of Action
JSON containing following items:

  • 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.

Inputs to this Action

  • Connection: Choose a connection that you have created.
  • Machine ID Column Name: Column name from the parent table that contains ID or name of the machine.
  • Related Data (Optional): 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

Output of Action
JSON containing the following items:

  • 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.

Inputs to this Action

  • Connection: Choose a connection that you have created.
  • File Hash Column Name: Column name from the parent table that contains file hash sha1, or sha256.

Output of Action
JSON containing the following items:

  • 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.

Inputs to this Action

  • Connection: Choose a connection that you have created.
  • File Hash Column Name: Column name from the parent table that contains file hash sha1, or sha256.

Output of Action
JSON containing the following items:

  • has_error: True/False
  • error: message/null
  • result: File details.

Isolate Machine

Isolates a machine from accessing the external network.

Inputs to this Action

  • Connection: Choose a connection that you have created.
  • Machine ID Column Name: Column name from the parent table that contains the ID or name of the machine.
  • Comment: Jinja Template for comment to associate with the action. Example: This is {{comment_column_name}}.
  • Isolation Type: Type of isolation (default is Full isolation).

Output of Action
JSON containing the following items:

  • has_error: True/False
  • error: message/null
  • result: Success/Failure message.

Unisolate Machine

Release machine from isolation.

Inputs to this Action

  • Connection: Choose a connection that you have created.
  • Machine ID Column Name: Column name from the parent table that contains the ID or name of the machine.
  • Comment: Jinja Template for comment to associate with the action. Example: This is {{comment_column_name}}.

Output of Action
JSON containing the following items:

  • has_error: True/False
  • error: message/null
  • result: Success/Failure message.

Advanced Hunting

Run advanced queries.

Inputs to this Action

  • Connection: Choose a connection that you have created.
  • Query: Jinja Template for query to run. Example: {{table_column_name}} | limit 2.

Output of Action
JSON containing the following items:

  • 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.

Inputs to this Action

  • Connection: Choose a connection that you have created.
  • Domain Address Column Name: Column name from the parent table that contains domain address to retrieves a collection of alerts.

Output of Action
JSON containing the following items:

  • 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.

Inputs to this Action

  • Connection: Choose a connection that you have created.
  • Domain Address Column Name: Column name from the parent table that contains domain address to retrieves a collection of machines.

Output of Action
JSON containing the following items:

  • has_error: True/False
  • error: message/null
  • result: List of Machines.

Get Domain Statistics

Retrieves the statistics on the given domain address.

Inputs to this Action

  • Connection: Choose a connection that you have created.
  • Domain Address Column Name: Column name from the parent table that contains domain address to retrieves statistics.

Output of Action
JSON containing the following items:

  • has_error: True/False
  • error: message/null
  • result: Statistics.

Submit Indicator

Submits new indicator entity.

Inputs to this Action

  • Connection: Choose a connection that you have created.
  • Indicator Value Column Name: Column name from the parent table that contains the value of the indicator entity.
  • Title: Jinja Template for the title of the indicator. Example: This is {{title_column_name}}.
  • Description: Jinja Template for a description of the indicator. Example: This is {{description_column_name}}.
  • Indicator Type (Optional): Type of the indicator (Default is FileSha1).
  • Action (Optional): Action that will be taken if the indicator will be discovered in the organization (Default is Alert action).
  • Severity (Optional): Severity of the indicator (Default is Informational).
  • Application Column Name (Optional): Column name from the parent table that contains the application associated with the indicator (Default is empty value).
  • Recommended Actions Column Name (Optional): Column name from the parent table that contains TI indicator alert recommended actions (Default is nothing).
  • RBAC Group Names Column Name (Optional): 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).
  • Expiration Time Column Name (Optional): The expiration time of the indicator (Default is 1 year). Example: YYYY-MM-DDTHH:MM:SSZ.

Output of Action
JSON containing the following items:

  • has_error: True/False
  • error: message/null
  • result: Success/Failure message.

List Indicators

Retrieves a collection of all active Indicators.

Inputs to this Action

  • Connection: Choose a connection that you have created.

Output of Action
JSON containing the following items:

  • has_error: True/False
  • error: message/null
  • result: List of Indicators.

Delete Indicators

Deletes an Indicator entity by ID.

Inputs to this Action

  • Connection: Choose a connection that you have created.
  • Indicator Id Column Name (Optional): Column name from the parent table that contains the ID of the indicator.

Output of Action
JSON containing the following items:

  • 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.

Inputs to this Action

  • Connection: Choose a connection that you have created.
  • User ID Column Name (Optional): Column name from the parent table that contains the ID of the user.

Output of Action
JSON containing the following items:

  • 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.

Inputs to this action

  • Connection: Choose a connection that you have created.
  • User Id Column Name (Optional): Column name from the parent table that contains the ID of the user.

Output of Action
JSON containing the following items:

  • has_error: True/False
  • error: message/null
  • result: List of Machines.

List Alerts

Retrieves a collection of Alerts.

Inputs to this Action

  • Connection: Choose a connection that you have created.
  • OData Query (Optional): Jinja 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.
  • Limit (Optional): 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).

Output of Action
Multiple rows of JSON containing following items:

  • 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.

Inputs to this Action

  • Connection: Choose a connection that you have created.
  • Jinja Templated Machine Id: Jinja-templated query containing machine id. Example: {{machine_id_column_name}}.
  • Jinja Templated Comment: Jinja-templated query containing comment to associate with the action. e.g. This is {{comment_column_name}}.

Output of Action
Multiple rows of JSON containing following items:

  • 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.

Inputs to this Action

  • Connection: Choose a connection that you have created.
  • Jinja Templated Machine Id: Jinja-templated query containing machine id. Example: {{machine_id_column_name}}.
  • Jinja Templated Comment: Jinja-templated query containing comment to associate with the action. e.g. This is {{comment_column_name}}.
  • Jinja Templated Sha1: Jinja-templated query containing Sha1 of the file to stop and quarantine on the device. Example: {{sha1_column_name}}.

Output of Action
Multiple rows of JSON containing following items:

  • has_error: True/False
  • error: message/null
    *machine action object

Collect Investigation Package

Collect investigation package from a device.

Inputs to this Action

  • Connection: Choose a connection that you have created.
  • Jinja Templated Machine Id: Jinja-templated query containing machine id. Example: {{machine_id_column_name}}.
  • Jinja Templated Comment: Jinja-templated query containing comment to associate with the action. e.g. This is {{comment_column_name}}.

Output of Action
Multiple rows of JSON containing following items:

  • 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.

Inputs to this Action

  • Connection: Choose a connection that you have created.
  • Jinja Templated Machine Id: Jinja-templated query containing machine id. Example: {{machine_id_column_name}}.
  • Jinja Templated Comment: Jinja-templated query containing comment to associate with the action. e.g. This is {{comment_column_name}}.
  • Scan Type (Optional): Select the type of the Scan. (Default is Quick)

Output of Action
Multiple rows of JSON containing following items:

  • 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
}

Did this page help you?