Lesson 26 — Custom Details and Alert Enrichment
Your analytics rule has fired. The account and IP address are mapped as entities.
But the analyst still wants to know why the alert matters: how many failures occurred, which application was targeted and when did the activity begin?
Custom details bring useful query values directly into the alert so the evidence is waiting for the analyst instead of hiding back in the query results.
What you will learn
Learn how to enrich Microsoft Sentinel alerts with useful values already returned by your analytics rule query.
Learning objectives
After completing this lesson, you should understand how custom details improve the investigation value of analytics rule alerts.
- Explain what custom details do.
- Choose useful query fields for alert enrichment.
- Understand the difference between entities and custom details.
- Preserve enrichment fields in the final KQL output.
- Avoid overloading an alert with unnecessary information.
The investigation
An analytics rule detects repeated failed sign-ins by alex@contoso.com from 203.0.113.25.
The account and IP are useful entities. But the analyst also wants to know that there were 742 failed sign-ins, which application was targeted and when the activity started.
What are custom details?
Custom details let an analytics rule take values returned by its query and surface them as additional information in the resulting alert.
Instead of forcing the analyst to reopen the query just to find an important count, application name or other investigation value, the rule can carry that context forward with the alert.
The detection already calculated the evidence. Do not make the next analyst calculate it again.
From query result to enriched alert
Entities and custom details are different
An account, IP address or host can become a structured Sentinel entity used for investigation and correlation.
A count such as FailedSignIns = 742 is not an entity. It is investigation context — exactly the kind of value custom details are designed to surface.
The query must return the value
Just like entity mapping, alert enrichment depends on the final query output.
If a later summarize or project removes a field, that value is no longer available to use as a custom detail.
Build useful investigation context
- 1
- 2
- 3
- 4
- 5
- 6
- 7
- 8
SigninLogs
| where ResultType != "0"
| summarize FailedSignIns = count(),
FirstSeen = min(TimeGenerated),
LastSeen = max(TimeGenerated)
by UserPrincipalName, IPAddress, AppDisplayName
| where FailedSignIns >= 10
The query now returns the identity and network fields needed for entity mapping as well as useful values that explain why the detection fired.
Custom detail key
The key is the label the analyst sees in the alert.
Use a clear name such as FailedSignIns, Application or FirstSeen rather than something vague such as Value1.
Custom detail value
The value comes from a column returned by the analytics rule query.
For example, the key Application could use the query column AppDisplayName as its value.
Example enrichment
| Custom detail key | Query column | Investigation value |
|---|---|---|
| FailedSignIns | FailedSignIns | Shows why the threshold-based detection fired. |
| Application | AppDisplayName | Shows which application was involved. |
| FirstSeen | FirstSeen | Shows when the observed activity began. |
| LastSeen | LastSeen | Shows the most recent event in the detection window. |
Why enrichment speeds up triage
An analyst should not need to reopen the original query to discover the basic reason an alert fired.
Useful custom details can put threshold counts, application names, locations, risk values or other important context directly in front of the analyst.
Do not copy every column
Alert enrichment is not a replacement for the underlying evidence.
Surface the values that help the analyst make the next decision. Leave everything else in the event data where it can be examined when needed.
Before and after enrichment
Dynamic alert details
Sentinel can also use query output to customise selected standard alert properties so individual alerts carry more meaningful context.
For example, a useful query value can help make the alert name or description more specific to the detected activity.
Keep alert names readable
Dynamic information is useful when it makes an alert easier to recognise.
Do not turn the alert title into a dump of every available field. The analyst should be able to scan the incident queue quickly.
Think like the receiving analyst
If I received this alert during a busy shift, which values would help me decide what to investigate next?
Those are your strongest candidates for custom details. Enrichment should reduce clicks and uncertainty, not add noise.
Common mistake — field disappeared
The query originally contains a useful value, but a later transformation removes it from the final result.
The analytics rule cannot enrich the alert with a field it no longer receives.
Common mistake — meaningless labels
A key such as Result1 or ExtraData tells the analyst almost nothing.
Name custom details according to the evidence they contain.
Common mistake — too much enrichment
Adding every available field can make the alert harder to read rather than easier.
Prioritise evidence that changes triage, investigation or response decisions.
Common mistake — replacing entities
Do not use custom details as a substitute for proper entity mapping.
If a user, host or IP should be an entity, map it as an entity. Use custom details for the additional context around those entities.
Agent Foskett investigation exercise
UserPrincipalName, IPAddress, DeviceName, FailedSignIns, AppDisplayName and FirstSeen.
Which fields belong to entities, and which make useful custom details?
UserPrincipalName → Account, IPAddress → IP and DeviceName → Host.
FailedSignIns, AppDisplayName and FirstSeen are useful candidates for alert enrichment because they explain the activity around those entities.
Best practices
- Design enrichment while writing the KQL.
- Keep useful enrichment fields in the final query output.
- Use clear custom detail names.
- Surface values that help analysts make decisions.
- Keep entity mapping and custom details serving their different purposes.
- Avoid filling alerts with context that nobody will use.
Agent Foskett takeaway
A good analytics rule does more than detect suspicious activity. It packages the result so another analyst can understand it quickly.
Entities tell Sentinel who and what were involved. Custom details carry the extra evidence that explains why the alert deserves attention.
Related Agent Foskett learning
Continue learning
Custom Details and Alert Enrichment in Microsoft Sentinel
Microsoft Sentinel custom details surface useful analytics rule query values directly in alerts, giving security analysts immediate context such as counts, applications, timestamps and other investigation evidence.
Microsoft Sentinel Lesson 26
This Agent Foskett Microsoft Sentinel Academy lesson explains custom detail keys and values, alert enrichment, dynamic alert context, KQL field preservation and practical design for analyst-ready alerts.
