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 most REST API end-points 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
Name for the Microsoft Defender for Endpoints plugin instance.
A system-wide unique identifier for this plugin instance used to locate the service.
Host name of the Microsoft Defender for Endpoints server. For better performance, select a server closer to your geo location.
Optional API Version of the Microsoft Defender for Endpoints REST API. When not specified, it defaults to the latest. E.g., ‘v1.0’.
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
The display name of the node within the flows.
A system-wide unique identifier for this plugin instance used to locate the service.
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.
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.
Enabling Include Evidence returns the evidence for each alert found.
The maximum number of returned alerts is limited to the Size Limit.
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.
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.
Owner of the alert. Typically, a user principal name (UPN).
Analyst classification of the alert. Possible values are: Unknown, FalsePositive, or TruePositive. Invalid values will cause a runtime error in the REST API request.
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 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.
The display name of the node within the flows.
A system-wide unique identifier for this plugin instance used to locate the service.
The time interval between alert searches.
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.
Enabling Include Evidence returns the evidence for each alert found.
The maximum number of returned alerts is limited to the Size Limit.
The display name of the node within the flows.
A system-wide unique identifier for this plugin instance used to locate the service.
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.
The HTTP Method must evaluate to one of GET, POST, PUT, PATCH, or DELETE. Any other value will cause a non-recoverable failure.
When needed, the Query Parameters must evaluate to a JSON object or string. When Query Parameters evaluates to an object, the object contains the query parameters (URL parameters) as key-value pairs. Values may include any value convertible to a string. Array values will result in the same key being supplied with each element as a value within the query parameters. When Query Parameters evaluates to a string, it 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.
When needed, the Body Parameters must evaluate to a JSON object. The object contains the request payload as specified by the 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.
Metro Office Park
2950 Metro Drive, Suite 104
Bloomington, MN 55425
Phone: +1 952-500-8921
©Nevelex Labs, LLC. 2018-2024, All Rights Reserved.
EULA