|
| 1 | +--- |
| 2 | +title: Manage template versions for your scheduled analytics rules in Azure Sentinel |
| 3 | +description: Learn how to manage the relationship between your scheduled analytics rule templates and the rules created from those templates. Merge updates to the templates into your rules, and revert changes in your rules back to the original template. |
| 4 | +services: sentinel |
| 5 | +documentationcenter: na |
| 6 | +author: yelevin |
| 7 | +manager: rkarlin |
| 8 | +editor: '' |
| 9 | + |
| 10 | +ms.service: azure-sentinel |
| 11 | +ms.subservice: azure-sentinel |
| 12 | +ms.devlang: na |
| 13 | +ms.topic: how-to |
| 14 | +ms.tgt_pltfrm: na |
| 15 | +ms.workload: na |
| 16 | +ms.date: 10/03/2021 |
| 17 | +ms.author: yelevin |
| 18 | + |
| 19 | +--- |
| 20 | +# Manage template versions for your scheduled analytics rules in Azure Sentinel |
| 21 | + |
| 22 | +> [!IMPORTANT] |
| 23 | +> |
| 24 | +> This feature is in **PREVIEW**. See the [Supplemental Terms of Use for Microsoft Azure Previews](https://azure.microsoft.com/support/legal/preview-supplemental-terms/) for additional legal terms that apply to Azure features that are in beta, preview, or otherwise not yet released into general availability. |
| 25 | +
|
| 26 | +## Introduction |
| 27 | + |
| 28 | +Azure Sentinel comes with [analytics rule templates](detect-threats-built-in.md) that you turn into active rules by effectively creating a copy of them – that’s what happens when you create a rule from a template. At that point, however, the active rule is no longer connected to the template. If changes are made to a rule template, by Microsoft engineers or anyone else, any rules created from that template beforehand are ***not*** dynamically updated to match the new template. |
| 29 | + |
| 30 | +However, rules created from templates ***do*** remember which templates they came from, which allows you two advantages: |
| 31 | + |
| 32 | +- If you made changes to a rule when creating it from a template (or at any time after that), you can always revert the rule back to its original version (as a copy of the template). |
| 33 | + |
| 34 | +- You can get notified when a template is updated, and you'll have the choice to update your rules to the new version of their templates or leave them as they are. |
| 35 | + |
| 36 | +This article will show you how to manage these tasks, and what to keep in mind. The procedures discussed below apply to any **[Scheduled](detect-threats-built-in.md#scheduled)** analytics rules created from templates. |
| 37 | + |
| 38 | +## Discover your rule's template version number |
| 39 | + |
| 40 | +With the implementation of template version control, you can see and track the versions of your rule templates and the rules created from them. Rules whose templates have been updated display an "*Update available*" badge next to the rule name. |
| 41 | + |
| 42 | +1. On the **Analytics** blade, select the **Active rules** tab. |
| 43 | + |
| 44 | +1. Select any rule of type **Scheduled**. |
| 45 | + |
| 46 | + - If the rule displays the "*Update available*" badge, its details pane will have a **Review and update** button next to the **Edit** button (see image 1 in the next step below). |
| 47 | + |
| 48 | + - If the rule was created from a template but does not have the "*Update available*" badge, its details pane will have a **Compare with template** button next to the **Edit** button (see images 2 and 3 in the next step below). |
| 49 | + |
| 50 | + - If there is only an **Edit** button, the rule was created from scratch, not from a template. |
| 51 | + |
| 52 | + :::image type="content" source="media/manage-analytics-rule-templates/see-rules-with-updated-template.png" alt-text="Screenshot of active rules list, with badge indicating a template update is available." lightbox="media/manage-analytics-rule-templates/see-rules-with-updated-template.png"::: |
| 53 | + |
| 54 | +1. Scroll down to the bottom of the details pane, where you'll see two version numbers: the version of the template from which the rule was created, and the latest available version of the template. |
| 55 | + |
| 56 | + :::image type="content" source="media/manage-analytics-rule-templates/see-template-versions.png" alt-text="Screenshot of details pane. Scroll down to see template version numbers." border="false"::: |
| 57 | + |
| 58 | + The number is in a “1.0.0” format – major version, minor version, and build. |
| 59 | + (For the time being, the build number is not in use and will always be 0.) |
| 60 | + |
| 61 | + - A difference in the *major version* number indicates that something essential in the template was changed, that could affect how the rule detects threats or even its ability to function altogether. This is a change you will want to include in your rules. |
| 62 | + |
| 63 | + - A difference in the *minor version* number indicates a minor improvement in the template – a cosmetic change or something similar – that would be “nice to have” but is not critical to maintaining the rule’s functionality, efficacy, or performance. This is a change that you could just as easily take or leave. |
| 64 | + |
| 65 | + > [!NOTE] |
| 66 | + > Images 2 and 3 above show two examples of rules created from templates, where the template has not been updated. |
| 67 | + > - Image 2 shows a rule that has a version number for its current template. This signals that the rule was created after Azure Sentinel's initial implementation of template version control in October 2021. |
| 68 | + > - Image 3 shows a rule that doesn't have a current template version. This shows that the rule had been created before October 2021. If there is a latest template version available, it's likely a newer version of the template than the one used to create the rule. |
| 69 | +
|
| 70 | +## Compare your active rule with its template |
| 71 | + |
| 72 | +Choose one of the following tabs according to the action you wish to take, to see the instructions for that action: |
| 73 | + |
| 74 | +# [Update template](#tab/update) |
| 75 | + |
| 76 | +Having selected a rule and determined that you want to consider updating it, select **Review and update** on the details pane (see above). You'll see that the **Analytics rule wizard** now has a **Compare to latest version** tab. |
| 77 | + |
| 78 | +On this tab you'll see a side-by-side comparison between the YAML representations of the existing rule and the latest version of the template. |
| 79 | + |
| 80 | +:::image type="content" source="media/manage-analytics-rule-templates/compare-template-versions.png" alt-text="Screenshot of 'Compare to latest version' tab in Analytics rule wizard."::: |
| 81 | + |
| 82 | +> [!NOTE] |
| 83 | +> Updating this rule will overwrite your existing rule with the latest version of the template. |
| 84 | +Any automation step or logic that makes reference to the existing rule should be verified, in case the referenced names have changed. Also, any customizations you made in creating the original rule - changes to the query, scheduling, grouping, or other settings - may be overwritten. |
| 85 | + |
| 86 | +### Update your rule with the new template version |
| 87 | + |
| 88 | +- If the changes made to the new version of the template are acceptable to you, and nothing else in your original rule has been affected, select **Review and update** to validate and apply the changes. |
| 89 | + |
| 90 | +- If you want to further customize the rule or re-apply any changes that might otherwise be overwritten, select **Next : Custom changes**. If you choose this, you will cycle through the remaining tabs of the [Analytics rule wizard](detect-threats-custom.md) to make those changes, after which you will validate and apply the changes on the **Review and update** tab. |
| 91 | + |
| 92 | +- If you don't want to make any changes to your existing rule, but rather to keep the existing template version, simply exit the wizard by selecting the X in the upper right corner. |
| 93 | + |
| 94 | +# [Revert to template](#tab/revert) |
| 95 | + |
| 96 | +Having selected a rule and determined that you want to revert to its original version, select **Compare with template** on the details pane (see above). You'll see that the **Analytics rule wizard** now has a **Compare to latest version** tab. |
| 97 | + |
| 98 | +On this tab you'll see a side-by-side comparison between the YAML representations of the existing rule and the latest version of the template. These two version numbers may be the same, but the left side shows the active rule including any changes that have been made to it during or after its creation from the template, while the right side shows the unchanged template. |
| 99 | + |
| 100 | +:::image type="content" source="media/manage-analytics-rule-templates/compare-template-versions-2.png" alt-text="Screenshot of 'Compare to latest version' tab in Analytics rule wizard."::: |
| 101 | + |
| 102 | +> [!NOTE] |
| 103 | +> Updating this rule will overwrite your existing rule with the latest version of the template. |
| 104 | +Any automation step or logic that makes reference to the existing rule should be verified, in case the referenced names have changed. Also, any customizations you made in creating the original rule - changes to the query, scheduling, grouping, or other settings - may be overwritten. |
| 105 | + |
| 106 | +### Revert your rule to its original template version |
| 107 | + |
| 108 | +- If you want to revert completely to the original version of this rule - a clean copy of the template - select **Review and update** to validate and apply the changes. |
| 109 | + |
| 110 | +- If you want to customize the rule differently or re-apply any changes that might otherwise be overwritten, select **Next : Custom changes**. If you choose this, you will cycle through the remaining tabs of the [Analytics rule wizard](detect-threats-custom.md) to make those changes, after which you will validate and apply the changes on the **Review and update** tab. |
| 111 | + |
| 112 | +- If you don't want to make any changes to your existing rule, simply exit the wizard by selecting the X in the upper right corner. |
| 113 | + |
| 114 | +--- |
| 115 | + |
| 116 | +## Next steps |
| 117 | +In this document, you learned how to track the versions of your Azure Sentinel analytics rule templates, and either to revert active rules to existing template versions, or update them to new ones. To learn more about Azure Sentinel, see the following articles: |
| 118 | + |
| 119 | +- Learn more about [analytics rules](detect-threats-built-in.md). |
| 120 | +- See more details about the [analytics rule wizard](detect-threats-custom.md). |
0 commit comments