more-articles-about-microsoft-sentinel-solutions

Author: LHL407

articles/sentinel/sentinel-analytic-rules-creation.md

@@ -12,9 +12,9 @@ ms.date: 1/27/2025
 
 # Create and publish analytics rules for Microsoft Sentinel solutions
 
-Microsoft Sentinel analytics rules are sets of criteria. They define how data is monitored, what is detected, and what actions are taken when specific conditions are met. These rules help identify suspicious behavior, anomalies, and potential security threats by analyzing logs and signals from various data sources.
+Microsoft Sentinel analytics rules are sets of criteria. They define how data is monitored, what's detected, and what actions are taken when specific conditions are met. These rules help identify suspicious behavior, anomalies, and potential security threats by analyzing logs and signals from various data sources.
 
-Microsoft Sentinel analytics rules are powerful tools for enhancing an organization's security posture because they proactively detect and respond to potential threats. By following a structured approach to creating and managing these rules, organizations can use Microsoft Sentinel's capabilities to protect their digital assets and maintain a robust security infrastructure. For more information, see [Threat detection in Microsoft Sentinel](/azure/sentinel/threat-detection).
+Microsoft Sentinel analytics rules are powerful tools for enhancing an organization's security posture because they proactively detect and respond to potential threats. By following a structured approach to creating and managing these rules, organizations can use the capabilities of Microsoft Sentinel to protect their digital assets and maintain a robust security infrastructure. For more information, see [Threat detection in Microsoft Sentinel](/azure/sentinel/threat-detection).
 
 This article walks you through the process of creating and publishing analytics rules to Microsoft Sentinel solutions.
 
@@ -37,7 +37,7 @@ Microsoft Sentinel analytics rules can be applied to a wide range of scenarios t
 
 You create analytics rules in [YAML](https://yaml.org/) format. You can use this example of an analytics rule as a reference to create your own queries: [Sample analytics rule in GitHub](https://github.com/Azure/Azure-Sentinel/blob/master/Solutions/Microsoft%20Entra%20ID/Analytic%20Rules/FailedLogonToAzurePortal.yaml).
 
-In this section, we provide a detailed walkthrough of various attributes of an analytics rule.
+The following sections provide a detailed walkthrough of various attributes of an analytics rule.
 
 ### ID
 
@@ -55,25 +55,25 @@ This field is mandatory.
 
 ### Name
 
-The `name` attribute provides a brief label that summarizes the detection. Make sure the label is clear and concise to help users understand the purpose of the rule. Use `alertDetailsOverride` to generate dynamic names to help analysts understand the alert. See the following requirements:
+The `name` attribute provides a brief label that summarizes the detection. Make sure the label is clear and concise to help users understand the purpose of the rule. Use `alertDetailsOverride` to generate dynamic names to help analysts understand the alert. This attribute:
 
-* Uses sentence-case capitalization
-* Doesn't end in a period
-* Has a maximum length of 50 characters (whenever possible)
+* Uses sentence-case capitalization.
+* Doesn't end in a period.
+* Has a maximum length of 50 characters (whenever possible).
 
 This field is mandatory.
 
 ### Description
 
-The `description` attribute provides a detailed description of the detection. The description includes information about the behavior being detected, the potential effect, and any recommended actions. See the following requirements:
+The `description` attribute provides a detailed description of the detection. The description includes information about the behavior being detected, the potential effect, and any recommended actions. This attribute:
 
-* Uses sentence case capitalization
-* Starts with "This query searches for" or "Identifies"
-* Is different from and more descriptive than the name field
-* Has a maximum length of 255 characters
-* Is five sentences or less
-* Doesn't describe the data source (connector or data type)
-* Doesn't provide a technical explanation for the query language
+* Uses sentence case capitalization.
+* Starts with "This query searches for" or "Identifies."
+* Is different from and more descriptive than the name field.
+* Has a maximum length of 255 characters.
+* Is five sentences or less.
+* Doesn't describe the data source (connector or data type).
+* Doesn't provide a technical explanation for the query language.
 
 This field is mandatory.
 
@@ -99,31 +99,31 @@ The `dataTypes` attribute represents the data types that the analytics rule depe
 
 ### Query period
 
-The `queryPeriod` attribute represents a specified period during which the query runs. For example: the last three days.
+The `queryPeriod` attribute represents a specified period during which the query runs. For example: the last 3 days. For this attribute:
 
-* Use Kusto Query Language (KQL) `TimeSpan` format (for example, three days is `3d`, 2 hours is `2h`).
+* Use Kusto Query Language (KQL) `TimeSpan` format (for example, 3 days is `3d`, 2 hours is `2h`).
 * Ensure that any learning or reference period is within this time frame.
 * Don't use a value higher than the maximum supported value, which is `14d`.
 
 This field is mandatory for scheduled analytics rules.
 
 ### Query frequency
 
-The `queryFrequency` attribute represents the frequency at which the query runs.
+The `queryFrequency` attribute represents the frequency at which the query runs. For this attribute:
 
-* Use KQL `TimeSpan` format (for example, three days is `3d`, 2 hours is `2h`).
+* Use KQL `TimeSpan` format (for example, 3 days is `3d`, 2 hours is `2h`).
 * Use a `queryFrequency` that is less than or equal to the `queryPeriod`.
-* Follow this rule: if the `queryPeriod` is greater than or equal to two days (`2d`), the `queryFrequency` value can't be less than 1 hour (`1h`) and is only used for high-severity detections.
+* Follow this rule: if the `queryPeriod` is greater than or equal to 2 days (`2d`), the `queryFrequency` value can't be less than 1 hour (`1h`) and is only used for high-severity detections.
 
 This field is mandatory for scheduled analytics rules.
 
 ### Trigger operator
 
 The `triggerOperator` attribute indicates the mechanism that triggers the alert. For example: greater than (`gt`) the number set in the `triggerThreshold` attribute (see [Trigger threshold](#trigger-threshold)).
 
-* `gt`: Greater than
-* `lt`: Less than
-* `eq`: Equal to
+* `gt`: Greater than.
+* `lt`: Less than.
+* `eq`: Equal to.
 
 This field is mandatory for scheduled analytics rules.
 
@@ -137,7 +137,7 @@ This field is mandatory for scheduled analytics rules.
 
 ### Tactics
 
-The `tactics` attribute defines the [`MITRE ATT&CK tactics`](https://attack.mitre.org/versions/v13/matrices/enterprise/) that the detection relates to. When you define the tactics, it helps users understand the context of the detection and how it fits into the overall threat landscape.
+The `tactics` attribute defines the [`MITRE ATT&CK tactics`](https://attack.mitre.org/versions/v13/matrices/enterprise/) that the detection relates to. When you define the tactics, it helps users understand the context of the detection and how it fits into the overall threat landscape. For this attribute:
 
 * `ATT&CK Framework v13` is supported.
 * Names can't include spaces. For example: `InitialAccess` or `LateralMovement`.
@@ -146,17 +146,17 @@ This field is mandatory.
 
 ### Relevant techniques
 
-The `relevantTechniques` attribute defines the [`MITRE ATT&CK techniques`](https://attack.mitre.org/versions/v13/matrices/enterprise/) that the detection relates to. When you define the techniques, it helps users understand the context of the detection and how it fits into the overall threat landscape.
+The `relevantTechniques` attribute defines the [`MITRE ATT&CK techniques`](https://attack.mitre.org/versions/v13/matrices/enterprise/) that the detection relates to. When you define the techniques, it helps users understand the context of the detection and how it fits into the overall threat landscape. For this attribute:
 
 * `ATT&CK Framework v13` is supported.
-* It matches `MITRE` tactics.
+* Attribute matches `MITRE` tactics.
 * Names can't include spaces. For example: `T1078` or `T1078.001`.
 
 This field is mandatory.
 
 ### Query
 
-The `query` attribute defines the detection logic. We recommend that you write the query in KQL and make sure that it's well-structured and easy to understand. We recommend that you create an efficient query that's optimized for performance to ensure it can be run against large datasets without affecting performance. Make sure that your query meets the following criteria.
+The `query` attribute defines the detection logic. We recommend that you write the query in KQL and make sure that it's structured and easy to understand. We recommend that you create an efficient query that's optimized for performance to ensure it can be run against large datasets without affecting performance. Make sure that your query meets the following criteria.
 
 Limit the query to 10,000 characters. If the query section exceeds this limit, consider reducing the number of characters. A static list of items used for comparison within the query body can cause you to go over the limit. We recommend that you move these lists to one of the following options:
 
@@ -176,8 +176,9 @@ Define human-readable names for explicit constants:
 We highly recommend that you use comments to clarify the query. Avoid adding comments at the end of a query statement line. Instead, add your comments on a separate line. For example:
 
 ```
-    // Removing noisy processes for an environment, adjust as needed
+  // Removing noisy processes for an environment, adjust as needed
 ```
+
 If you're referencing a parser instead of a table name, ensure clarity in the description by including a comment next to the parser function reference. The parser must be imported into the workspace first. Otherwise, the queries don't recognize it as valid.
 
 Ensure that every available entity field is returned for mapping purposes. (Refer to the [Entity mappings section](#entity-mappings).) Sanitize the returned table so that it provides only the properties that you need to investigate further. You don't need a `TimeGenerated` filter when you use a simple `lookback` command across the entire query. The `queryPeriod` value in the YAML controls this process.
@@ -195,16 +196,18 @@ This field is mandatory.
 The `eventGroupingSettings` attribute relates to alerts. An alert rule can generate a separate alert for each query result. For instance, a rule that identifies non-Microsoft alerts in the event stream could create a Microsoft Sentinel alert for each source alert.
 
 * To produce a single alert for all query results (the default), use:
-            ```json
-            eventGroupingSettings:
-              aggregationKind: SingleAlert
-            ```
+
+  ```json
+  eventGroupingSettings:
+  aggregationKind: SingleAlert
+  ```
 
 * To produce a separate alert for each query result, use:
-            ```json
-            eventGroupingSettings:
-              aggregationKind: AlertPerResult
-            ```
+
+  ```json
+  eventGroupingSettings:
+  aggregationKind: AlertPerResult
+  ```
 
 ### Entity mappings
 
@@ -216,40 +219,40 @@ This field is mandatory.
 
 ### Field mappings
 
-The `fieldMappings` attribute represents the identifier of the field in the query output that corresponds to the entity type. See allowed values under the identifiers column value at [Entity mapping table](/azure/sentinel/entities-reference#entity-types-and-identifiers).
+The `fieldMappings` attribute represents the identifier of the field in the query output that corresponds to the entity type. See allowed values under the identifiers column value at [Entity mapping table](/azure/sentinel/entities-reference#entity-types-and-identifiers). For this attribute:
 
 * Each template can have up to 10 entity mappings.
 * Each entity mapping can have up to three field mappings (that is, identifiers).
 
-```json
-        entityMappings:
-        - entityType: Account
-          fieldMappings:
-            - identifier: FullName
-              columnName: AccountCustomEntity
-        - entityType: Host
-          fieldMappings:
-            - identifier: FullName
-              columnName: HostCustomEntity
-        - entityType: IP
-          fieldMappings:
-            - identifier: Address
-              columnName: ClientIP
-        - entityType: DNS
-          fieldMappings:
-            - identifier: DomainName
-              columnName: Name
-
-```
+  ```json
+  entityMappings:
+  - entityType: Account
+    fieldMappings:
+      - identifier: FullName
+        columnName: AccountCustomEntity
+  - entityType: Host
+    fieldMappings:
+      - identifier: FullName
+        columnName: HostCustomEntity
+  - entityType: IP
+    fieldMappings:
+      - identifier: Address
+        columnName: ClientIP
+  - entityType: DNS
+    fieldMappings:
+      - identifier: DomainName
+        columnName: Name
+
+  ```
 
 ### Custom details
 
 The `customDetails` attribute integrates event data into alerts, making it visible in security incidents for faster triaging, investigation, and response. Custom details are key/value pairs of property and column names. For more information, see [Surface custom event details in alerts in Microsoft Sentinel](/azure/sentinel/surface-custom-details-in-alerts). Up to 20 custom details (that is, key/value pairs) can be defined per template.
 
 ```json
-        customDetails:
-        Computers: Computer
-        IPs: ComputerIP
+    customDetails:
+      Computers: Computer
+      IPs: ComputerIP
 ```
 
 ### Alert details override
@@ -260,25 +263,25 @@ The `alertDetailsOverride` attribute is a dynamic field that you can use to over
 * The `name` must not exceed 256 characters, while the `description` is limited to 5,000 characters.
 * The column name within the curly braces must precisely match the expected column name, without any leading or trailing white space (for example, `{{columnName}}`, not `{{ columnName }}`). In the following example, `columnName1`, `columnName2`, `dynamicTactic`, and `dynamicSeverity` are output fields of the scheduled alert query.
 
-    ```json
-        alertDetailsOverride:
-          alertDisplayNameFormat: free text with field names embedded using the format {{columnName}} # Up to 256 chars and 3 placeholders
-          alertDescriptionFormat: free text with field names embedded using the format  {{columnName}} # Up to 5000 chars and 3 placeholders
-          alertTacticsColumnName: dynamicTacticColumnName
-          alertSeverityColumnName: dynamicSeverityColumnName
+  ```json
+      alertDetailsOverride:
+        alertDisplayNameFormat: free text with field names embedded using the format {{columnName}} # Up to 256 chars and 3 placeholders
+        alertDescriptionFormat: free text with field names embedded using the format  {{columnName}} # Up to 5000 chars and 3 placeholders
+        alertTacticsColumnName: dynamicTacticColumnName
+        alertSeverityColumnName: dynamicSeverityColumnName
 
-    ```
+  ```
 
-    ```json
-        alertDetailsOverride:
-          alertDisplayNameFormat: rule {{columnName1}} display name
-          alertDescriptionFormat: rule {{columnName2}} display name
-          alertTacticsColumnName: dynamicTactic
-          alertSeverityColumnName: dynamicSeverity
-    ```
+  ```json
+      alertDetailsOverride:
+        alertDisplayNameFormat: rule {{columnName1}} display name
+        alertDescriptionFormat: rule {{columnName2}} display name
+        alertTacticsColumnName: dynamicTactic
+        alertSeverityColumnName: dynamicSeverity
+  ```
 
 ### Version
 
-When a customer creates a new hunting query from the template, the template `version` is saved. If a new template version is published, customers are notified in the UX. Versions follow the format a, b, and c, in which a is the major version, b is the minor version, and c is the patch. The version field is the last line of the template.
+When a customer creates a new hunting query from the template, the template `version` is saved. If a new template version is published, customers are notified in the UX. Versions follow the format `a`, `b`, and `c`, in which `a` is the major version, `b` is the minor version, and `c` is the patch. The version field is the last line of the template.
 
 This field is mandatory.