Microsoft Defender XDR
Hunting and detection

Best practices for graph mapping in advanced hunting - Microsoft Defender XDR | Microsoft Learn

In brief

Microsoft added guidance on preparing query results and mapping entities, identifiers, labels, relationships, and enrichment in Defender XDR graph visualizations.

What Defender admins need to know

Administrators can use the guidance to create clearer, enriched graphs; no action is required.

Summaries are generated from the documentation change itself.

Documentation change

The comparison below shows only the changed extract. Use the full-page view for complete context.

new file mode 100644

layout: Conceptual title: Best practices for graph mapping in advanced hunting - Microsoft Defender XDR | Microsoft Learn canonicalUrl: https://learn.microsoft.com/en-us/defender-xdr/advanced-hunting-graph-mapping-best-practices breadcrumb_path: /defender-xdr/breadcrumb/toc.json permissioned-type: public feedback_system: Standard feedback_product_url: https://techcommunity.microsoft.com/t5/microsoft-365-defender/bd-p/MicrosoftThreatProtection uhfHeaderId: MSDocsHeader-MicrosoftDefender manager: orspodek description: Learn how to prepare advanced hunting query results and map them to nodes and edges to build a readable, well-enriched graph in Microsoft Defender. ms.service: defender-xdr ms.subservice: adv-hunting ms.author: pauloliveria author: poliveria ms.localizationpriority: medium ms.collection:


Best practices for graph mapping in advanced hunting - Microsoft Defender XDR | Microsoft Learn

Important

Some information in this article relates to a prereleased product which may be substantially modified before it's commercially released. Microsoft makes no warranties, expressed or implied, with respect to the information provided here.

Learn how to turn advanced hunting query results into enriched nodes and meaningful relationships when you visualize query results as a graph.

Tip

Key idea: The visual builder generates the mapping automatically. Focus on selecting result columns that identify each entity, label it clearly, and explain its relationships.

Prepare the query results

Design the final query output before opening the mapping builder. It should provide the following information:

  • A strong, stable identifier for every entity, such as DeviceId, SHA256, AlertId, or AccountObjectId.
  • An optional friendly label, such as DeviceName, that makes the graph easy to read.
  • Any additional identifiers or context you want available when inspecting a node.
  • Relationship-specific details, such as RemotePort or InitiatingProcessFileName.

For every relationship, the source and target identifiers must appear in the same result row. Every column selected in the builder must exist in the final query output and contain the expected values.

Create the nodes in the builder

Add a node for each entity represented in the query results, then configure these fields:

Builder fieldWhat to select
Type nameA recognized entity name when you want Defender enrichment. Other names are allowed, but they render as generic nodes.
Node identifier columnThe strongest column that uniquely identifies the entity. Defender also uses this value to look up enrichment data.
Display name columnAn optional human-readable label. Use it for presentation only, not as a substitute for a strong identifier.
Additional columnsOther useful identifiers and entity context. These values are displayed when the node is inspected.

Note

Entity enrichment: When a node uses a supported type and a valid identifier, selecting it in the graph opens the corresponding Defender entity pane.

Recognized entity types and identifiers

Type name(s)Preferred node identifier
Device, MachineDeviceId (Sense device ID)
IPAddress, IP, RemoteIP, LocalIPThe corresponding IP address column
FileSHA256; otherwise SHA1
UrlURL
AlertAlertId
HostHostname
User, AccountAccountObjectId; otherwise AccountSid, then AccountUpn

Tip

When multiple identifiers are available, use the preferred one as the node identifier and include the others under Additional columns.

Connect the nodes with edges

After creating the nodes, add an edge for each relationship and configure these fields:

Builder fieldWhat to select
Relationship labelA short, meaningful description such as ConnectedTo, Downloaded, or Triggered.
Source nodeThe entity where the relationship starts.
Target nodeThe entity where the relationship ends.
Additional columnsContext that describes the relationship rather than either entity.
ConditionAn optional rule that determines whether the edge is created for each result row.

The source and target must reference nodes already created in the builder. Choose the direction deliberately so the graph reads naturally, and keep relationship details on the edge instead of duplicating them on both nodes.

Add a condition when the relationship is conditional

Each edge supports one optional condition. For every result row, the edge is created only when that condition is true.

  1. Column—select the query-result column to evaluate.
  2. Operator—choose equals, not equals, contains, not empty, or is empty.
  3. Value—enter the comparison value for equals, not equals, and contains. No value is used with not empty or is empty.
OperatorValue required?Use it when...
equalsYesThe column must match the supplied value.
not equalsYesThe column must differ from the supplied value.
containsYesThe column must contain the supplied value.
not emptyNoThe column must contain a value.
is emptyNoThe column must not contain a value.

Tip

Example: Set the condition to RemoteIPnot empty to create ConnectedTo edges only for rows that contain a remote IP address.

If the decision requires several checks, create one derived column in the query and apply the edge condition to that column.

Worked example: device communicating with an IP address

Assume the query returns DeviceId, DeviceName, RemoteIP, RemotePort, and InitiatingProcessFileName.

Builder itemConfiguration
Machine nodeType: Machine; Identifier: DeviceId; Display name: DeviceName
IP nodeType: IP; Identifier: RemoteIP; Display name: RemoteIP
ConnectedTo edgeSource: Machine; Target: IP; Additional columns: RemotePort, InitiatingProcessFileName; Condition: RemoteIP not empty

This mapping produces readable device-to-IP connections, enables entity enrichment, and keeps the connection details attached to the relationship.

Final checklist

  • Use a recognized type name when an enriched entity pane is expected.
  • Select the strongest available identifier and follow the documented precedence.
  • Keep the display name readable, but do not rely on it for identity.
  • Confirm every selected column is returned and populated by the query.
  • Keep node columns entity-specific and edge columns relationship-specific.
  • Make sure every edge points between existing nodes in the intended direction.
  • For a conditional edge, verify that its column, operator, and required value describe exactly when the relationship should exist.
  • Render the graph and select each supported node to confirm that the expected Defender entity pane opens. \ No newline at end of file