Automations - Create Or Update

Service:
Defender for Cloud
API Version:
2023-12-01-preview

Creates or updates a security automation. If a security automation is already created and a subsequent request is issued for the same automation id, then it will be updated.

PUT https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Security/automations/{automationName}?api-version=2023-12-01-preview

URI Parameters

Name In Required Type Description
automationName
 path True

string

The security automation name.
resourceGroupName
 path True

string

minLength: 1
maxLength: 90

The name of the resource group. The name is case insensitive.
subscriptionId
 path True

string (uuid)

The ID of the target subscription. The value must be an UUID.
api-version
 query True

string

minLength: 1

The API version to use for this operation.

Request Body

Name Type Description
etag

string

Entity tag is used for comparing two or more entities from the same requested resource.
kind

string

Kind of the resource
location

string

The geo-location where the resource lives
properties.actions AutomationAction[]:

A collection of the actions which are triggered if all the configured rules evaluations, within at least one rule set, are true.
properties.description

string

The security automation description.
properties.isEnabled

boolean

Indicates whether the security automation is enabled.
properties.scopes

AutomationScope[]

A collection of scopes on which the security automations logic is applied. Supported scopes are the subscription itself or a resource group under that subscription. The automation will only apply on defined scopes.
properties.sources

AutomationSource[]

A collection of the source event types which evaluate the security automation set of rules.
tags

object

Resource tags.

Responses

Name Type Description
200 OK

Automation

Resource 'Automation' update operation succeeded
201 Created

Automation

Resource 'Automation' create operation succeeded
Other Status Codes

Common.CloudError

An unexpected error response.

Security

azure_auth

Azure Active Directory OAuth2 Flow.

Type: oauth2
Flow: implicit
Authorization URL: https://login.microsoftonline.com/common/oauth2/authorize

Scopes

Name Description
user_impersonation impersonate your user account

Examples

Create or update a security automation for all assessments (including all severities)
Create or update a security automation for all high severity assessments
Disable or enable a security automation

Create or update a security automation for all assessments (including all severities)

Sample request

PUT https://management.azure.com/subscriptions/a5caac9c-5c04-49af-b3d0-e204f40345d5/resourceGroups/exampleResourceGroup/providers/Microsoft.Security/automations/exampleAutomation?api-version=2023-12-01-preview

{
  "etag": "etag value (must be supplied for update)",
  "location": "Central US",
  "properties": {
    "description": "An example of a security automation that triggers one LogicApp resource (myTest1) on any security assessment",
    "actions": [
      {
        "actionType": "LogicApp",
        "logicAppResourceId": "/subscriptions/e54a4a18-5b94-4f90-9471-bd3decad8a2e/resourceGroups/sample/providers/Microsoft.Logic/workflows/MyTest1",
        "uri": "https://exampleTriggerUri1.com"
      }
    ],
    "isEnabled": true,
    "scopes": [
      {
        "description": "A description that helps to identify this scope - for example: security assessments that relate to the resource group myResourceGroup within the subscription a5caac9c-5c04-49af-b3d0-e204f40345d5",
        "scopePath": "/subscriptions/a5caac9c-5c04-49af-b3d0-e204f40345d5/resourceGroups/myResourceGroup"
      }
    ],
    "sources": [
      {
        "eventSource": "Assessments"
      }
    ]
  },
  "tags": {}
}

Sample response

Status code:
200 
{
  "name": "exampleAutomation",
  "type": "Microsoft.Security/automations",
  "etag": "new etag value",
  "id": "/subscriptions/a5caac9c-5c04-49af-b3d0-e204f40345d5/resourceGroups/exampleResourceGroup/providers/Microsoft.Security/automations/exampleAutomation",
  "location": "Central US",
  "properties": {
    "description": "An example of a security automation that triggers one LogicApp resource (myTest1) on any security assessment",
    "actions": [
      {
        "actionType": "LogicApp",
        "logicAppResourceId": "/subscriptions/e54a4a18-5b94-4f90-9471-bd3decad8a2e/resourceGroups/sample/providers/Microsoft.Logic/workflows/MyTest1"
      }
    ],
    "isEnabled": true,
    "scopes": [
      {
        "description": "A description that helps to identify this scope - for example: security assessments that relate to the resource group myResourceGroup within the subscription a5caac9c-5c04-49af-b3d0-e204f40345d5",
        "scopePath": "/subscriptions/a5caac9c-5c04-49af-b3d0-e204f40345d5/resourceGroups/myResourceGroup"
      }
    ],
    "sources": [
      {
        "eventSource": "Assessments",
        "ruleSets": []
      }
    ]
  },
  "tags": {}
}
Status code:
201 
{
  "name": "exampleAutomation",
  "type": "Microsoft.Security/SecurityAutomations",
  "etag": "new etag value",
  "id": "/subscriptions/a5caac9c-5c04-49af-b3d0-e204f40345d5/resourceGroups/exampleResourceGroup/providers/Microsoft.Security/SecurityAutomations/exampleAutomation",
  "location": "Central US",
  "properties": {
    "description": "An example of a security automation that triggers one LogicApp resource (myTest1) on any security assessment",
    "actions": [
      {
        "actionType": "LogicApp",
        "logicAppResourceId": "/subscriptions/e54a4a18-5b94-4f90-9471-bd3decad8a2e/resourceGroups/sample/providers/Microsoft.Logic/workflows/MyTest1"
      }
    ],
    "isEnabled": true,
    "scopes": [
      {
        "description": "A description that helps to identify this scope - for example: security assessments that relate to the resource group myResourceGroup within the subscription a5caac9c-5c04-49af-b3d0-e204f40345d5",
        "scopePath": "/subscriptions/a5caac9c-5c04-49af-b3d0-e204f40345d5/resourceGroups/myResourceGroup"
      }
    ],
    "sources": [
      {
        "eventSource": "Assessments",
        "ruleSets": []
      }
    ]
  },
  "tags": {}
}

Create or update a security automation for all high severity assessments

Sample request

PUT https://management.azure.com/subscriptions/a5caac9c-5c04-49af-b3d0-e204f40345d5/resourceGroups/exampleResourceGroup/providers/Microsoft.Security/automations/exampleAutomation?api-version=2023-12-01-preview

{
  "etag": "etag value (must be supplied for update)",
  "location": "Central US",
  "properties": {
    "description": "An example of a security automation that triggers one LogicApp resource (myTest1) on any high severity security assessment",
    "actions": [
      {
        "actionType": "LogicApp",
        "logicAppResourceId": "/subscriptions/e54a4a18-5b94-4f90-9471-bd3decad8a2e/resourceGroups/sample/providers/Microsoft.Logic/workflows/MyTest1",
        "uri": "https://exampleTriggerUri1.com"
      }
    ],
    "isEnabled": true,
    "scopes": [
      {
        "description": "A description that helps to identify this scope - for example: security assessments that relate to the resource group myResourceGroup within the subscription a5caac9c-5c04-49af-b3d0-e204f40345d5",
        "scopePath": "/subscriptions/a5caac9c-5c04-49af-b3d0-e204f40345d5/resourceGroups/myResourceGroup"
      }
    ],
    "sources": [
      {
        "eventSource": "Assessments",
        "ruleSets": [
          {
            "rules": [
              {
                "expectedValue": "High",
                "operator": "Equals",
                "propertyJPath": "properties.metadata.severity",
                "propertyType": "String"
              }
            ]
          }
        ]
      }
    ]
  },
  "tags": {}
}

Sample response

Status code:
200 
{
  "name": "exampleAutomation",
  "type": "Microsoft.Security/automations",
  "etag": "new etag value",
  "id": "/subscriptions/a5caac9c-5c04-49af-b3d0-e204f40345d5/resourceGroups/exampleResourceGroup/providers/Microsoft.Security/automations/exampleAutomation",
  "location": "Central US",
  "properties": {
    "description": "An example of a security automation that triggers one LogicApp resource (myTest1) on any high severity security assessment",
    "actions": [
      {
        "actionType": "LogicApp",
        "logicAppResourceId": "/subscriptions/e54a4a18-5b94-4f90-9471-bd3decad8a2e/resourceGroups/sample/providers/Microsoft.Logic/workflows/MyTest1"
      }
    ],
    "isEnabled": true,
    "scopes": [
      {
        "description": "A description that helps to identify this scope - for example: security assessments that relate to the resource group myResourceGroup within the subscription a5caac9c-5c04-49af-b3d0-e204f40345d5",
        "scopePath": "/subscriptions/a5caac9c-5c04-49af-b3d0-e204f40345d5/resourceGroups/myResourceGroup"
      }
    ],
    "sources": [
      {
        "eventSource": "Assessments",
        "ruleSets": [
          {
            "rules": [
              {
                "expectedValue": "High",
                "operator": "Equals",
                "propertyJPath": "properties.metadata.severity",
                "propertyType": "String"
              }
            ]
          }
        ]
      }
    ]
  },
  "tags": {}
}
Status code:
201 
{
  "name": "exampleAutomation",
  "type": "Microsoft.Security/SecurityAutomations",
  "etag": "new etag value",
  "id": "/subscriptions/a5caac9c-5c04-49af-b3d0-e204f40345d5/resourceGroups/exampleResourceGroup/providers/Microsoft.Security/SecurityAutomations/exampleAutomation",
  "location": "Central US",
  "properties": {
    "description": "An example of a security automation that triggers one LogicApp resource (myTest1) on any high severity security assessment",
    "actions": [
      {
        "actionType": "LogicApp",
        "logicAppResourceId": "/subscriptions/e54a4a18-5b94-4f90-9471-bd3decad8a2e/resourceGroups/sample/providers/Microsoft.Logic/workflows/MyTest1"
      }
    ],
    "isEnabled": true,
    "scopes": [
      {
        "description": "A description that helps to identify this scope - for example: security assessments that relate to the resource group myResourceGroup within the subscription a5caac9c-5c04-49af-b3d0-e204f40345d5",
        "scopePath": "/subscriptions/a5caac9c-5c04-49af-b3d0-e204f40345d5/resourceGroups/myResourceGroup"
      }
    ],
    "sources": [
      {
        "eventSource": "Assessments",
        "ruleSets": [
          {
            "rules": [
              {
                "expectedValue": "High",
                "operator": "Equals",
                "propertyJPath": "properties.metadata.severity",
                "propertyType": "String"
              }
            ]
          }
        ]
      }
    ]
  },
  "tags": {}
}

Disable or enable a security automation

Sample request

PUT https://management.azure.com/subscriptions/a5caac9c-5c04-49af-b3d0-e204f40345d5/resourceGroups/exampleResourceGroup/providers/Microsoft.Security/automations/exampleAutomation?api-version=2023-12-01-preview

{
  "etag": "etag value (must be supplied for update)",
  "location": "Central US",
  "properties": {
    "description": "An example of a security automation that triggers one LogicApp resource (myTest1) on any security assessment of type customAssessment",
    "actions": [
      {
        "actionType": "LogicApp",
        "logicAppResourceId": "/subscriptions/e54a4a18-5b94-4f90-9471-bd3decad8a2e/resourceGroups/sample/providers/Microsoft.Logic/workflows/MyTest1",
        "uri": "https://exampleTriggerUri1.com"
      }
    ],
    "isEnabled": false,
    "scopes": [
      {
        "description": "A description that helps to identify this scope - for example: security assessments that relate to the resource group myResourceGroup within the subscription a5caac9c-5c04-49af-b3d0-e204f40345d5",
        "scopePath": "/subscriptions/a5caac9c-5c04-49af-b3d0-e204f40345d5/resourceGroups/myResourceGroup"
      }
    ],
    "sources": [
      {
        "eventSource": "Assessments",
        "ruleSets": [
          {
            "rules": [
              {
                "expectedValue": "customAssessment",
                "operator": "Equals",
                "propertyJPath": "$.Entity.AssessmentType",
                "propertyType": "String"
              }
            ]
          }
        ]
      }
    ]
  },
  "tags": {}
}

Sample response

Status code:
200 
{
  "name": "exampleAutomation",
  "type": "Microsoft.Security/automations",
  "etag": "new etag value",
  "id": "/subscriptions/a5caac9c-5c04-49af-b3d0-e204f40345d5/resourceGroups/exampleResourceGroup/providers/Microsoft.Security/automations/exampleAutomation",
  "location": "Central US",
  "properties": {
    "description": "An example of a security automation that triggers one LogicApp resource (myTest1) on any security assessment of type customAssessment",
    "actions": [
      {
        "actionType": "LogicApp",
        "logicAppResourceId": "/subscriptions/e54a4a18-5b94-4f90-9471-bd3decad8a2e/resourceGroups/sample/providers/Microsoft.Logic/workflows/MyTest1"
      }
    ],
    "isEnabled": false,
    "scopes": [
      {
        "description": "A description that helps to identify this scope - for example: security assessments that relate to the resource group myResourceGroup within the subscription a5caac9c-5c04-49af-b3d0-e204f40345d5",
        "scopePath": "/subscriptions/a5caac9c-5c04-49af-b3d0-e204f40345d5/resourceGroups/myResourceGroup"
      }
    ],
    "sources": [
      {
        "eventSource": "Assessments",
        "ruleSets": [
          {
            "rules": [
              {
                "expectedValue": "customAssessment",
                "operator": "Equals",
                "propertyJPath": "$.Entity.AssessmentType",
                "propertyType": "String"
              }
            ]
          }
        ]
      }
    ]
  },
  "tags": {}
}
Status code:
201 
{
  "name": "exampleAutomation",
  "type": "Microsoft.Security/SecurityAutomations",
  "etag": "new etag value",
  "id": "/subscriptions/a5caac9c-5c04-49af-b3d0-e204f40345d5/resourceGroups/exampleResourceGroup/providers/Microsoft.Security/SecurityAutomations/exampleAutomation",
  "location": "Central US",
  "properties": {
    "description": "An example of a security automation that triggers one LogicApp resource (myTest1) on any security assessment of type customAssessment",
    "actions": [
      {
        "actionType": "LogicApp",
        "logicAppResourceId": "/subscriptions/e54a4a18-5b94-4f90-9471-bd3decad8a2e/resourceGroups/sample/providers/Microsoft.Logic/workflows/MyTest1"
      }
    ],
    "isEnabled": false,
    "scopes": [
      {
        "description": "A description that helps to identify this scope - for example: security assessments that relate to the resource group myResourceGroup within the subscription a5caac9c-5c04-49af-b3d0-e204f40345d5",
        "scopePath": "/subscriptions/a5caac9c-5c04-49af-b3d0-e204f40345d5/resourceGroups/myResourceGroup"
      }
    ],
    "sources": [
      {
        "eventSource": "Assessments",
        "ruleSets": [
          {
            "rules": [
              {
                "expectedValue": "customAssessment",
                "operator": "Equals",
                "propertyJPath": "$.Entity.AssessmentType",
                "propertyType": "String"
              }
            ]
          }
        ]
      }
    ]
  },
  "tags": {}
}

Definitions

Name Description
Automation

The security automation resource.
AutomationActionEventHub

The target Event Hub to which event data will be exported. To learn more about Microsoft Defender for Cloud continuous export capabilities, visit https://aka.ms/ASCExportLearnMore
AutomationActionLogicApp

The logic app action that should be triggered. To learn more about Microsoft Defender for Cloud's Workflow Automation capabilities, visit https://aka.ms/ASCWorkflowAutomationLearnMore
AutomationActionWorkspace

The Log Analytics Workspace to which event data will be exported. Security alerts data will reside in the 'SecurityAlert' table and the assessments data will reside in the 'SecurityRecommendation' table (under the 'Security'/'SecurityCenterFree' solutions). Note that in order to view the data in the workspace, the Security Center Log Analytics free/standard solution needs to be enabled on that workspace. To learn more about Microsoft Defender for Cloud continuous export capabilities, visit https://aka.ms/ASCExportLearnMore
AutomationRuleSet

A rule set which evaluates all its rules upon an event interception. Only when all the included rules in the rule set will be evaluated as 'true', will the event trigger the defined actions.
AutomationScope

A single automation scope.
AutomationSource

The source event types which evaluate the security automation set of rules. For example - security alerts and security assessments. To learn more about the supported security events data models schemas - please visit https://aka.ms/ASCAutomationSchemas.
AutomationTriggeringRule

A rule which is evaluated upon event interception. The rule is configured by comparing a specific value from the event model to an expected value. This comparison is done by using one of the supported operators set.
Common.CloudError

Common error response for all Azure Resource Manager APIs to return error details for failed operations. (This also follows the OData error response format.).
Common.CloudErrorBody

The error detail.
createdByType

The type of identity that created the resource.
ErrorAdditionalInfo

The resource management error additional info.
EventSource

A valid event source type.
Operator

A valid comparer operator to use. A case-insensitive comparison will be applied for String PropertyType.
PropertyType

The data type of the compared operands (string, integer, floating point number or a boolean [true/false]]
systemData

Metadata pertaining to creation and last modification of the resource.

Automation

Object

The security automation resource.

Name Type Description
etag

string

Entity tag is used for comparing two or more entities from the same requested resource.
id

string (arm-id)

Fully qualified resource ID for the resource. E.g. "/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/{resourceProviderNamespace}/{resourceType}/{resourceName}"
kind

string

Kind of the resource
location

string

The geo-location where the resource lives
name

string

The name of the resource
properties.actions AutomationAction[]:

A collection of the actions which are triggered if all the configured rules evaluations, within at least one rule set, are true.
properties.description

string

The security automation description.
properties.isEnabled

boolean

Indicates whether the security automation is enabled.
properties.scopes

AutomationScope[]

A collection of scopes on which the security automations logic is applied. Supported scopes are the subscription itself or a resource group under that subscription. The automation will only apply on defined scopes.
properties.sources

AutomationSource[]

A collection of the source event types which evaluate the security automation set of rules.
systemData

systemData

Azure Resource Manager metadata containing createdBy and modifiedBy information.
tags

object

Resource tags.
type

string

The type of the resource. E.g. "Microsoft.Compute/virtualMachines" or "Microsoft.Storage/storageAccounts"

AutomationActionEventHub

Object

The target Event Hub to which event data will be exported. To learn more about Microsoft Defender for Cloud continuous export capabilities, visit https://aka.ms/ASCExportLearnMore

Name Type Description
actionType string:

EventHub

The type of the action that will be triggered by the Automation
connectionString

string

The target Event Hub connection string (it will not be included in any response).
eventHubResourceId

string

The target Event Hub Azure Resource ID.
isTrustedServiceEnabled

boolean

Indicates whether the trusted service is enabled or not.
sasPolicyName

string

The target Event Hub SAS policy name.

AutomationActionLogicApp

Object

The logic app action that should be triggered. To learn more about Microsoft Defender for Cloud's Workflow Automation capabilities, visit https://aka.ms/ASCWorkflowAutomationLearnMore

Name Type Description
actionType string:

LogicApp

The type of the action that will be triggered by the Automation
logicAppResourceId

string

The triggered Logic App Azure Resource ID. This can also reside on other subscriptions, given that you have permissions to trigger the Logic App
uri

string (uri)

The Logic App trigger URI endpoint (it will not be included in any response).

AutomationActionWorkspace

Object

The Log Analytics Workspace to which event data will be exported. Security alerts data will reside in the 'SecurityAlert' table and the assessments data will reside in the 'SecurityRecommendation' table (under the 'Security'/'SecurityCenterFree' solutions). Note that in order to view the data in the workspace, the Security Center Log Analytics free/standard solution needs to be enabled on that workspace. To learn more about Microsoft Defender for Cloud continuous export capabilities, visit https://aka.ms/ASCExportLearnMore

Name Type Description
actionType string:

Workspace

The type of the action that will be triggered by the Automation
workspaceResourceId

string

The fully qualified Log Analytics Workspace Azure Resource ID.

AutomationRuleSet

Object

A rule set which evaluates all its rules upon an event interception. Only when all the included rules in the rule set will be evaluated as 'true', will the event trigger the defined actions.

Name Type Description
rules

AutomationTriggeringRule[]

A rule which is evaluated upon event interception. The rule is configured by comparing a specific value from the event model to an expected value. This comparison is done by using one of the supported operators set.

AutomationScope

Object

A single automation scope.

Name Type Description
description

string

The resources scope description.
scopePath

string

The resources scope path. Can be the subscription on which the automation is defined on or a resource group under that subscription (fully qualified Azure resource IDs).

AutomationSource

Object

The source event types which evaluate the security automation set of rules. For example - security alerts and security assessments. To learn more about the supported security events data models schemas - please visit https://aka.ms/ASCAutomationSchemas.

Name Type Description
eventSource

EventSource

A valid event source type.
ruleSets

AutomationRuleSet[]

A set of rules which evaluate upon event interception. A logical disjunction is applied between defined rule sets (logical 'or').

AutomationTriggeringRule

Object

A rule which is evaluated upon event interception. The rule is configured by comparing a specific value from the event model to an expected value. This comparison is done by using one of the supported operators set.

Name Type Description
expectedValue

string

The expected value.
operator

Operator

A valid comparer operator to use. A case-insensitive comparison will be applied for String PropertyType.
propertyJPath

string

The JPath of the entity model property that should be checked.
propertyType

PropertyType

The data type of the compared operands (string, integer, floating point number or a boolean [true/false]]

Common.CloudError

Object

Common error response for all Azure Resource Manager APIs to return error details for failed operations. (This also follows the OData error response format.).

Name Type Description
error.additionalInfo

ErrorAdditionalInfo[]

The error additional info.
error.code

string

The error code.
error.details

Common.CloudErrorBody[]

The error details.
error.message

string

The error message.
error.target

string

The error target.

Common.CloudErrorBody

Object

The error detail.

Name Type Description
additionalInfo

ErrorAdditionalInfo[]

The error additional info.
code

string

The error code.
details

Common.CloudErrorBody[]

The error details.
message

string

The error message.
target

string

The error target.

createdByType

Enumeration

The type of identity that created the resource.

Value Description
User
Application
ManagedIdentity
Key

ErrorAdditionalInfo

Object

The resource management error additional info.

Name Type Description
info

object

The additional info.
type

string

The additional info type.

EventSource

Enumeration

A valid event source type.

Value Description
Assessments

Assessments
AssessmentsSnapshot

AssessmentsSnapshot
SubAssessments

SubAssessments
SubAssessmentsSnapshot

SubAssessmentsSnapshot
Alerts

Alerts
SecureScores

SecureScores
SecureScoresSnapshot

SecureScoresSnapshot
SecureScoreControls

SecureScoreControls
SecureScoreControlsSnapshot

SecureScoreControlsSnapshot
RegulatoryComplianceAssessment

RegulatoryComplianceAssessment
RegulatoryComplianceAssessmentSnapshot

RegulatoryComplianceAssessmentSnapshot
AttackPaths

AttackPaths
AttackPathsSnapshot

AttackPathsSnapshot

Operator

Enumeration

A valid comparer operator to use. A case-insensitive comparison will be applied for String PropertyType.

Value Description
Equals

Applies for decimal and non-decimal operands
GreaterThan

Applies only for decimal operands
GreaterThanOrEqualTo

Applies only for decimal operands
LesserThan

Applies only for decimal operands
LesserThanOrEqualTo

Applies only for decimal operands
NotEquals

Applies for decimal and non-decimal operands
Contains

Applies only for non-decimal operands
StartsWith

Applies only for non-decimal operands
EndsWith

Applies only for non-decimal operands

PropertyType

Enumeration

The data type of the compared operands (string, integer, floating point number or a boolean [true/false]]

Value Description
String

String
Integer

Integer
Number

Number
Boolean

Boolean

systemData

Object

Metadata pertaining to creation and last modification of the resource.

Name Type Description
createdAt

string (date-time)

The timestamp of resource creation (UTC).
createdBy

string

The identity that created the resource.
createdByType

createdByType

The type of identity that created the resource.
lastModifiedAt

string (date-time)

The timestamp of resource last modification (UTC)
lastModifiedBy

string

The identity that last modified the resource.
lastModifiedByType

createdByType

The type of identity that last modified the resource.