Skip to main content
Version: 0.10

Windows Defender (WIP)

Pulls the machine list from Microsoft Defender for Endpoint, including Defender's own risk and exposure assessment of each host.

Type namewindows_defender
CreatesEndpoints
Runs onA sensor with outbound reach to api.securitycenter.microsoft.com
Presence flagdefender_exits
Field prefixdefender_

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_ip is 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.
  • mac gets 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.

Stale machines are skipped

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.

Exposure level is Defender's opinion, not the platform's

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​

FromToProtocolPort
The sensor running the integrationlogin.microsoftonline.com — the token endpointHTTPS over TCP443
The sensor running the integrationapi.securitycenter.microsoft.com — the machine listHTTPS over TCP443

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​

NeedWhy
An account that can register applicationsThe credential is an app registration with a client secret
An account that can grant tenant-wide admin consentMachine.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 readThe API returns what Defender knows; a tenant without onboarded machines authenticates fine and returns nothing

In this deployment​

NeedWhy
A registered, healthy sensorThe 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​

FieldRequiredNotes
NameYesLabel for this instance
Application (client) IDYesApp registration client ID
Directory (tenant) IDYesEntra tenant ID
Client SecretNoRequired 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 StatusNoOne 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 settingsNohttp://host:port
SensorYesSensor that will run the integration
Ignore SSLYesNot 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.

TODO

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.

Use the onboarding-status exclusion deliberately

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:

APIPermissionType
WindowsDefenderATPMachine.Read.AllApplication

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.

Client secrets expire

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:

  1. Defender machine ID
  2. Computer DNS name, as both the Defender DNS name and a host name
  3. Defender DNS name alone
  4. Host name together with the OS vendor
  5. Host name alone
  6. 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​