Windows Defender (WIP)
Pulls the machine list from Microsoft Defender for Endpoint, including Defender's own risk and exposure assessment of each host.
| Type name | windows_defender |
| Creates | Endpoints |
| Runs on | A sensor with outbound reach to api.securitycenter.microsoft.com |
| Presence flag | defender_exits |
| Field prefix | defender_ |
What it contributes
- Identity — machine ID, computer DNS name, Entra device ID, Entra-joined flag
- Network — last IP address, last external IP address
- Platform — OS platform, version, build, processor, architecture
- Agent and health — agent version, health status, Defender AV status, onboarding status, managed by and managed-by status
- Risk posture — risk score, exposure level, device value
- Grouping — RBAC group ID and name, machine tags
- Cloud context — VM metadata VM ID and resource ID
- Deduplication signals — merged-into machine ID, potential-duplication flag, excluded flag and exclusion reason
- Lifecycle: Defender's first seen and last seen
It writes the shared fields names (with fqdn and domains from the computer
DNS name), os, os_vendor, type, private_ip, mac and updated_at:
private_ipis the last IP address only when it is a private address that does not belong to a virtual interface, such as a Docker, VPN or Mobile Hotspot adapter. Otherwise the asset's Private IP is left as it is.macgets the MAC of every network interface Defender reports, including interfaces that are down, added to the MACs other sources wrote rather than replacing them. Placeholder addresses that many machines share are never written.
Defender's last seen is the sighting it reports for last_seen, and Defender's
first seen is its first_seen.
A machine whose last seen is missing or older than the template's Ignore of host is offline window is dropped, as is a machine whose onboarding status is excluded on the instance.
defender_risk_score and defender_exposure_level are carried over verbatim.
They are useful for prioritisation and for reconciling two tools' views, but they
are not Velum Edge findings — see Scanning for those.
Requirements
The integration is outbound-only: it is a scheduled Defender API client, so nothing is installed in the tenant, nothing is deployed to the endpoints, and nothing has to reach into the deployment.
Network access
| From | To | Protocol | Port |
|---|---|---|---|
| The sensor running the integration | login.microsoftonline.com — the token endpoint | HTTPS over TCP | 443 |
| The sensor running the integration | api.securitycenter.microsoft.com — the machine list | HTTPS over TCP | 443 |
Two hosts, because authentication and data live in different services: the run
takes a client-credentials token from the first for the
https://api.securitycenter.microsoft.com/.default scope, then pages
/api/machines from the second, 100 machines a page with a 30-second pause between
pages. If the sensor reaches the internet through a
proxy, point Proxy settings at it rather than opening direct egress.
Access in Entra ID
| Need | Why |
|---|---|
| An account that can register applications | The credential is an app registration with a client secret |
| An account that can grant tenant-wide admin consent | Machine.Read.All is an application permission on the WindowsDefenderATP API and is inert until consented — see Permissions in Entra ID |
| A Defender for Endpoint deployment to read | The API returns what Defender knows; a tenant without onboarded machines authenticates fine and returns nothing |
In this deployment
| Need | Why |
|---|---|
| A registered, healthy sensor | The integration runs on a sensor, on the platform's schedule — see Sensors |
There are no special host requirements beyond a sensor that is checking in. The work is a paged HTTPS read per run, so it adds no meaningful load and needs no local storage.
Configuration
| Field | Required | Notes |
|---|---|---|
| Name | Yes | Label for this instance |
| Application (client) ID | Yes | App registration client ID |
| Directory (tenant) ID | Yes | Entra tenant ID |
| Client Secret | No | Required in practice for client-credentials auth. Write-only: once saved, the console shows a locked box with Replace and Remove, and never displays it again |
| Exclude Onboarding Status | No | One of Onboarded, InsufficientInfo, CanBeOnboarded, Unsupported, or None. Machines with that status are dropped. The console offers a single choice, although the setting is meant to take several |
| Proxy settings | No | http://host:port |
| Sensor | Yes | Sensor that will run the integration |
| Ignore SSL | Yes | Not used: the sensor always validates Microsoft's certificates |
The scan template adds Virtual interface ranges under advanced settings: a comma-separated list of addresses or CIDRs, such as a VPN pool or a pod network, that are never taken for a machine's Private IP. Common Docker, VPN and cluster ranges are excluded without being listed.
Confirm that a run imports machines when Exclude Onboarding Status was saved from the current console. The console stores one status, or nothing for None, while the platform reads the setting as a list of statuses.
Defender returns machines it merely knows about alongside those it protects.
Excluding CanBeOnboarded and Unsupported gives you a clean list of protected
endpoints; leaving them in gives you a coverage-gap report instead. Both are
legitimate — pick the one matching what this instance is for, and consider
running two instances if you want both. The console lets you exclude one status
per instance today.
Permissions in Entra ID
Register an application, add an application permission on the WindowsDefenderATP API, and grant admin consent:
| API | Permission | Type |
|---|---|---|
| WindowsDefenderATP | Machine.Read.All | Application |
The integration authenticates against
https://login.microsoftonline.com/{tenant}/oauth2/v2.0/token with the
https://api.securitycenter.microsoft.com/.default scope, then pages
/api/machines. That listing is the only call it makes.
Test connection takes a token and reads one machine from the same listing, so a
missing admin consent for Machine.Read.All shows up there rather than on the
first scheduled run.
An app-registration secret has a maximum lifetime. Note its expiry when you create it — an expired secret shows up as an integration that simply stops refreshing, which is easy to miss.
Matching
Each machine is matched to an existing endpoint by the first rule that finds one:
- Defender machine ID
- Computer DNS name, as both the Defender DNS name and a host name
- Defender DNS name alone
- Host name together with the OS vendor
- Host name alone
- The short host name (the DNS name up to the first dot), when it is at least three characters long
A machine that matches nothing creates a new endpoint, subject to the template's On New Asset Discovered action.
See also
- Azure managed devices — device objects from Entra ID, a different and complementary view
- Integrations overview — the shared configuration model