Lesson 25 — Entity Mapping in Analytics Rules
Your KQL has found a suspicious sign-in. It contains a user account and an IP address.
But unless Microsoft Sentinel understands what those fields represent, they are still just columns in a query result.
Entity mapping turns those fields into investigation-ready objects that Sentinel can correlate, display and use throughout alerts, incidents and response workflows.
What you will learn
Learn how analytics rules map query output into entities that Microsoft Sentinel can recognise and investigate.
Learning objectives
After completing this lesson, you should understand how entity mapping enriches analytics rule output.
- Explain why entity mapping matters during investigation.
- Map query columns to supported entity types.
- Understand entity identifiers and their importance.
- Recognise strong and weak identifiers.
- Design KQL output with entity mapping in mind.
The investigation
An analytics rule finds a suspicious sign-in from 203.0.113.25 by alex@contoso.com.
The evidence is there. Now Sentinel needs to understand that one value is an IP address and the other represents an account.
What is entity mapping?
Entity mapping connects fields returned by an analytics rule query to standard entity types recognised by Microsoft Sentinel.
That mapping enriches alerts and incidents with structured information that can be used during investigation, correlation and response.
Good KQL tells you what happened. Good entity mapping tells Sentinel who and what were involved.
From query field to investigation entity
Common entity types
Microsoft Sentinel supports entities such as Account, Host, IP, URL, File, FileHash, Process, DNS, AzureResource, RegistryKey, RegistryValue, SecurityGroup, Mailbox and MailMessage.
The entity type tells Sentinel what kind of object the mapped data represents.
The query must return the field
You can only map a useful field if the final query output contains it.
If your query removes IPAddress before the final result set, there is nothing left for the rule to map as an IP entity.
A simple detection query
- 1
- 2
- 3
- 4
SigninLogs | where ResultType != "0" | summarize FailedSignIns = count() by UserPrincipalName, IPAddress | where FailedSignIns >= 10
The final output contains UserPrincipalName and IPAddress. Those columns can now be used when configuring entity mappings in the analytics rule.
Entity type
The entity type is the object Sentinel should create from the query data.
Examples include Account for a user identity, IP for an IP address and Host for a device.
Identifier
An identifier tells Sentinel which property of the entity your query field represents.
For an IP entity, for example, the query column can be mapped to the IP entity's address identifier.
Example mappings
| Query column | Entity type | Purpose |
|---|---|---|
| UserPrincipalName | Account | Identifies the user involved in the detection. |
| IPAddress | IP | Identifies the source or destination IP involved. |
| DeviceName | Host | Identifies the endpoint or server. |
| RemoteUrl | URL | Identifies a web resource involved in the activity. |
| SHA256 | FileHash | Identifies a file by cryptographic hash. |
Strong identifiers
A strong identifier can uniquely identify an entity by itself.
Where available, strong identifiers improve the chance that Sentinel correctly recognises the same entity across different data sources and detections.
Weak identifiers
A weak identifier might not uniquely identify an entity on its own.
Weak identifiers can become more useful when combined with additional identifiers that provide the missing context.
Why identifiers matter
Multiple identifiers
A single entity mapping can use up to three identifiers.
Using the appropriate combination can improve unique identification and correlation when a single field is not enough.
Multiple entities
A single analytics rule can define up to ten entity mappings.
You can also map more than one entity of the same type — for example, a source IP and a destination IP.
Source and destination IP example
- 1
- 2
- 3
CommonSecurityLog | where DeviceAction =~ "Allow" | project TimeGenerated, SourceIP, DestinationIP
The rule can map SourceIP as one IP entity and DestinationIP as another. Both mappings count toward the rule's entity mapping limit.
Why entities improve investigations
Mapped entities become structured parts of alerts and incidents rather than remaining anonymous text fields.
This gives analysts clearer pivots into the accounts, devices, addresses and other objects involved in the activity.
Correlation becomes stronger
Standardised entities help Sentinel connect related security information around the same account, host, IP address or other object.
That makes entity mapping an important part of turning a detection into useful investigation context.
Automation can use entities
Entity information can also be used during automated response workflows.
For example, a playbook may extract an account or IP entity from an incident and use it during enrichment or response actions.
Entity limits
An alert can identify up to 500 entities collectively across the mappings in a rule, with the available capacity divided across those mappings.
The total Entities field in an alert also has a 64 KB size limit.
Design the query for the investigation
Do not wait until the analytics rule wizard to think about entities.
While writing the KQL, ask which objects an analyst will need after the alert fires. Then preserve those fields in the final output so they are available for mapping.
The query is not finished merely because it can identify suspicious activity. It should also return the evidence required to investigate that activity.
Common mistake — field disappeared
The query starts with a useful IP address or account field, but a later summarize or project removes it.
The rule then cannot map the missing value as an entity.
Common mistake — wrong field
Mapping a field to the wrong entity type or identifier produces poor investigation context.
Check what the field actually contains rather than relying only on its column name.
Common mistake — too little identity
A short account name such as alex may not uniquely identify a user across environments or domains.
Use stronger identifiers or combinations of identifiers when the available data supports them.
Common mistake — map everything
More mappings do not automatically make a detection better.
Map the entities that genuinely help analysts understand, correlate and respond to the detected behaviour.
Agent Foskett investigation exercise
UserPrincipalName, IPAddress, DeviceName and FailedSignIns.
Which fields are natural candidates for entity mapping?
UserPrincipalName → Account, IPAddress → IP and DeviceName → Host.
FailedSignIns is useful investigation context, but it is a count rather than an entity. In the next lesson, we will look at how information like this can be surfaced using custom details.
Best practices
- Plan entity mapping while designing the KQL.
- Return every field required for mapping in the final query output.
- Prefer strong identifiers where possible.
- Use multiple identifiers when they improve unique identification.
- Map investigation-relevant entities rather than every available column.
Agent Foskett takeaway
Entity mapping is what turns useful query columns into objects Microsoft Sentinel understands.
Once the account, IP, host or other evidence becomes an entity, the alert becomes far more useful for correlation, investigation and response.
Related Agent Foskett learning
Continue learning
Entity Mapping in Microsoft Sentinel Analytics Rules
Microsoft Sentinel entity mapping connects analytics rule query output to recognised security entities such as accounts, IP addresses, hosts, URLs and file hashes, improving investigation, correlation and response.
Microsoft Sentinel Lesson 25
This Agent Foskett Microsoft Sentinel Academy lesson explains entity types, identifiers, strong and weak identification, multiple mappings and practical KQL design for investigation-ready alerts.
