×
Microsoft Defender for Endpoints
MS Defender for Endpoints

Overview

The Microsoft Defender for Endpoints plugin supports the ability to list alerts, get an alert’s details, and update an alert within a customer’s tenant. Additionally, a generic node exists to expose all REST API methods.

Functionality

The Security Flow Microsoft Defender for Endpoints plugin provides the ability to call any REST API end-point through the NL-MS-Defender-EP-REST-API node. Additionally, the plugin provides direct access to

  • trigger flows periodically based on searches for alerts
  • retrieve alerts by executing a search
  • retrieve an alert’s details using its ID
  • update an existing alert

Instance Configuration Parameters

Property
Description

Instance Name

Name for the Microsoft Defender for Endpoints plugin instance.


Unique ID

A system-wide unique identifier for this plugin instance used to locate the service.


Microsoft Defender Server

Host name of the Microsoft Defender for Endpoints server. For better performance, select a server closer to your geo location.


API Version

Optional API Version of the Microsoft Defender for Endpoints REST API. When not specified, it defaults to the latest. E.g., ‘v1.0’.


Authorization (OAuth2)

Application authorization used to access Microsoft Defender for Endpoints services. Visit https://docs.microsoft.com/en-us/microsoft-365/security/defender-endpoint/exposed-apis-create-app-nativeapp?view=o365-worldwide for details on setting up an application with delegated access to Microsoft Defender for Endpoints.

Flow Nodes

This node provides access to search for alerts, retrieve an alert, and update an alert with the Microsoft Defender for Endpoints API.
Property
Description

Name

The display name of the node within the flows.


Unique ID

A system-wide unique identifier for this plugin instance used to locate the service.


Action

Configuration option determining the type of operation to perform:

  • Find Alerts: Retrieve alerts by executing a search.
  • Get Alert: Retrieves an alert’s details using its ID.
  • Update Alert: Updates an existing alert.

Successful results for an action are placed in msg.payload.msdefenderendpoints.[uniqueId].response.


Alerts Filter

Defines the filter query. Clear the content of the Alerts Filter field to disable filtering and return all alerts up to the specified Size Limit. Learn more about filtering using the List Alerts API page. An example filter is supplied to pull all new alerts created within the last ten days. The filter field uses variable substitution from the incoming message using a mustache format. Visit the Template Engine and Formatters page to learn more.


Include Evidence

Enabling Include Evidence returns the evidence for each alert found.


Size Limit

The maximum number of returned alerts is limited to the Size Limit.


Alert ID

The ID of the alert being retrieved or updated. When set to Standard Alert Location, the alert ID is expected to be within the response at alert.id.


Status

Specifies the current status of the alert. Possible values are: New, InProgress, or Resolved. Invalid values will cause a runtime error in the REST API request.


Assign To

Owner of the alert. Typically, a user principal name (UPN).


Classification

Analyst classification of the alert. Possible values are: Unknown, FalsePositive, or TruePositive. Invalid values will cause a runtime error in the REST API request.


Determination

Analyst determination of the alert. Possible values are: NotAvailable, Apt, Malware, SecurityPersonnel, SecurityTesting, UnwantedSoftware, or Other. Invalid values will cause a runtime error in the REST API request.


Comment

Comment to be added to the alert. The Comment field uses variable substitution from the incoming message using a mustache format. Visit the Template Engine and Formatters page to learn more.

Microsoft Defender for Endpoints Alert search node to find matching alerts to use as triggering events within a flow.
Property
Description

Name

The display name of the node within the flows.


Unique ID

A system-wide unique identifier for this plugin instance used to locate the service.


Repeat

The time interval between alert searches.


Alerts Filter

Defines the filter query. Clear the content of the Alerts Filter field to disable filtering and return all alerts up to the specified Size Limit. Learn more about filtering using the List Alerts API page. An example filter is supplied to pull all new alerts created within the last ten days. The filter field uses variable substitution from the incoming message using a mustache format. Visit the Template Engine and Formatters page to learn more.


Behavior: Include Evidence

Enabling Include Evidence returns the evidence for each alert found.


Size Limit

The maximum number of returned alerts is limited to the Size Limit.

This node provides the capability to call any of the Microsoft Defender for Endpoints REST API end-points. Reference the Supported Microsoft Defender for Endpoint APIs document for the path, request method, query parameters, and body to be configured in this node.
Property
Description

Name

The display name of the node within the flows.


Unique ID

A system-wide unique identifier for this plugin instance used to locate the service.


Path Segment

The Path Segment defines a mustache template for the URL’s path after the api and optional version. The following example sets the path for retrieving IP statistics. The path for getting via the IP statistics API with a str context value is ips/{{payload.ip}}/stats. If the payload.ip is 10.209.67.177, the final URL is https://[hostname]/api/[version]/ips/10.209.67.177/stats, where the hostname and version came from the plugin instance configuration.


HTTP Method

The HTTP Method must evaluate to one of GET, POST, PUT, PATCH, or DELETE. Any other value will cause a non-recoverable failure.


Query Parameters

When needed, the Query Parameters must evaluate to a JSON object or string. The object contains the query parameters (URL parameters) as key-value pairs. Values may include any value convertible to string. Array values will result in the same key being supplied with each element as a value within the query parameters. The string must contain the URL parameters in the key1=value1&key2=value2&...&keyN=valueN format. If the Query Parameters uses the {} JSON context, mustache template substitution is applied prior to generation of the final JSON object.


Body Parameters

When needed, the Body Parameters must evaluate to a JSON object. The object contains the request payload as specified by REST API end-point. If the Body Parameters uses the {} JSON context, mustache template substitution is applied prior to generation of the final JSON object.

Nevelex Labs, Main Office

Metro Office Park
2950 Metro Drive, Suite 104
Bloomington, MN 55425
Phone: +1 952-500-8921

©Nevelex Labs, LLC. 2018-2021, All Rights Reserved.

EULA