Connect Microsoft Defender for Endpoint

Imports security alerts, incidents, monitored machines, the vulnerabilities present on each device, each device's compliance with the secure configurations, installed software, recommendations, and security scores from your Microsoft 365 Defender tenant.

For the general flow of adding a source, see Connect Data Sources.

Before you start

To configure the data source, you can use your M365 interface or use the full PowerShell script that we provide.

Prerequisites

• Active Microsoft Defender for Endpoint Plan 1 or Plan 2 license

• Access to the Azure portal with Global Administrator or Privileged Role Administrator role — an Application Administrator can create the App Registration but cannot grant admin consent to Microsoft Graph application permissions

Setup

Step 1 — Create an App Registration

1. Sign in to portal.azure.com

2. Search for App registrations → New registration

3. Fill in:

Click Register, then note the Application (client) ID and Directory (tenant) ID.

Step 2 — Configure API permissions

Collected data comes from three distinct APIs, each requiring its own permissions.

2a — WindowsDefenderATP API

API permissions → Add a permission → APIs my organization uses → WindowsDefenderATP → Application permissions

2b — Microsoft Threat Protection API

Add a permission → APIs my organization uses → Microsoft Threat Protection → Application permissions

2c — Microsoft Graph API

Add a permission → Microsoft Graph → Application permissions

⚠️ Click Grant admin consent to validate all permissions.

Step 3 — Create a Client Secret

1. Left menu: Certificates & secrets

2. Client secrets tab → New client secret

3. Enter a description and choose an expiration period

4. Click Add

5. Copy the value immediately — it is only shown once

Step 4 — Configure the connector in HARVEN

HARVEN → Workspace → Data Sources → Add → Defender for Endpoint, then fill in the Tenant ID, Client ID, and Client secret.

Fields to fill in HARVEN

Collected data

• alerts — Security alerts: Identification (alert_id, title, severity, status, classification), Context (description, category, threat_family_name, machine_id, mitre_techniques), Tracking (created_datetime, last_update_datetime, assigned_to, detection_source), Analysis (evidence_count, determination)

• incidents — Security incidents: Identification (incident_id, display_name, severity, classification), Tracking (status, created_datetime, last_update_datetime, assigned_to), Detail (alert_count, tags)

• machines — Monitored machines: Identification (machine_id, computer_dns_name, os_platform, os_version), Posture (health_status, risk_score, exposure_level, onboarding_status), Detail (ip_addresses, is_aad_joined, agent_version, defender_av_status, tags), Activity (last_seen, first_seen)

• machine_vulnerabilities — Vulnerabilities present on each device: Identification (device_id, device_name, cve_id, severity, cvss_score), Exposure (software_name, software_version, exploitability_level, first_seen, security_update_available)

• secure_configuration — Compliance of each device with each secure configuration (firewall, Secure Boot, BitLocker, antivirus…): Identification (machine_id, computer_dns_name, os_platform, configuration_id, configuration_name), Compliance (is_compliant, configuration_impact, last_seen)

• software — Installed software: Inventory (software_id, software_name, software_vendor, software_version), Risk (weaknesses_count, exposed_machines, end_of_support_status)

• recommendations — Security recommendations: Identification (recommendation_id, recommendation_name, recommendation_category), Priority (severity, exposed_machines, impact_score, status, remediation_type)

• secure_scores — Security score: Score (current_score, max_score, enabled_services), Context (created_datetime, licensed_user_count, active_user_count)

• investigations — Automated investigations

• machine_actions — Remediation actions

• files — File hash reputation, looked up for the hash given in a file_hash equality filter; without one the table returns no rows

• indicators — Threat indicators (IOC)

Existing data sources

A data source connected before a table was added gets it when you click Refresh tables on that data source.

PowerShell script

Create the App Registration, assign the permissions and generate the secret in one command, with our PowerShell script.

Download the script

How to run it:

Windows — Right-click the file, Run with PowerShell — or in a terminal:

powershell -ExecutionPolicy Bypass -File .\setup-microsoft-connector.ps1

macOS / Linux — Install PowerShell 7 then run the script:

brew install powershell
pwsh ./setup-microsoft-connector.ps1

Arguments (optional) — Without any argument, the script is fully interactive.

• -Connector <entraid|intune|defender|mdca|azure> — Connector to configure. Omitted: the script asks in a menu.

• -AppName <name> — Name of the App Registration to create (default: HARVEN-<connector>).

• -SubscriptionId <id> — Required for azure: target subscription for the Reader role.

• -IncludeEntraIdWrite — entraid only: adds the remediation permission User.EnableDisableAccount.All.

• -Yes — Non-interactive: skips confirmations and installs missing modules automatically.

The script offers to install the missing modules automatically.

Official documentation

• Defender for Endpoint API

• App Registration for Defender

Need help? Contact [email protected].