You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: articles/sentinel/ci-cd-custom-content.md
+42-36Lines changed: 42 additions & 36 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -5,7 +5,7 @@ description: This article explains custom Sentinel content like GitHub or Azure
5
5
author: mberdugo
6
6
ms.author: monaberdugo
7
7
ms.service: microsoft-sentinel
8
-
ms.topic: conceptual
8
+
ms.topic: article
9
9
ms.date: 12/31/2024
10
10
ms.custom:
11
11
- template-concept
@@ -19,15 +19,28 @@ ms.collection: usx-security
19
19
20
20
---
21
21
22
-
# Manage content as code with Microsoft Sentinel repositories (public preview)
22
+
# Manage content as code with Microsoft Sentinel repositories (preview)
23
23
24
-
The Microsoft Sentinel repositories feature provides a central experience for the deployment and management of Sentinel content as code. Repositories allow connections to an external source control for continuous integration / continuous delivery (CI/CD). This automation removes the burden of manual processes to update and deploy your custom content across workspaces. A subset of content as code is *detections* as code (DaC). Microsoft Sentinel **Repositories** implements DaC as well.
24
+
Microsoft Sentinel repositories let you deploy and manage custom Sentinel content from an external source control repository for continuous integration/continuous delivery (CI/CD). This automation removes the need for manual processes to update and deploy your custom content across workspaces. A subset of content as code is *detections* as code (DaC). Microsoft Sentinel **Repositories** implements DaC as well.
25
25
26
26
For more information on Sentinel content, see [About Microsoft Sentinel content and solutions](sentinel-solutions.md).
27
27
28
28
> [!IMPORTANT]
29
29
> The Microsoft Sentinel **Repositories** feature is currently in **PREVIEW**. See the [Supplemental Terms of Use for Microsoft Azure Previews](https://azure.microsoft.com/support/legal/preview-supplemental-terms/) for more legal terms that apply to Azure features that are in beta, preview, or otherwise not yet released into general availability.
30
-
>
30
+
31
+
32
+
## How Microsoft Sentinel repositories work
33
+
34
+
You can deploy these Microsoft Sentinel custom content types from an external source control repository you connect to Microsoft Sentinel:
35
+
36
+
- Analytics rules
37
+
- Automation rules
38
+
- Hunting queries
39
+
- Parsers
40
+
- Playbooks
41
+
- Workbooks
42
+
43
+
Updates you make to the content in your Microsoft Sentinel repositories are synchronized to your Microsoft Sentinel workspace and overwrite any changes you make to that content through the Microsoft Sentinel portal. Your Microsoft Sentinel repositories become your “single source of truth” for custom content in the connected workspaces.
31
44
32
45
## Plan your repository connection
33
46
@@ -44,52 +57,46 @@ Creating a connection to a repository requires an **Owner** role in the resource
44
57
45
58
If you find content in a public repository where you aren't a contributor, first import, fork, or clone the content to a repo where you're a contributor. Then connect your repo to your Microsoft Sentinel workspace. For more information, see [Deploy custom content from your repository](ci-cd.md).
46
59
47
-
## Plan your repository content
48
60
49
-
Repository content must be stored as [Bicep files](../azure-resource-manager/bicep/file.md) or [Azure Resource Manager (ARM) templates](../azure-resource-manager/templates/overview.md). However, Bicep is more intuitive and makes it easier to describe Azure resources and Microsoft Sentinel content.
61
+
### Maximum connections and deployments
50
62
51
-
Deploy Bicep file templates alongside or instead of ARM JSON templates. If you're considering infrastructure as code options, we recommend looking at Bicep. For more information, see [What is Bicep?](../azure-resource-manager/bicep/overview.md).
63
+
- Each Microsoft Sentinel workspace is currently limited to **five repository connections**.
64
+
- Each Azure resource group is limited to **800 deployments** in its deployment history. If you have a high volume of template deployments one or more of your resource groups, you may see the `Deployment QuotaExceeded` error. For more information, see [DeploymentQuotaExceeded](/azure/azure-resource-manager/templates/deployment-quota-exceeded) in the Azure Resource Manager templates documentation.
52
65
53
-
> [!IMPORTANT]
54
-
> In order to use Bicep files, your repositories connection needs to be updated if your connection was created before November 1, 2024. Repositories connections must be [removed](ci-cd.md#remove-a-repository-connection) and recreated in order to update.
66
+
## Plan your repository content
55
67
56
-
Even if your original content is an ARM template, consider converting to Bicep to make the review and update processes less complex. Bicep is closely related to ARM because during a deployment, each Bicep file is converted to an ARM template. For more information on converting ARM templates, see [Decompiling ARM template JSON to Bicep](../azure-resource-manager/bicep/decompile.md).
68
+
Microsoft Sentinel repositories support deployment of content you store as [Bicep files](../azure-resource-manager/bicep/overview.md) or [Azure Resource Manager (ARM) templates](../azure-resource-manager/templates/overview.md). We recommend using Bicep, which is more intuitive and makes it easier to describe Azure resources and Microsoft Sentinel content.
57
69
58
-
> [!NOTE]
59
-
> Known Bicep limitations:
60
-
> - Bicep files don't support the `id` property. When decompiling ARM JSON to Bicep, make sure you don't have this property. For example, analytic rule templates exported from Microsoft Sentinel have the `id` property that needs removal.
61
-
> - Change the ARM JSON schema to version `2019-04-01` for best results when decompiling.
70
+
The template for each content type has a specific structure and parameter name, as documented in the [Sentinel resources template reference](/azure/templates/microsoft.securityinsights/allversions). For samples of each content type, see [RepositoriesSampleContent repository](https://github.com/SentinelCICD/RepositoriesSampleContent).
62
71
63
-
### Validate your content
72
+
We've provided a sample repository with templates for each of the content types listed. The repo also demonstrates how to use advanced features of repository connections. For more information, see [Microsoft Sentinel CI/CD repositories sample](https://github.com/SentinelCICD/RepositoriesSampleContent).
64
73
65
-
The following Microsoft Sentinel content types can be deployed through a repository connection:
66
-
- Analytics rules
67
-
- Automation rules
68
-
- Hunting queries
69
-
- Parsers
70
-
- Playbooks
71
-
- Workbooks
72
-
73
-
> [!IMPORTANT]
74
-
> Analytic rules deployed using The Microsoft Sentinel **Repositories** feature can use cross-workspace queries only if the destination workspace is in the same Resource Group as the workspace connected to the repository.
75
-
>
74
+
:::image type="content" source="media/ci-cd-custom-content/repositories-connection-success.png" alt-text="Screenshot of a successful repository connection. The RepositoriesSampleContent is shown. This screenshot is after the sample was imported from the SentinelCICD repo to a private GitHub repo in the FourthCoffee organization." lightbox="media/ci-cd-custom-content/repositories-connection-success.png":::
76
75
77
-
> [!TIP]
78
-
> This article does *not* describe how to create these types of content from scratch. For more information, see the relevant [Microsoft Sentinel GitHub wiki](https://github.com/Azure/Azure-Sentinel/wiki#get-started) for each content type.
79
-
>
76
+
Although you can build templates from scratch, it's often easier to start from either the Sentinel Public GitHub repository YAML files or from out-of-the-box Microsoft Sentinel content. This table outlines how to convert an ARM template for use with Microsoft Sentinel Repositories.
80
77
81
-
The repositories deployment doesn't validate the content except to confirm it's in the correct JSON or Bicep format. Be sure to test your content within Microsoft Sentinel before deploying.
78
+
| Content Type | Convert from Sentinel Public YAML | Export from Sentinel | Template Reference | Sample Templates |
|**Workbooks**| N/A |[Exporting workbooks as ARM templates](/azure/azure-monitor/visualize/workbooks-automate#arm-template-for-deploying-a-workbook-template)|[Reference](/azure/azure-monitor/visualize/workbooks-automate#arm-template-for-deploying-a-workbook-template)| N/A |
82
86
83
-
A sample repository is available with templates for each of the content types listed. The repo also demonstrates how to use advanced features of repository connections. For more information, see [Microsoft Sentinel CI/CD repositories sample](https://github.com/SentinelCICD/RepositoriesSampleContent).
84
87
88
+
> [!IMPORTANT]
89
+
> Bicep considerations:
90
+
> - To use Bicep files, your repositories connection needs to be updated if your connection was created before November 1, 2024. Repositories connections must be [removed](ci-cd.md#remove-a-repository-connection) and recreated in order to update.
91
+
> - Bicep files don't support the `id` property. When decompiling ARM JSON to Bicep, make sure you don't have this property. For example, analytic rule templates exported from Microsoft Sentinel have the `id` property that needs removal.
92
+
> - Change the ARM JSON schema to version `2019-04-01` for best results when decompiling.
85
93
86
-
:::image type="content" source="media/ci-cd-custom-content/repositories-connection-success.png" alt-text="Screenshot of a successful repository connection. The RepositoriesSampleContent is shown. This screenshot is after the sample was imported from the SentinelCICD repo to a private GitHub repo in the FourthCoffee organization." lightbox="media/ci-cd-custom-content/repositories-connection-success.png":::
87
94
95
+
> [!IMPORTANT]
96
+
> Analytic rules deployed using the Microsoft Sentinel **Repositories** feature can use cross-workspace queries only if the destination workspace is in the same Resource Group as the workspace connected to the repository.
88
97
89
-
### Maximum connections and deployments
90
98
91
-
- Each Microsoft Sentinel workspace is currently limited to **five repository connections**.
92
-
- Each Azure resource group is limited to **800 deployments** in its deployment history. If you have a high volume of template deployments one or more of your resource groups, you may see the `Deployment QuotaExceeded` error. For more information, see [DeploymentQuotaExceeded](/azure/azure-resource-manager/templates/deployment-quota-exceeded) in the Azure Resource Manager templates documentation.
99
+
For information on creating custom content from scratch, see the relevant [Microsoft Sentinel GitHub wiki](https://github.com/Azure/Azure-Sentinel/wiki#get-started) for each content type.
93
100
94
101
95
102
## Improve performance with smart deployments
@@ -126,7 +133,6 @@ Once the workflow or pipeline is triggered, the deployment supports the followin
126
133
127
134
These options are available through a feature of the PowerShell deployment script called from the workflow or pipeline. For more information on how to implement these customizations, see [Customize repository deployments](ci-cd-custom-deploy.md#customize-your-connection-configuration).
128
135
129
-
130
136
## Next steps
131
137
132
138
Get more examples and step by step instructions on deploying Microsoft Sentinel repositories.
Copy file name to clipboardExpand all lines: articles/sentinel/ci-cd-custom-deploy.md
+1-1Lines changed: 1 addition & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -38,7 +38,7 @@ After the connection is made, the following prerequisites apply:
38
38
- Actions enabled for GitHub and Pipelines enabled for Azure DevOps
39
39
- Ensure custom content files you want to deploy to your workspaces are in a supported format. For supported formats, see [Plan your repository content](ci-cd-custom-content.md#plan-your-repository-content).
40
40
41
-
For more information on deployable content types, see [Validate your content](ci-cd-custom-content.md#validate-your-content).
41
+
For more information on deployable content types, see [Plan your repository content](ci-cd-custom-content.md#plan-your-repository-content).
0 commit comments