Create an alert with custom entity mapping using Microsoft Sentinel REST API

As you may know the latest stable Microsoft Sentinel Alert API version 2020-01-01 doesn’t allows you to create an analytics rule in which you can add custom entity mapping, custom detail or incident grouping configuration. It isn’t too helpful for you in the case you would like to do more with the analytics rule or to copy testing rules over to a new Microsoft Sentinel workspace. Fortunately Microsoft has been working on a newer API version to help you enrich the analytics rule.

In this article, I would like to share with you the latest script to help create an analytic rule that you can include custom entity mapping or incident configuration.

The API version 2020-01-01 only allows you to define query, tactic and some basic settings such as query frequency or trigger threshold. It doesn’t give full alert details with mentioned settings when you call GET.

You can use ARM template to create an analytic rule with full details. Refer the article below:

Azure Sentinel Analytics Rule ARM Template

As said earlier, Microsoft is working on a newer version 2021-03-01-preview. With this version you can do much more than what 2020-01-01 allows you.

The sample request body accepted by the preview API is as follows:

  "ruleId": "8e2ce858-2b9e-4583-8a61-81810b55d923",
  "kind": "Scheduled",
  "properties": {
    "query": "let TargetKeyVaults = dynamic ([\"shared-corporate-kv\",\"azsec-kv\"]); AzureDiagnostics | where ResourceProvider =~ \"MICROSOFT.KEYVAULT\" | where Resource in~ (TargetKeyVaults) | project TimeGenerated, OperationName, KeyVaultName = Resource, ResourceGroup, CallerIPAddress, _ResourceId",
    "triggerThreshold": "0",
    "customDetails": {
      "KeyVaultName": "KeyVaultName",
      "OperationName": "OperationName"
    "suppressionDuration": "PT5H",
    "suppressionEnabled": "True",
    "queryPeriod": "PT5H",
    "triggerOperator": "GreaterThan",
    "displayName": "AzSecAAA - Monitor Az Key Vault Operation",
    "queryFrequency": "PT5H",
    "alertDetailsOverride": {
      "alertDescriptionFormat": "{{OperationName}} from {{CallerIPAddress}} on {{KeyVaultName}} Key Vault",
      "alertDisplayNameFormat": "{{OperationName}} from {{CallerIPAddress}} on {{KeyVaultName}} Key Vault"
    "description": "This is the sample rule to monitor KV",
    "severity": "Medium",
    "entityMappings": [
        "fieldMappings": [
            "identifier": "ResourceId",
            "columnName": "_ResourceId"
        "entityType": "AzureResource"
        "fieldMappings": [
            "identifier": "Address",
            "columnName": "CallerIPAddress"
        "entityType": "IP"
    "enabled": "True",
    "tactics": [
    "incidentConfiguration": {
      "groupingConfiguration": {
        "lookbackDuration": "PT5H",
        "matchingMethod": "Selected",
        "groupByCustomDetails": [
        "groupByEntities": [
        "groupByAlertDetails": [
        "reopenClosedIncident": "True",
        "enabled": "True"
      "createIncident": "true"

You can use this script to test alert creation. The script is quite well documented by itself to give you ideas of values each field in the request body is accepted.

There is another script here in case you would like to get full details of an analytic rule.

Migrate alert rules to another Azure Sentinel in the same tenant

If you have any question or feedback please feel free to leave a comment in the Comment box or create a GitHub issue.

This entry was posted in Security Automation and tagged , , . Bookmark the permalink.

Leave a Reply

Your email address will not be published.