Customize alert details in Microsoft Sentinel

• Applies to:

  Microsoft Sentinel in the Azure portal, Microsoft Sentinel in the Microsoft Defender portal

This article explains how to override the default properties of alerts with content from the underlying query results.

In the process of creating a scheduled analytics rule, as the first step you define a name and description for the rule, and you assign it a severity and MITRE ATT&CK tactics. All alerts generated by a given rule - and all incidents created as a result - will inherit the name, description, severity, and tactics defined in the rule, without regard to the particular content of a specific instance of the alert.

With the alert details feature, you can override these and other default properties of alerts in two ways:

• Create custom, variable names and descriptions for your alerts. You can select fields in your alert's query output whose contents can be included in the name or description of each instance of the alert. If the selected field has no value in a given instance, the alert details for that instance will revert to the defaults specified in the first page of the wizard.

• Customize the severity, tactics, and other properties of a given instance of an alert (see the full list of properties below) with the values of any relevant fields from the query output. If the selected fields are empty or have values that don't match the field data type, the respective alert properties will revert to their defaults (for tactics and severity, those specified in the first page of the wizard).

Important

• Some alert details' customizability (see those so indicated below) are currently in PREVIEW. See the Supplemental Terms of Use for Microsoft Azure Previews for additional legal terms that apply to Azure features that are in beta, preview, or otherwise not yet released into general availability.
• Microsoft Sentinel is generally available within Microsoft's unified security operations platform in the Microsoft Defender portal. For preview, Microsoft Sentinel is available in the Defender portal without Microsoft Defender XDR or an E5 license. For more information, see Microsoft Sentinel in the Microsoft Defender portal.

Follow the procedure detailed below to use the alert details feature. These steps are part of the analytics rule creation wizard, but they're addressed here independently to address the scenario of adding or changing alert details in an existing analytics rule.

How to customize alert details

1. Enter the Analytics page in the portal through which you access Microsoft Sentinel:

   Azure portal

   From the Configuration section of the Microsoft Sentinel navigation menu, select Analytics.

   Defender portal

   From the Microsoft Defender navigation menu, expand Microsoft Sentinel, then Configuration. Select Analytics.

2. Select a scheduled query rule and select Edit. Or create a new rule by selecting Create > Scheduled query rule at the top of the screen.

3. Select the Set rule logic tab.

4. In the Alert enrichment section, expand Alert details.

   

5. In the now-expanded Alert details section, add free text that includes properties corresponding to the details you want to display in the alert:

   1. In the Alert Name Format field, enter the text you want to appear as the name of the alert (the alert text), and include, in double curly brackets, any query output fields you want to be part of the alert text.

      Example: Alert from {{ProviderName}}: {{AccountName}} failed to sign in to computer {{ComputerName}}.

   2. Do the same with the Alert Description Format field.

      Note

      You are currently limited to three parameters each in the Alert Name Format and Alert Description Format fields.

   3. To override other default properties, select an alert property from the Alert property drop-down list. Then select the field from the query results, whose contents you want to populate the alert property, from the Value drop-down list.

   4. To override more default properties, select + Add new and repeat the previous step. The following properties can be overridden:

      Name	Description
      AlertName	String
      Description	String
      AlertSeverity	One of the following values: - Informational - Low - Medium - High
      Tactics	One of the following values: - Reconnaissance - ResourceDevelopment - InitialAccess - Execution - Persistence - PrivilegeEscalation - DefenseEvasion - CredentialAccess - Discovery - LateralMovement - Collection - Exfiltration - CommandAndControl - Impact - PreAttack - ImpairProcessControl - InhibitResponseFunction
      Techniques (Preview)	A string that matches the following regular expression: ^T(?<Digits>\d{4})$. For example: T1234
      AlertLink (Preview)	String
      ConfidenceLevel (Preview)	One of the following values: - Low - High - Unknown
      ConfidenceScore (Preview)	Integer, between 0-1 (inclusive)
      ExtendedLinks (Preview)	String
      ProductComponentName (Preview)	String
      ProductName (Preview) * See note following this table	String
      ProviderName (Preview)	String
      RemediationSteps (Preview)	String

      Note

      If you onboarded Microsoft Sentinel to the Microsoft Defender portal, do not customize the ProductName field for alerts from Microsoft sources. Doing so will result in these alerts being dropped from Microsoft Defender XDR and no incident being created.

   If you change your mind, or if you made a mistake, you can remove an alert detail by clicking the trash can icon next to the Alert property/Value pair, or delete the free text from the Alert Name/Description Format fields.

6. When you have finished customizing your alert details, if you're now creating the rule, continue to the next tab in the wizard. If you're editing an existing rule, select the Review and create tab. Once the rule validation is successful, select Save.

Service limits

• You can override a field with up to 50 values in a single query. When your query exceeds 50 customized values, all customized values are dropped, and in all query results the field reverts to its default value. Tune your query to yield no more than 50 values to ensure no customized values are dropped.
• The size limit for the AlertName field, and any other non-collection properties, is 256 bytes.
• The size limit for the Description field, and any other collection properties, is 5 KB.
• Values exceeding the size limits are dropped.

Next steps

In this document, you learned how to customize alert details in Microsoft Sentinel analytics rules. To learn more about Microsoft Sentinel, see the following articles:

• Explore the other ways to enrich your alerts:
  • Map data fields to entities in Microsoft Sentinel
  • Surface custom event details in alerts in Microsoft Sentinel
• Get the complete picture on scheduled query analytics rules.
• Learn more about entities in Microsoft Sentinel.