Automations - Create Or Update

  • Reference
Service:
Defender for Cloud
API Version:
2019-01-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=2019-01-01-preview

URI Parameters

Name In Required Type Description
automationName
 path True

string

The security automation name.
resourceGroupName
 path True

string

The name of the resource group within the user's subscription. The name is case insensitive.

Regex pattern: ^[-\w\._\(\)]+$
subscriptionId
 path True

string

Azure subscription ID

Regex pattern: ^[0-9A-Fa-f]{8}-([0-9A-Fa-f]{4}-){3}[0-9A-Fa-f]{12}$
api-version
 query True

string

API version for the 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

Location where the resource is stored
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

A list of key value pairs that describe the resource.

Responses

Name Type Description
200 OK

Automation

OK
201 Created

Automation

Created
Other Status Codes

CloudError

Error response that describes why the operation failed.

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=2019-01-01-preview

{
  "location": "Central US",
  "etag": "etag value (must be supplied for update)",
  "tags": {},
  "properties": {
    "description": "An example of a security automation that triggers one LogicApp resource (myTest1) on any security assessment",
    "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"
      }
    ],
    "actions": [
      {
        "logicAppResourceId": "/subscriptions/e54a4a18-5b94-4f90-9471-bd3decad8a2e/resourceGroups/sample/providers/Microsoft.Logic/workflows/MyTest1",
        "actionType": "LogicApp",
        "uri": "https://exampleTriggerUri1.com"
      }
    ]
  }
}

Sample Response

Status code:
200 
{
  "id": "/subscriptions/a5caac9c-5c04-49af-b3d0-e204f40345d5/resourceGroups/exampleResourceGroup/providers/Microsoft.Security/automations/exampleAutomation",
  "name": "exampleAutomation",
  "type": "Microsoft.Security/automations",
  "location": "Central US",
  "etag": "new etag value",
  "tags": {},
  "properties": {
    "description": "An example of a security automation that triggers one LogicApp resource (myTest1) on any security assessment",
    "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": []
      }
    ],
    "actions": [
      {
        "logicAppResourceId": "/subscriptions/e54a4a18-5b94-4f90-9471-bd3decad8a2e/resourceGroups/sample/providers/Microsoft.Logic/workflows/MyTest1",
        "actionType": "LogicApp"
      }
    ]
  }
}
Status code:
201 
{
  "id": "/subscriptions/a5caac9c-5c04-49af-b3d0-e204f40345d5/resourceGroups/exampleResourceGroup/providers/Microsoft.Security/SecurityAutomations/exampleAutomation",
  "name": "exampleAutomation",
  "type": "Microsoft.Security/SecurityAutomations",
  "location": "Central US",
  "etag": "new etag value",
  "tags": {},
  "properties": {
    "description": "An example of a security automation that triggers one LogicApp resource (myTest1) on any security assessment",
    "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": []
      }
    ],
    "actions": [
      {
        "logicAppResourceId": "/subscriptions/e54a4a18-5b94-4f90-9471-bd3decad8a2e/resourceGroups/sample/providers/Microsoft.Logic/workflows/MyTest1",
        "actionType": "LogicApp"
      }
    ]
  }
}

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=2019-01-01-preview

{
  "location": "Central US",
  "etag": "etag value (must be supplied for update)",
  "tags": {},
  "properties": {
    "description": "An example of a security automation that triggers one LogicApp resource (myTest1) on any high severity security assessment",
    "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": [
              {
                "propertyJPath": "properties.metadata.severity",
                "propertyType": "String",
                "expectedValue": "High",
                "operator": "Equals"
              }
            ]
          }
        ]
      }
    ],
    "actions": [
      {
        "logicAppResourceId": "/subscriptions/e54a4a18-5b94-4f90-9471-bd3decad8a2e/resourceGroups/sample/providers/Microsoft.Logic/workflows/MyTest1",
        "actionType": "LogicApp",
        "uri": "https://exampleTriggerUri1.com"
      }
    ]
  }
}

Sample Response

Status code:
200 
{
  "id": "/subscriptions/a5caac9c-5c04-49af-b3d0-e204f40345d5/resourceGroups/exampleResourceGroup/providers/Microsoft.Security/automations/exampleAutomation",
  "name": "exampleAutomation",
  "type": "Microsoft.Security/automations",
  "location": "Central US",
  "etag": "new etag value",
  "tags": {},
  "properties": {
    "description": "An example of a security automation that triggers one LogicApp resource (myTest1) on any high severity security assessment",
    "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": [
              {
                "propertyJPath": "properties.metadata.severity",
                "propertyType": "String",
                "expectedValue": "High",
                "operator": "Equals"
              }
            ]
          }
        ]
      }
    ],
    "actions": [
      {
        "logicAppResourceId": "/subscriptions/e54a4a18-5b94-4f90-9471-bd3decad8a2e/resourceGroups/sample/providers/Microsoft.Logic/workflows/MyTest1",
        "actionType": "LogicApp"
      }
    ]
  }
}
Status code:
201 
{
  "id": "/subscriptions/a5caac9c-5c04-49af-b3d0-e204f40345d5/resourceGroups/exampleResourceGroup/providers/Microsoft.Security/SecurityAutomations/exampleAutomation",
  "name": "exampleAutomation",
  "type": "Microsoft.Security/SecurityAutomations",
  "location": "Central US",
  "etag": "new etag value",
  "tags": {},
  "properties": {
    "description": "An example of a security automation that triggers one LogicApp resource (myTest1) on any high severity security assessment",
    "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": [
              {
                "propertyJPath": "properties.metadata.severity",
                "propertyType": "String",
                "expectedValue": "High",
                "operator": "Equals"
              }
            ]
          }
        ]
      }
    ],
    "actions": [
      {
        "logicAppResourceId": "/subscriptions/e54a4a18-5b94-4f90-9471-bd3decad8a2e/resourceGroups/sample/providers/Microsoft.Logic/workflows/MyTest1",
        "actionType": "LogicApp"
      }
    ]
  }
}

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=2019-01-01-preview

{
  "location": "Central US",
  "etag": "etag value (must be supplied for update)",
  "tags": {},
  "properties": {
    "description": "An example of a security automation that triggers one LogicApp resource (myTest1) on any security assessment of type customAssessment",
    "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": [
              {
                "propertyJPath": "$.Entity.AssessmentType",
                "propertyType": "String",
                "expectedValue": "customAssessment",
                "operator": "Equals"
              }
            ]
          }
        ]
      }
    ],
    "actions": [
      {
        "logicAppResourceId": "/subscriptions/e54a4a18-5b94-4f90-9471-bd3decad8a2e/resourceGroups/sample/providers/Microsoft.Logic/workflows/MyTest1",
        "actionType": "LogicApp",
        "uri": "https://exampleTriggerUri1.com"
      }
    ]
  }
}

Sample Response

Status code:
200 
{
  "id": "/subscriptions/a5caac9c-5c04-49af-b3d0-e204f40345d5/resourceGroups/exampleResourceGroup/providers/Microsoft.Security/automations/exampleAutomation",
  "name": "exampleAutomation",
  "type": "Microsoft.Security/automations",
  "location": "Central US",
  "etag": "new etag value",
  "tags": {},
  "properties": {
    "description": "An example of a security automation that triggers one LogicApp resource (myTest1) on any security assessment of type customAssessment",
    "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": [
              {
                "propertyJPath": "$.Entity.AssessmentType",
                "propertyType": "String",
                "expectedValue": "customAssessment",
                "operator": "Equals"
              }
            ]
          }
        ]
      }
    ],
    "actions": [
      {
        "logicAppResourceId": "/subscriptions/e54a4a18-5b94-4f90-9471-bd3decad8a2e/resourceGroups/sample/providers/Microsoft.Logic/workflows/MyTest1",
        "actionType": "LogicApp"
      }
    ]
  }
}
Status code:
201 
{
  "id": "/subscriptions/a5caac9c-5c04-49af-b3d0-e204f40345d5/resourceGroups/exampleResourceGroup/providers/Microsoft.Security/SecurityAutomations/exampleAutomation",
  "name": "exampleAutomation",
  "type": "Microsoft.Security/SecurityAutomations",
  "location": "Central US",
  "etag": "new etag value",
  "tags": {},
  "properties": {
    "description": "An example of a security automation that triggers one LogicApp resource (myTest1) on any security assessment of type customAssessment",
    "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": [
              {
                "propertyJPath": "$.Entity.AssessmentType",
                "propertyType": "String",
                "expectedValue": "customAssessment",
                "operator": "Equals"
              }
            ]
          }
        ]
      }
    ],
    "actions": [
      {
        "logicAppResourceId": "/subscriptions/e54a4a18-5b94-4f90-9471-bd3decad8a2e/resourceGroups/sample/providers/Microsoft.Logic/workflows/MyTest1",
        "actionType": "LogicApp"
      }
    ]
  }
}

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.
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.).
CloudErrorBody

The error detail.
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]]

Automation

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

Resource Id
kind

string

Kind of the resource
location

string

Location where the resource is stored
name

string

Resource name
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

A list of key value pairs that describe the resource.
type

string

Resource type

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

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.
sasPolicyName

string

The target Event Hub SAS policy name.

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

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

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

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

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

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

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

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

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]]

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.).

Name Type Description
error.additionalInfo

ErrorAdditionalInfo[]

The error additional info.
error.code

string

The error code.
error.details

CloudErrorBody[]

The error details.
error.message

string

The error message.
error.target

string

The error target.

CloudErrorBody

The error detail.

Name Type Description
additionalInfo

ErrorAdditionalInfo[]

The error additional info.
code

string

The error code.
details

CloudErrorBody[]

The error details.
message

string

The error message.
target

string

The error target.

ErrorAdditionalInfo

The resource management error additional info.

Name Type Description
info

object

The additional info.
type

string

The additional info type.

EventSource

A valid event source type.

Name Type Description
Alerts

string

Assessments

string

AssessmentsSnapshot

string

RegulatoryComplianceAssessment

string

RegulatoryComplianceAssessmentSnapshot

string

SecureScoreControls

string

SecureScoreControlsSnapshot

string

SecureScores

string

SecureScoresSnapshot

string

SubAssessments

string

SubAssessmentsSnapshot

string

Operator

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

Name Type Description
Contains

string

Applies only for non-decimal operands
EndsWith

string

Applies only for non-decimal operands
Equals

string

Applies for decimal and non-decimal operands
GreaterThan

string

Applies only for decimal operands
GreaterThanOrEqualTo

string

Applies only for decimal operands
LesserThan

string

Applies only for decimal operands
LesserThanOrEqualTo

string

Applies only for decimal operands
NotEquals

string

Applies for decimal and non-decimal operands
StartsWith

string

Applies only for non-decimal operands

PropertyType

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

Name Type Description
Boolean

string

Integer

string

Number

string

String

string