Microsoft Defender for Endpoint Integration Guide

Overview

The Microsoft Defender for Endpoint (MDE) integration connects your NINA workflows to the Microsoft Defender for Endpoint REST API, enabling comprehensive endpoint security operations. This integration lets you manage security alerts, investigate endpoint threats, query vulnerability and software inventory, trigger live response actions on devices, and manage custom threat intelligence indicators — all directly from your workflows.

Microsoft Defender for Endpoint is Microsoft's enterprise endpoint security platform offering preventative protection, post-breach detection, automated investigation, and response capabilities across Windows, macOS, Linux, Android, and iOS devices.

Status

We currently support 13 resources across the full MDE API surface:

Alert Management: List, retrieve, update, and batch-update security alerts with OData filtering, severity and status shortcuts, and evidence expansion
Machine (Device) Management: Query the managed device inventory, retrieve logon users, installed software, vulnerabilities, and recommendations per device; add/remove tags individually or in bulk; find devices by IP address or tag
Machine Actions: Trigger and track response actions — network isolation, antivirus scans, forensic package collection, code-execution restriction, and file quarantine
Vulnerability Management (TVM): Query CVEs across the organization, retrieve devices and software affected by a specific CVE, and list all vulnerabilities grouped by machine and software
Software Inventory (TVM): Query the organization's software inventory, retrieve version distributions, affected devices, exposed vulnerabilities, and missing KBs per software
Security Recommendations (TVM): List and retrieve security recommendations, find affected devices and related vulnerabilities, and get recommendations per device
Remediation Tasks (TVM): List, retrieve, update, and find devices for remediation activities
Threat Intelligence Indicators (IoC): Create, list, retrieve, update, and delete custom file hash, IP, domain, URL, and certificate indicators
File: Retrieve file metadata, prevalence statistics, related alerts, and machines that observed a file hash
IP Address: Retrieve alerts and prevalence statistics for a given IP
Domain: Retrieve alerts, related machines, and statistics for a domain
User: Retrieve alerts and related machines for a user account
Score: Retrieve the organizational exposure score, device secure score, and exposure score breakdown by device group

Credential Configuration

Before using the Microsoft Defender for Endpoint integration in your workflows, you need to configure OAuth2 credentials through an Azure App Registration. The integration uses the OAuth2 client credentials flow (no user interaction required) against the Azure AD v1.0 token endpoint and the MDE Security Center API.

Authentication Method

OAuth2 Client Credentials

Field	Description	Example
Tenant ID	Directory (tenant) ID from Azure portal	`87654321-4321-4321-4321-fedcba987654`
Client ID	Application (client) ID from Azure App Registration	`12345678-1234-1234-1234-123456789abc`
Client Secret	Client secret value from Azure App Registration	`abcd1234~efgh5678ijklMNOP9012qrst.UV`
Base URL	MDE API base URL. Change only for sovereign cloud environments.	`https://api.securitycenter.microsoft.com`

How to create an Azure App Registration:

Sign in to the Azure portal
Navigate to Microsoft Entra ID > App registrations
Click New registration
Provide a name (e.g., "NINA MDE Integration")
Select Accounts in this organizational directory only
Click Register
Note the Application (client) ID and Directory (tenant) ID shown on the overview page
Go to Certificates & secrets > Client secrets > New client secret
Enter a description and expiration period, then click Add
Copy the Value immediately — it will not be shown again

Required API Permissions (Application permissions on WindowsDefenderATP):

Grant the following application permissions and click Grant admin consent:

Permission	Required for
`Alert.Read.All`	Reading alerts
`Alert.ReadWrite.All`	Updating and batch-updating alerts
`Machine.Read.All`	Reading device inventory, logon users, and device-related data
`Machine.ReadWrite.All`	Triggering machine actions (isolate, scan, etc.) and managing tags
`Vulnerability.Read.All`	Querying CVEs and TVM vulnerability data
`Software.Read.All`	Querying software inventory
`Score.Read.All`	Retrieving exposure and secure scores
`Ti.ReadWrite`	Creating, updating, and deleting custom IoC indicators
`Ti.Read.All`	Listing and reading custom IoC indicators
`RemediationTasks.Read.All`	Reading remediation tasks
`RemediationTasks.ReadWrite.All`	Updating remediation tasks

Note: WindowsDefenderATP is the Azure AD resource display name for the Microsoft Defender for Endpoint API. In the Azure portal, search for "WindowsDefenderATP" when adding API permissions, or use the resource URI https://api.securitycenter.microsoft.com/.

Sovereign Cloud Environments

If your organization uses a government or sovereign cloud, override the Base URL credential field with the appropriate endpoint:

Cloud	Base URL
Commercial (default)	`https://api.securitycenter.microsoft.com`
US Government GCC	`https://api.securitycenter.microsoft.us`
US Government GCC High	`https://api-gcc.securitycenter.microsoft.us`

Creating a Microsoft Defender for Endpoint Credential

Navigate to the Credentials section in NINA
Click Add New Credential
Fill in the credential details:
- Name: A descriptive name (e.g., "MDE Production")
- Description: Optional details about the credential's purpose
- Integration Service: Select "Microsoft Defender for Endpoint"
- Auth Type: Select "OAuth2"
- Tenant ID: Enter your Directory (tenant) ID
- Client ID: Enter your Application (client) ID
- Client Secret: Enter your client secret value
- Base URL: Leave blank for commercial cloud (defaults to https://api.securitycenter.microsoft.com)
Click Test Connection to verify credentials — this acquires an OAuth token from Azure AD to confirm the credentials are valid
Click Save to store the credential

Supported Resources and Operations

Alert

Manage MDE security alerts. Supports OData v4 $filter, $top (max 10,000), $skip, $orderby, and $expand.

Operation	Name	Description
`list`	List Alerts	Retrieve a collection of alerts with optional OData filtering, sorting, and severity/status shortcuts
`get`	Get Alert	Retrieve a single alert by its ID
`update`	Update Alert	Update status, classification, determination, assignee, or add a comment to an alert
`batchUpdate`	Batch Update Alerts	Update multiple alerts at once (up to rate limit: 10 calls/min, 500 calls/hr)

Key parameters for list:

$filter — OData filter expression (e.g., severity eq 'High' and status eq 'New')
$top — number of alerts to return (default: 100, max: 10,000)
$skip — number of alerts to skip for pagination
$orderby — sort expression (e.g., alertCreationTime desc)
$expand — set to evidence to include evidence entities inline
severity — shortcut filter: UnSpecified, Informational, Low, Medium, High
status — shortcut filter: Unknown, New, InProgress, Resolved
alertCreationTimeGte — shortcut filter: only alerts created at or after this RFC3339 timestamp

Key parameters for update:

alertId (required) — the alert ID
updateFields.status — New, InProgress, Resolved
updateFields.assignedTo — analyst email address
updateFields.classification — TruePositive, InformationalExpectedActivity, FalsePositive
updateFields.determination — see determination values below
updateFields.comment — comment text to append

Key parameters for batchUpdate:

alertIds (required) — array of alert IDs
updateFields — same fields as update

Machine (Device)

Query the managed endpoint inventory and perform per-device data retrieval and tagging operations.

Operation	Name	Description
`list`	List Devices	Retrieve managed devices with OData filtering and health/risk shortcut filters
`listLogonUsers`	List Logon Users	Retrieve logged-on users for a specific device
`listAlerts`	List Alerts by Device	Retrieve all alerts related to a device
`listSoftware`	List Installed Software	Retrieve installed software on a specific device
`listVulnerabilities`	List Vulnerabilities by Device	Retrieve discovered CVEs on a specific device
`listRecommendations`	List Recommendations by Device	Retrieve TVM security recommendations for a device
`listMissingKBs`	List Missing KBs by Device	Retrieve missing security updates for a device
`addOrRemoveTags`	Add or Remove Tag	Add or remove a single tag on a device
`bulkAddOrRemoveTags`	Bulk Add or Remove Tags	Add or remove a tag across up to 500 devices
`findByIP`	Find Devices by IP (15-min window)	Find devices seen with the given IP within 15 minutes of a timestamp
`findByInternalIP`	Find Device by Internal IP	Find a device by internal IP at a specific timestamp
`findByTag`	Find Devices by Tag	Find all devices that have a specific tag

Key parameters for list:

$filter — OData filter (fields: id, computerDnsName, lastSeen, lastIpAddress, healthStatus, onboardingStatus, riskScore, rbacGroupId, rbacGroupName, osPlatform, machineTags)
$top — max devices to return (default: 100, max: 10,000)
$skip — pagination offset
$orderby — sort expression (e.g., lastSeen desc)
healthStatus — shortcut filter: Active, Inactive, ImpairedCommunication, NoSensorData, NoSensorDataImpairedCommunication, Unknown
onboardingStatus — shortcut filter: onboarded, CanBeOnboarded, Unsupported, InsufficientInfo
riskScore — shortcut filter: None, Informational, Low, Medium, High

Key parameters for addOrRemoveTags / bulkAddOrRemoveTags:

id (single) / machineIds (bulk) — device identifier(s)
action — Add or Remove
value — tag name

Machine Action

Trigger and monitor remote response actions on managed endpoints. Every action returns a MachineAction object with a status that can be polled.

Operation	Name	Description
`list`	List Machine Actions	Retrieve history of response actions with OData filtering
`get`	Get Machine Action	Retrieve status and details of a specific action by ID
`isolate`	Isolate Machine	Disconnect a device from the network (Defender traffic preserved)
`unisolate`	Unisolate Machine	Restore full network connectivity to an isolated device
`runAntivirusScan`	Run Antivirus Scan	Initiate a Quick or Full Microsoft Defender Antivirus scan
`collectInvestigationPackage`	Collect Investigation Package	Collect a forensic ZIP package (logs and data) from the device
`restrictCodeExecution`	Restrict Code Execution	Restrict all application execution to Microsoft-signed binaries only
`unrestrictCodeExecution`	Remove Code Execution Restriction	Lift code-execution restriction
`stopAndQuarantineFile`	Stop and Quarantine File	Kill a process and delete a file by SHA1 hash

Common parameters for machine actions:

id (required) — machine ID of the target device
comment (required) — justification comment recorded with the action

Additional parameters for isolate:

isolationType — Full (blocks all traffic), Selective (restricts limited apps), UnManagedDevice

Additional parameters for runAntivirusScan:

scanType (required) — Quick or Full

Additional parameters for stopAndQuarantineFile:

sha1 (required) — SHA1 hash of the file to stop and quarantine

Vulnerability

Query CVE vulnerabilities detected across the organization via Threat and Vulnerability Management.

Operation	Name	Description
`list`	List Vulnerabilities	Retrieve CVEs with OData filtering (max 8,000 per page)
`get`	Get Vulnerability by ID	Retrieve details for a specific CVE
`listMachines`	List Devices by Vulnerability	Retrieve devices affected by a specific CVE
`listByMachineAndSoftware`	List Vulnerabilities by Machine and Software	Retrieve all vulnerabilities grouped by machine and software

Key parameters for list:

$filter — OData filter (fields: id, name, description, cvssV3, publishedOn, severity, updatedOn)
$top — max records (default: 100, max: 8,000)
$skip — pagination offset

Key parameters for listByMachineAndSoftware:

$filter — OData filter (fields: id, cveId, machineId, fixingKbId, productName, productVersion, severity, productVendor)
$top — max records (default: 100, max: 10,000)

Software

Query the software inventory of managed endpoints.

Operation	Name	Description
`list`	List Software	Retrieve the organization's software inventory
`get`	Get Software by ID	Retrieve details of a specific software entry
`listVersionDistribution`	List Software Version Distribution	Retrieve version distribution for a software entry
`listMachines`	List Devices by Software	Retrieve devices that have the software installed
`listVulnerabilities`	List Vulnerabilities by Software	Retrieve vulnerabilities exposed by the software
`listMissingKBs`	List Missing KBs by Software	Retrieve missing security updates for the software

Key parameters for list:

$filter — OData filter (fields: id, name, vendor)
$top — max records (default: 100, max: 10,000)
$skip — pagination offset

Note: Software IDs follow the pattern vendor-_-productname (e.g., microsoft-_-edge).

Recommendation

Query TVM security recommendations for the organization.

Operation	Name	Description
`list`	List Security Recommendations	Retrieve recommendations with OData filtering
`get`	Get Recommendation by ID	Retrieve a specific recommendation
`listMachines`	List Devices by Recommendation	Retrieve devices associated with a recommendation
`listVulnerabilities`	List Vulnerabilities by Recommendation	Retrieve vulnerabilities associated with a recommendation
`listSoftware`	List Software by Recommendation	Retrieve software associated with a recommendation
`listByMachine`	List Recommendations by Device	Retrieve recommendations for a specific device

Key parameters for list:

$filter — OData filter (fields: id, productName, vendor, recommendedVersion, recommendationCategory, subCategory, severityScore, remediationType, status)
$top — max records (default: 100, max: 10,000)

Note: Recommendation IDs follow the pattern va-_-vendor-_-product (e.g., va-_-google-_-chrome).

Remediation Task

Query and update TVM remediation activities created in the Microsoft 365 Defender portal.

Operation	Name	Description
`list`	List Remediation Tasks	Retrieve remediation activities with OData filtering
`get`	Get Remediation Task	Retrieve a specific remediation task
`update`	Update Remediation Task	Update the status of a remediation task
`listMachines`	List Devices by Remediation Task	Retrieve devices associated with a remediation task

Key parameters for list:

$filter — OData filter (fields: createdon, status)
$top — max records (default: 100, max: 10,000)
status — shortcut filter: Active or Completed

Key parameters for update:

id (required) — remediation task ID
updateFields.status — Active, Completed, or Canceled

Indicator

Manage custom threat intelligence indicators (IoCs) in Microsoft Defender for Endpoint.

Operation	Name	Description
`list`	List Indicators	Retrieve indicators with OData filtering and shortcut filters
`create`	Create Indicator	Submit a new IoC indicator
`get`	Get Indicator	Retrieve a specific indicator by ID
`update`	Update Indicator	Update an existing indicator
`delete`	Delete Indicator	Delete an indicator by ID

Key parameters for list:

$filter — OData filter (fields: application, createdByDisplayName, expirationTime, generateAlert, title, indicatorValue, indicatorType, creationTimeDateTimeUtc, createdBy, action, severity)
$top — max records (default: 100, max: 10,000)
indicatorType — shortcut filter: FileSha1, FileSha256, FileMd5, CertificateThumbprint, IpAddress, DomainName, Url
action — shortcut filter: Alert, Warn, Block, Audit, BlockAndRemediate, AlertAndBlock, Allowed
severity — shortcut filter: Informational, Low, Medium, High

Key parameters for create:

indicatorValue (required) — the IoC value (file hash, IP, domain, or URL)
indicatorType (required) — type of indicator
action (required) — action to take on match
title (required) — short title
description (required) — description of the indicator
expirationTime — ISO 8601 expiration (e.g., 2025-12-31T00:00:00Z)
severity — Informational, Low, Medium, High
recommendedActions — free-text recommended actions
rbacGroupNames — array of RBAC group names to scope the indicator
generateAlert — boolean; whether to generate an alert on match
educateUrl — end-user education URL (applicable when action is Warn)

File

Retrieve file metadata and prevalence data using a SHA1 or SHA256 hash.

Operation	Name	Description
`get`	Get File Information	Retrieve file metadata (prevalence, publisher, signer, determination) by hash
`listAlerts`	List Alerts by File	Retrieve alerts related to a file hash (SHA1 only)
`listMachines`	List Machines by File	Retrieve machines that observed the file (SHA1 only)
`getStats`	Get File Statistics	Retrieve prevalence statistics for a file (SHA1 only)

Key parameters:

id (required) — SHA1 or SHA256 hash of the file
lookBackHours (for getStats) — hours to look back (max 720, defaults to 30 days)

IP Address

Retrieve security data for a specific IP address observed by managed endpoints.

Operation	Name	Description
`listAlerts`	List Alerts by IP	Retrieve alerts related to an IP address
`getStats`	Get IP Statistics	Retrieve prevalence statistics for an IP address

Key parameters:

ip (required) — IP address (e.g., 10.209.67.177)
lookBackHours (for getStats) — hours to look back (max 720)

Domain

Retrieve security data for a domain observed by managed endpoints.

Operation	Name	Description
`listAlerts`	List Alerts by Domain	Retrieve alerts related to a domain
`listMachines`	List Machines by Domain	Retrieve machines that communicated with the domain
`getStats`	Get Domain Statistics	Retrieve prevalence statistics for a domain

Key parameters:

domain (required) — domain name (e.g., example.com)
lookBackHours (for getStats) — hours to look back (max 720)

User

Retrieve alerts and related machines for a user account.

Operation	Name	Description
`listAlerts`	List Alerts by User	Retrieve alerts related to a user
`listMachines`	List Machines by User	Retrieve machines related to a user

Key parameters:

id (required) — the username only, not the full UPN (e.g., use jdoe not [email protected])

Score

Retrieve organizational security posture scores from Threat and Vulnerability Management.

Operation	Name	Description
`getExposureScore`	Get Exposure Score	Retrieve the organizational TVM exposure score
`getDeviceSecureScore`	Get Device Secure Score	Retrieve the Microsoft Secure Score for Devices
`listByDeviceGroup`	List Exposure Score by Device Group	Retrieve exposure score broken down by device group

No additional parameters are required for score operations.

Parameter Merging and Templating

The Microsoft Defender for Endpoint integration takes full advantage of NINA's parameter merging and templating capabilities:

Parameter Sources (in order of precedence)

Node Parameters: Parameters configured directly in the MDE Integration Node
Extracted Parameters: Parameters automatically extracted from the input data
Input Data: The complete input data from upstream nodes

When an MDE Integration Node executes:

It combines parameters from all sources
Node parameters take precedence over extracted parameters
Template variables within parameters are processed using {{variable_name}} syntax
The combined parameters are used to execute the MDE operation

OData Filter Shortcuts vs. Raw Filters

Several list operations provide shortcut filter parameters (e.g., severity, status on alert.list) that are automatically converted to OData $filter expressions. When you provide a raw $filter parameter, the shortcut parameters are ignored and the raw filter takes full precedence.

Behavior	When to use
Shortcut filters (`severity`, `status`, etc.)	Simple, single-field filters — no OData syntax needed
Raw `$filter`	Complex expressions with multiple clauses, `or` logic, or functions

Example: Managing Security Alerts

Listing Alerts by Severity and Status

{
  "integration_service": "microsoft-defender-endpoint",
  "resource": "alert",
  "operation": "list",
  "parameters": {
    "severity": "High",
    "status": "New",
    "$top": 50,
    "$orderby": "alertCreationTime desc"
  }
}

Listing Alerts with a Raw OData Filter

{
  "integration_service": "microsoft-defender-endpoint",
  "resource": "alert",
  "operation": "list",
  "parameters": {
    "$filter": "severity eq 'High' and status eq 'New' and alertCreationTime ge 2026-01-01T00:00:00Z",
    "$top": 100,
    "$orderby": "alertCreationTime desc",
    "$expand": "evidence"
  }
}

Getting a Specific Alert

{
  "integration_service": "microsoft-defender-endpoint",
  "resource": "alert",
  "operation": "get",
  "parameters": {
    "alertId": "{{alert_id}}"
  }
}

Updating an Alert Status with Template Variables

Input Data from Previous Node:

{
  "alert_id": "da637773775833477842_-2109939563",
  "analyst": "[email protected]",
  "verdict": "true_positive"
}

Node Configuration:

{
  "integration_service": "microsoft-defender-endpoint",
  "resource": "alert",
  "operation": "update",
  "parameters": {
    "alertId": "{{alert_id}}",
    "updateFields": {
      "status": "Resolved",
      "assignedTo": "{{analyst}}",
      "classification": "TruePositive",
      "determination": "Malware",
      "comment": "Investigated and confirmed as malware — remediation completed by {{analyst}}"
    }
  }
}

Batch Updating Multiple Alerts

{
  "integration_service": "microsoft-defender-endpoint",
  "resource": "alert",
  "operation": "batchUpdate",
  "parameters": {
    "alertIds": ["{{alert_id_1}}", "{{alert_id_2}}", "{{alert_id_3}}"],
    "updateFields": {
      "status": "InProgress",
      "assignedTo": "[email protected]",
      "comment": "Triaged and assigned to SOC for investigation"
    }
  }
}

Example: Device Management

Listing High-Risk Active Devices

{
  "integration_service": "microsoft-defender-endpoint",
  "resource": "machine",
  "operation": "list",
  "parameters": {
    "healthStatus": "Active",
    "riskScore": "High",
    "$top": 200,
    "$orderby": "lastSeen desc"
  }
}

Finding a Device by Internal IP

Input Data:

{
  "suspicious_ip": "10.10.5.42",
  "event_timestamp": "2026-05-10T14:30:00Z"
}

Node Configuration:

{
  "integration_service": "microsoft-defender-endpoint",
  "resource": "machine",
  "operation": "findByIP",
  "parameters": {
    "ip": "{{suspicious_ip}}",
    "timestamp": "{{event_timestamp}}"
  }
}

Adding a Tag to a Device

{
  "integration_service": "microsoft-defender-endpoint",
  "resource": "machine",
  "operation": "addOrRemoveTags",
  "parameters": {
    "id": "{{machine_id}}",
    "action": "Add",
    "value": "incident-2026-042"
  }
}

Bulk Tagging Multiple Devices

{
  "integration_service": "microsoft-defender-endpoint",
  "resource": "machine",
  "operation": "bulkAddOrRemoveTags",
  "parameters": {
    "machineIds": ["{{machine_id_1}}", "{{machine_id_2}}", "{{machine_id_3}}"],
    "action": "Add",
    "value": "quarantine-candidate"
  }
}

Example: Endpoint Response Actions

Isolating a Compromised Device

Input Data:

{
  "machine_id": "4a5f3a3b2c1d0e9f8a7b6c5d4e3f2a1b",
  "incident_id": "INC-2026-0042",
  "analyst": "[email protected]"
}

Node Configuration:

{
  "integration_service": "microsoft-defender-endpoint",
  "resource": "machineAction",
  "operation": "isolate",
  "parameters": {
    "id": "{{machine_id}}",
    "comment": "Isolating device as part of incident {{incident_id}} investigation — authorized by {{analyst}}",
    "isolationType": "Full"
  }
}

Running an Antivirus Scan

{
  "integration_service": "microsoft-defender-endpoint",
  "resource": "machineAction",
  "operation": "runAntivirusScan",
  "parameters": {
    "id": "{{machine_id}}",
    "comment": "Full AV scan triggered as part of malware investigation",
    "scanType": "Full"
  }
}

Collecting a Forensic Investigation Package

{
  "integration_service": "microsoft-defender-endpoint",
  "resource": "machineAction",
  "operation": "collectInvestigationPackage",
  "parameters": {
    "id": "{{machine_id}}",
    "comment": "Collecting forensic package for incident {{incident_id}} evidence"
  }
}

Stopping and Quarantining a Malicious File

{
  "integration_service": "microsoft-defender-endpoint",
  "resource": "machineAction",
  "operation": "stopAndQuarantineFile",
  "parameters": {
    "id": "{{machine_id}}",
    "comment": "Stopping and quarantining confirmed malware identified in threat intel feed",
    "sha1": "{{malware_sha1}}"
  }
}

Polling a Machine Action Status

After triggering a machine action, poll its status using the returned action ID:

{
  "integration_service": "microsoft-defender-endpoint",
  "resource": "machineAction",
  "operation": "get",
  "parameters": {
    "id": "{{machine_action_id}}"
  }
}

Example: Threat Intelligence Indicators

Creating a Malicious Domain Indicator

{
  "integration_service": "microsoft-defender-endpoint",
  "resource": "indicator",
  "operation": "create",
  "parameters": {
    "indicatorValue": "malicious-c2.example.com",
    "indicatorType": "DomainName",
    "action": "Block",
    "title": "APT29 C2 Domain",
    "description": "Command-and-control domain attributed to APT29 campaign",
    "severity": "High",
    "expirationTime": "2026-12-31T00:00:00Z",
    "recommendedActions": "Block all network traffic to this domain and investigate any prior connections",
    "generateAlert": true
  }
}

Creating a File Hash Indicator with Dynamic Input

Input Data:

{
  "file_sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
  "malware_family": "TrickBot",
  "threat_actor": "TA505",
  "expiry": "2026-06-30T00:00:00Z"
}

Node Configuration:

{
  "integration_service": "microsoft-defender-endpoint",
  "resource": "indicator",
  "operation": "create",
  "parameters": {
    "indicatorValue": "{{file_sha256}}",
    "indicatorType": "FileSha256",
    "action": "BlockAndRemediate",
    "title": "{{malware_family}} malware — {{threat_actor}}",
    "description": "Confirmed {{malware_family}} sample attributed to {{threat_actor}}",
    "severity": "High",
    "expirationTime": "{{expiry}}",
    "recommendedActions": "Block and quarantine the file; investigate systems with prior execution",
    "generateAlert": true
  }
}

Listing Active Block Indicators

{
  "integration_service": "microsoft-defender-endpoint",
  "resource": "indicator",
  "operation": "list",
  "parameters": {
    "action": "Block",
    "$top": 200,
    "$orderby": "creationTimeDateTimeUtc desc"
  }
}

Example: Vulnerability and TVM Queries

Listing High-Severity CVEs

{
  "integration_service": "microsoft-defender-endpoint",
  "resource": "vulnerability",
  "operation": "list",
  "parameters": {
    "$filter": "severity eq 'High'",
    "$top": 200,
    "$orderby": "cvssV3 desc"
  }
}

Finding All Devices Affected by a CVE

{
  "integration_service": "microsoft-defender-endpoint",
  "resource": "vulnerability",
  "operation": "listMachines",
  "parameters": {
    "cveId": "{{cve_id}}"
  }
}

Getting the Organization Exposure Score

{
  "integration_service": "microsoft-defender-endpoint",
  "resource": "score",
  "operation": "getExposureScore",
  "parameters": {}
}

Listing Active Security Recommendations

{
  "integration_service": "microsoft-defender-endpoint",
  "resource": "recommendation",
  "operation": "list",
  "parameters": {
    "$filter": "status eq 'Active'",
    "$top": 100,
    "$orderby": "severityScore desc"
  }
}

Marking a Remediation Task as Completed

{
  "integration_service": "microsoft-defender-endpoint",
  "resource": "remediationTask",
  "operation": "update",
  "parameters": {
    "id": "{{task_id}}",
    "updateFields": {
      "status": "Completed"
    }
  }
}

Example: File, IP, and Domain Investigation

Investigating a Suspicious File Hash

{
  "integration_service": "microsoft-defender-endpoint",
  "resource": "file",
  "operation": "get",
  "parameters": {
    "id": "{{file_sha256}}"
  }
}

Getting Alerts for a Suspicious IP

{
  "integration_service": "microsoft-defender-endpoint",
  "resource": "ip",
  "operation": "listAlerts",
  "parameters": {
    "ip": "{{suspicious_ip}}"
  }
}

Getting Alerts and Machines for a Suspicious Domain

{
  "integration_service": "microsoft-defender-endpoint",
  "resource": "domain",
  "operation": "listAlerts",
  "parameters": {
    "domain": "{{suspicious_domain}}"
  }
}

{
  "integration_service": "microsoft-defender-endpoint",
  "resource": "domain",
  "operation": "listMachines",
  "parameters": {
    "domain": "{{suspicious_domain}}"
  }
}

Alert Field Reference

Alert Status Values

Value	Description
`New`	Newly detected alert not yet reviewed
`InProgress`	Alert is actively being investigated
`Resolved`	Alert investigation completed

Alert Classification Values

Value	Label
`TruePositive`	True Positive
`InformationalExpectedActivity`	Informational / Expected Activity
`FalsePositive`	False Positive

Alert Determination Values

Value	Label
`MultiStagedAttack`	Multistage Attack
`MaliciousUserActivity`	Malicious User Activity
`CompromisedUser`	Compromised Account
`Malware`	Malware
`Phishing`	Phishing
`UnwantedSoftware`	Unwanted Software
`Other`	Other
`SecurityTesting`	Security Test
`LineOfBusinessApplication`	Line-of-Business Application
`ConfirmedActivity`	Confirmed Activity
`NotMalicious`	Not Malicious
`InsufficientData`	Not Enough Data to Validate

Note: Determination must be consistent with the chosen classification. For example, Malware and Phishing are only valid determinations for TruePositive alerts.

Indicator Action Values

Value	Description
`Alert`	Generate an alert when matched
`Warn`	Warn the end user and allow them to bypass
`Block`	Block the action
`Audit`	Log the event without blocking
`BlockAndRemediate`	Block and automatically remediate
`AlertAndBlock`	Generate an alert and block
`Allowed`	Explicitly allow the indicator

Common Workflow Patterns

Incident Response — Device Isolation

alert.list — retrieve new high-severity alerts
alert.get — retrieve evidence and machine details from the alert
machine.list — verify device health and risk score
machineAction.isolate — isolate the device from the network
machineAction.collectInvestigationPackage — collect forensic data
alert.update — assign alert to analyst and set status to InProgress
machineAction.get — poll until isolation action status is Succeeded

Threat Intelligence Enrichment

Receive a suspicious indicator (IP, domain, file hash) from an upstream node
ip.listAlerts / domain.listAlerts / file.listAlerts — check existing alerts
ip.getStats / domain.getStats / file.getStats — retrieve prevalence statistics
machine.list / file.listMachines / domain.listMachines — identify affected devices
indicator.create — create a blocking IoC if confirmed malicious
alert.update — update related alerts with investigation findings

Vulnerability Prioritization

score.getExposureScore — check current organizational exposure
vulnerability.list with $filter: severity eq 'High' — enumerate high-severity CVEs
vulnerability.listMachines — per CVE, identify affected devices
recommendation.list — retrieve actionable TVM recommendations
remediationTask.list — check existing remediation activities

Automated Alert Triage

alert.list with status=New and severity=High — retrieve new high-priority alerts
file.get / ip.listAlerts / domain.listAlerts — enrich alert IOCs
Based on enrichment outcome, alert.batchUpdate — bulk-classify and assign alerts

Troubleshooting

Issue	Resolution
`Azure AD token error [invalid_client]`	Verify that Client ID and Client Secret are correct and that the secret has not expired
`Azure AD token error [unauthorized_client]`	Confirm that the app registration exists in the correct tenant and that application (not delegated) permissions are configured
`MDE API error [Forbidden]`	Ensure the required API permissions are configured and admin consent has been granted in Azure portal
`MDE API error [NotFound]` for alerts or machines	Verify the ID is correct and that the service principal has access to the relevant RBAC device groups
OData filter syntax errors	Use single quotes around string values (e.g., `severity eq 'High'`). Check supported field names for each resource — not all OData fields are filterable on all resources
Shortcut filter ignored	If you provide both a shortcut filter (e.g., `severity`) and a raw `$filter`, the shortcut is ignored. Use one or the other
Machine action stuck in `Pending`	Check the device's online/health status in the MDE portal. Actions cannot be delivered to offline or isolated devices without active Defender connectivity
`id is required` on machine actions	Machine action operations require the machine ID (`id`), not the hostname or IP address. Use `machine.list` to look up the ID
Rate limit errors (HTTP 429)	The integration retries automatically up to 3 times with exponential back-off (1 s, 2 s, 4 s). For `batchUpdate`, the limit is 10 calls/min and 500 calls/hr
Empty body (success: true)	Some operations return HTTP 204 with no body (e.g., `indicator.delete`). The integration returns `{"success": true}` in these cases
User ID format errors	The `user` resource requires the username only (e.g., `jdoe`), not the full UPN (`[email protected]`)
Token expiry issues	The integration caches tokens and refreshes them automatically with a 60-second safety buffer. Recreate the credential if persistent auth errors occur
Software ID not found	Software IDs follow the `vendor-_-productname` convention (e.g., `microsoft-_-edge`). Use `software.list` with a `$filter` to find the correct ID

Best Practices

Grant minimum required permissions: Request only the API permissions needed for your workflow. Read-only workflows should use *.Read.All permissions only and omit *.ReadWrite.All.
Rotate client secrets regularly: Azure App Registration client secrets expire. Set calendar reminders before expiry and update the NINA credential before the secret expires to avoid workflow failures.
Use shortcut filters for simple queries: The severity, status, healthStatus, and similar shortcut parameters are easier to configure than raw OData and are combined automatically with and. Switch to raw $filter only when you need or logic or unsupported fields.
Leverage $expand=evidence selectively: Including evidence inline in alert list calls increases response size. Use it only when you need evidence data, or fetch it separately with alert.get.
Always record a comment for machine actions: The comment parameter is required by the MDE API for all machine actions and is stored in the action audit trail. Write meaningful comments that reference incident IDs for traceability.
Poll machine actions to verify completion: Machine actions are asynchronous — they return a MachineAction object with a Pending or InProgress status immediately. Build polling logic using machineAction.get before assuming the action completed.
Set expiration times on indicators: IoC indicators without an expiration time remain active indefinitely. Set expirationTime based on your threat intelligence confidence window and implement cleanup workflows for expired indicators.
Use bulk operations where possible: batchUpdate for alerts and bulkAddOrRemoveTags for machines reduce API calls compared to per-item operations. Be mindful of rate limits (10 calls/min for batch alert updates).
Paginate large result sets: Most list operations default to 100 records. Use $top and $skip to page through large datasets. For vulnerability.list the maximum is 8,000 records per page; for most other list operations it is 10,000.
Scope indicators with RBAC groups: Use rbacGroupNames on indicator creation to limit the indicator's enforcement scope to specific device groups, avoiding unintended blocking across the organization.
Monitor exposure scores proactively: Include score.getExposureScore and score.getDeviceSecureScore in regular reporting workflows to track the organization's security posture trend over time.
Handle 204 No Content responses: Operations like indicator.delete return no body. The integration normalizes this to {"success": true} — check for this key in downstream nodes instead of parsing a full response object.
Use template variables for dynamic workflows: Use {{variable_name}} syntax to pass alert IDs, machine IDs, and other values from upstream nodes dynamically, avoiding hardcoded identifiers in node configurations.
Test credentials before production use: Use the Test Connection button when creating credentials. It acquires an OAuth token from Azure AD and fails fast if the tenant, client ID, or secret are incorrect — before any workflow runs.

Security Considerations

Protect client secrets: Store credentials exclusively through NINA's credential manager. Never include Client IDs or secrets in workflow parameters, logs, or comments.
Use dedicated service accounts: Register a dedicated Azure App for this integration rather than reusing credentials across multiple systems. This limits the blast radius if credentials are compromised.
Restrict RBAC device group access: In the MDE portal, you can limit which device groups the API service principal has access to. Restrict access to only the device groups relevant to your automation workflows.
Audit machine action usage: Machine actions (isolation, file quarantine, code restriction) have direct operational impact. Implement workflow-level approval gates and log all actions for audit purposes.
Review indicator lifecycles: Regularly audit active IoC indicators (indicator.list) to remove stale or incorrect entries. A misconfigured block indicator can disrupt legitimate business traffic.

Updated: 2026-05-11

Overview​

Status​

Credential Configuration​

Authentication Method​

OAuth2 Client Credentials​

Sovereign Cloud Environments​

Creating a Microsoft Defender for Endpoint Credential​

Supported Resources and Operations​

Alert​

Machine (Device)​

Machine Action​

Vulnerability​

Software​

Recommendation​

Remediation Task​

Indicator​

File​

IP Address​

Domain​

User​

Score​

Parameter Merging and Templating​

Parameter Sources (in order of precedence)​

OData Filter Shortcuts vs. Raw Filters​

Example: Managing Security Alerts​

Listing Alerts by Severity and Status​

Listing Alerts with a Raw OData Filter​

Getting a Specific Alert​

Updating an Alert Status with Template Variables​

Input Data from Previous Node:​

Node Configuration:​

Batch Updating Multiple Alerts​

Example: Device Management​

Listing High-Risk Active Devices​

Finding a Device by Internal IP​

Input Data:​

Node Configuration:​

Adding a Tag to a Device​

Bulk Tagging Multiple Devices​

Example: Endpoint Response Actions​

Isolating a Compromised Device​

Input Data:​

Node Configuration:​

Running an Antivirus Scan​

Collecting a Forensic Investigation Package​

Stopping and Quarantining a Malicious File​

Polling a Machine Action Status​

Example: Threat Intelligence Indicators​

Creating a Malicious Domain Indicator​

Creating a File Hash Indicator with Dynamic Input​

Input Data:​

Node Configuration:​

Listing Active Block Indicators​

Example: Vulnerability and TVM Queries​

Listing High-Severity CVEs​

Finding All Devices Affected by a CVE​

Getting the Organization Exposure Score​

Listing Active Security Recommendations​

Marking a Remediation Task as Completed​

Example: File, IP, and Domain Investigation​

Investigating a Suspicious File Hash​

Getting Alerts for a Suspicious IP​

Getting Alerts and Machines for a Suspicious Domain​

Alert Field Reference​

Alert Status Values​

Alert Classification Values​

Alert Determination Values​

Indicator Action Values​

Common Workflow Patterns​

Incident Response — Device Isolation​

Threat Intelligence Enrichment​

Vulnerability Prioritization​

Automated Alert Triage​

Troubleshooting​

Best Practices​

Security Considerations​

Overview

Status

Credential Configuration

Authentication Method

OAuth2 Client Credentials

Sovereign Cloud Environments

Creating a Microsoft Defender for Endpoint Credential

Supported Resources and Operations

Alert

Machine (Device)

Machine Action

Vulnerability

Software

Recommendation

Remediation Task

Indicator

File

IP Address

Domain

User

Score

Parameter Merging and Templating

Parameter Sources (in order of precedence)

OData Filter Shortcuts vs. Raw Filters

Example: Managing Security Alerts

Listing Alerts by Severity and Status

Listing Alerts with a Raw OData Filter

Getting a Specific Alert

Updating an Alert Status with Template Variables

Input Data from Previous Node:

Node Configuration:

Batch Updating Multiple Alerts

Example: Device Management

Listing High-Risk Active Devices

Finding a Device by Internal IP

Input Data:

Node Configuration:

Adding a Tag to a Device

Bulk Tagging Multiple Devices

Example: Endpoint Response Actions

Isolating a Compromised Device

Input Data:

Node Configuration:

Running an Antivirus Scan

Collecting a Forensic Investigation Package

Stopping and Quarantining a Malicious File

Polling a Machine Action Status

Example: Threat Intelligence Indicators

Creating a Malicious Domain Indicator

Creating a File Hash Indicator with Dynamic Input

Input Data:

Node Configuration:

Listing Active Block Indicators

Example: Vulnerability and TVM Queries

Listing High-Severity CVEs

Finding All Devices Affected by a CVE

Getting the Organization Exposure Score

Listing Active Security Recommendations

Marking a Remediation Task as Completed

Example: File, IP, and Domain Investigation

Investigating a Suspicious File Hash

Getting Alerts for a Suspicious IP

Getting Alerts and Machines for a Suspicious Domain

Alert Field Reference

Alert Status Values

Alert Classification Values

Alert Determination Values

Indicator Action Values

Common Workflow Patterns

Incident Response — Device Isolation

Threat Intelligence Enrichment

Vulnerability Prioritization

Automated Alert Triage

Troubleshooting

Best Practices

Security Considerations