What’s new: Alert Enrichment – Custom Details and Entity Mapping
Published Mar 09 2021 03:33 AM 9,269 Views

We are pleased to announce the new alert custom details and an improved version of entity mapping. Two new features which are part of a series of new alert enrichment capabilities in Microsoft Sentinel. Let's go through them in the following:


Custom Details.png


Custom Details:




When a security alert is triggered in the environment, the information described in the alert is crucial for the security analyst to perform their investigation. Hence, it is important that the alert contains essential information and therefore the ability to include custom details in the alert will improve the efficiency of investigation. Custom details allows users to add custom information to the alert created within scheduled alert rules.


How do I configure it?


When creating or editing an analytics rule, you will find Alert enhancement – Custom details section under Set rule logic tab.


Start configuring the custom details by providing a name that will appear as the field name in alerts and its value from the drop-down list. You can add multiple key-value pairs (up to 20) by clicking on “Add new”.


Where to view the custom details


The custom details will be stored as a part of 'ExtendedProperties' field in Json format. In the event where multiple alerts were triggered, each has its own custom details.




Below is the sample query to parse custom details where each field name will be unpacked as a column. The name of the column will be the field name with the prefix “custom_”.



| extend customDetails = parse_json(tostring(parse_json(ExtendedProperties).["Custom Details"]))
| evaluate bag_unpack (customDetails, "custom_")






We wouldn’t want the alert to be overloaded, so we will limit the number of key-value pairs to 20 in a single analytics rule and the details are limited to 2 KB collectively. Additional details will be dropped when exceeding the limit.




Entity Mapping:




Entity mapping configuration is essential in building scheduled query analytics rules. It allows Microsoft Sentinel to recognize the entities and form the core of analysis which help you to investigate incidents effectively and efficiently.

In the past, you could only map five entity types in Analytic rules – users (accounts), hosts, IP addresses, URLs and file hashes. It has been our goal to enhance the entity mapping feature with more entity types and identifier options for a greater flexibility in identifying an entity.


The new entity mapping offers the following enhancements and functionalities:

  • Supports additional entity types and identifiers (see the full list of supported Entity types and Identifiers).
  • Supports multiple entities of the same kind on a single event.
  • Supports strong and weak identifiers.
  • Validates the configuration of mappings during rule creation.
  • Unlike the previous version, the new entity mappings do not add codes to your query.


How do I configure it?


1.  When creating or editing an analytics rule, you will find Alert enhancement – Entity mapping section under Set rule logic tab.


2.  Select the entity type from the entity type drop-down list to start mapping (you may map up to a maximum of five entities at a time by clicking + Add new entity).



3.  Choose the identifier for each entity from the identifier drop-down list. Some identifiers are required, others are optional. Then, select the correspond data field from the Value drop-down list. The Value list is populated by the data fields (columns) defined in the rule query.


4.  The number of definable identifiers for a given entity  ranges from one to three, depending on the entity type. For example, IP entity has only one identifier, File entity can define up to two identifiers, while Host entity allows up to three.


Note that adding more identifiers to an entity allows Microsoft Sentinel to discover more attributes of a particular entity. Hence, the discovered entity will have a richer information about the entity. This helps to increase the efficiency during incident investigation.


5.  You can map more than one entity of the same type. For example, you can map two IP entities, one from a source IP address field and another one from a destination IP address field.


6.  Unlike the previous version, the new entity mappings do not add any code to the rule’s query.


What about my previously defined entity mappings?


1.  Your previously defined entity mappings will still be working as usual.


2.  If you configured the new entity mapping on an existing analytics rule with previously defined entity mappings, the rule will disregard the old mapping without removing the mappings defined in the query code.


3.  When you update a rule with the intention to add more entity mappings, you need to re-define all the entities via the new mapping.

For example, I have an existing rule with two entities defined (Account and Host) through the old mapping. If I wish to add another entity mapping (Registry Key), I need to define all the three entity types (Account, Host and Registry Key) with the new entity mapping feature.


4.  Lastly, if you still need to use the old version of entity mapping (as long as the new version is still in preview), you can access it using the URL with feature flag (https://ms.portal.azure.com/?feature.EntityMapping=false). More information can be found here.



Get started today! 


We encourage you to start using this feature as it will help to improve your efficiency by shorten the investigation time. 

 Try it out, and let us know what you think! 


You can also contribute new connectors, workbooks, analytics and more in Microsoft Sentinel. Get started now by joining theMicrosoft Sentinel Threat Hunters GitHub community. 



Special thanks to @romarsia and @Inwafula for the review.

Version history
Last update:
‎Nov 02 2021 06:38 PM
Updated by: