Assessments - Create Or Update

Create a security assessment on your resource. An assessment metadata that describes this assessment must be predefined with the same name before inserting the assessment result

PUT https://management.azure.com/{resourceId}/providers/Microsoft.Security/assessments/{assessmentName}?api-version=2020-01-01

URI Parameters

Name In Required Type Description
assessmentName
path True

string

The Assessment Key - Unique key for the assessment type

resourceId
path True

string

The identifier of the resource.

api-version
query True

string

API version for the operation

Request Body

Name Required Type Description
properties.resourceDetails True ResourceDetails:

Details of the resource that was assessed

properties.status True

AssessmentStatus

The result of the assessment

properties.additionalData

object

Additional data regarding the assessment

properties.metadata

SecurityAssessmentMetadataProperties

Describes properties of an assessment metadata.

properties.partnersData

SecurityAssessmentPartnerData

Data regarding 3rd party partner integration

Responses

Name Type Description
200 OK

SecurityAssessment

OK - Updated

201 Created

SecurityAssessment

Created

Other Status Codes

CloudError

Error response describing 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 security recommendation task on a resource

Sample request

PUT https://management.azure.com/subscriptions/20ff7fc3-e762-44dd-bd96-b71116dcdc23/resourceGroups/myRg/providers/Microsoft.Compute/virtualMachineScaleSets/vmss2/providers/Microsoft.Security/assessments/8bb8be0a-6010-4789-812f-e4d661c4ed0e?api-version=2020-01-01

{
  "properties": {
    "resourceDetails": {
      "source": "Azure"
    },
    "status": {
      "code": "Healthy"
    }
  }
}

Sample response

{
  "id": "/subscriptions/20ff7fc3-e762-44dd-bd96-b71116dcdc23/resourceGroups/myRg/providers/Microsoft.Compute/virtualMachineScaleSets/vmss1/providers/Microsoft.Security/assessments/8bb8be0a-6010-4789-812f-e4d661c4ed0e",
  "name": "8bb8be0a-6010-4789-812f-e4d661c4ed0e",
  "type": "Microsoft.Security/assessments",
  "properties": {
    "resourceDetails": {
      "source": "Azure",
      "id": "/subscriptions/20ff7fc3-e762-44dd-bd96-b71116dcdc23/resourceGroups/myRg/providers/Microsoft.Compute/virtualMachineScaleSets/vmss1/providers/Microsoft.Security/assessments/8bb8be0a-6010-4789-812f-e4d661c4ed0e"
    },
    "displayName": "Install internal agent on VM",
    "status": {
      "code": "Healthy"
    }
  }
}
{
  "id": "/subscriptions/20ff7fc3-e762-44dd-bd96-b71116dcdc23/resourceGroups/myRg/providers/Microsoft.Compute/virtualMachineScaleSets/vmss1/providers/Microsoft.Security/assessments/8bb8be0a-6010-4789-812f-e4d661c4ed0e",
  "name": "8bb8be0a-6010-4789-812f-e4d661c4ed0e",
  "type": "Microsoft.Security/assessments",
  "properties": {
    "resourceDetails": {
      "source": "Azure",
      "id": "/subscriptions/20ff7fc3-e762-44dd-bd96-b71116dcdc23/resourceGroups/myRg/providers/Microsoft.Compute/virtualMachineScaleSets/vmss1/providers/Microsoft.Security/assessments/8bb8be0a-6010-4789-812f-e4d661c4ed0e"
    },
    "displayName": "Install internal agent on VM",
    "status": {
      "code": "Healthy"
    }
  }
}

Definitions

Name Description
AssessmentLinks

Links relevant to the assessment

AssessmentStatus

The result of the assessment

AssessmentStatusCode

Programmatic code for the status of the assessment

assessmentType

BuiltIn if the assessment based on built-in Azure Policy definition, Custom if the assessment based on custom Azure Policy definition

AzureResourceDetails

Details of the Azure resource that was assessed

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

implementationEffort

The implementation effort required to remediate this assessment

OnPremiseResourceDetails

Details of the On Premise resource that was assessed

OnPremiseSqlResourceDetails

Details of the On Premise Sql resource that was assessed

SecurityAssessment

Security assessment on a resource

SecurityAssessmentMetadataPartnerData

Describes the partner that created the assessment

SecurityAssessmentMetadataProperties

Describes properties of an assessment metadata.

SecurityAssessmentPartnerData

Data regarding 3rd party partner integration

severity

The severity level of the assessment

threats
userImpact

The user impact of the assessment

Links relevant to the assessment

Name Type Description
azurePortalUri

string

Link to assessment in Azure Portal

AssessmentStatus

The result of the assessment

Name Type Description
cause

string

Programmatic code for the cause of the assessment status

code

AssessmentStatusCode

Programmatic code for the status of the assessment

description

string

Human readable description of the assessment status

AssessmentStatusCode

Programmatic code for the status of the assessment

Name Type Description
Healthy

string

The resource is healthy

NotApplicable

string

Assessment for this resource did not happen

Unhealthy

string

The resource has a security issue that needs to be addressed

assessmentType

BuiltIn if the assessment based on built-in Azure Policy definition, Custom if the assessment based on custom Azure Policy definition

Name Type Description
BuiltIn

string

Microsoft Defender for Cloud managed assessments

CustomPolicy

string

User defined policies that are automatically ingested from Azure Policy to Microsoft Defender for Cloud

CustomerManaged

string

User assessments pushed directly by the user or other third party to Microsoft Defender for Cloud

VerifiedPartner

string

An assessment that was created by a verified 3rd party if the user connected it to ASC

AzureResourceDetails

Details of the Azure resource that was assessed

Name Type Description
id

string

Azure resource Id of the assessed resource

source string:

Azure

The platform where the assessed resource resides

categories

Name Type Description
Compute

string

Data

string

IdentityAndAccess

string

IoT

string

Networking

string

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.

implementationEffort

The implementation effort required to remediate this assessment

Name Type Description
High

string

Low

string

Moderate

string

OnPremiseResourceDetails

Details of the On Premise resource that was assessed

Name Type Description
machineName

string

The name of the machine

source string:

OnPremise

The platform where the assessed resource resides

sourceComputerId

string

The oms agent Id installed on the machine

vmuuid

string

The unique Id of the machine

workspaceId

string

Azure resource Id of the workspace the machine is attached to

OnPremiseSqlResourceDetails

Details of the On Premise Sql resource that was assessed

Name Type Description
databaseName

string

The Sql database name installed on the machine

machineName

string

The name of the machine

serverName

string

The Sql server name installed on the machine

source string:

OnPremiseSql

The platform where the assessed resource resides

sourceComputerId

string

The oms agent Id installed on the machine

vmuuid

string

The unique Id of the machine

workspaceId

string

Azure resource Id of the workspace the machine is attached to

SecurityAssessment

Security assessment on a resource

Name Type Description
id

string

Resource Id

name

string

Resource name

properties.additionalData

object

Additional data regarding the assessment

properties.displayName

string

User friendly display name of the assessment

properties.links

AssessmentLinks

Links relevant to the assessment

properties.metadata

SecurityAssessmentMetadataProperties

Describes properties of an assessment metadata.

properties.partnersData

SecurityAssessmentPartnerData

Data regarding 3rd party partner integration

properties.resourceDetails ResourceDetails:

Details of the resource that was assessed

properties.status

AssessmentStatus

The result of the assessment

type

string

Resource type

SecurityAssessmentMetadataPartnerData

Describes the partner that created the assessment

Name Type Description
partnerName

string

Name of the company of the partner

productName

string

Name of the product of the partner that created the assessment

secret

string

Secret to authenticate the partner and verify it created the assessment - write only

SecurityAssessmentMetadataProperties

Describes properties of an assessment metadata.

Name Type Description
assessmentType

assessmentType

BuiltIn if the assessment based on built-in Azure Policy definition, Custom if the assessment based on custom Azure Policy definition

categories

categories[]

The categories of resource that is at risk when the assessment is unhealthy

description

string

Human readable description of the assessment

displayName

string

User friendly display name of the assessment

implementationEffort

implementationEffort

The implementation effort required to remediate this assessment

partnerData

SecurityAssessmentMetadataPartnerData

Describes the partner that created the assessment

policyDefinitionId

string

Azure resource ID of the policy definition that turns this assessment calculation on

preview

boolean

True if this assessment is in preview release status

remediationDescription

string

Human readable description of what you should do to mitigate this security issue

severity

severity

The severity level of the assessment

threats

threats[]

Threats impact of the assessment

userImpact

userImpact

The user impact of the assessment

SecurityAssessmentPartnerData

Data regarding 3rd party partner integration

Name Type Description
partnerName

string

Name of the company of the partner

secret

string

secret to authenticate the partner - write only

severity

The severity level of the assessment

Name Type Description
High

string

Low

string

Medium

string

threats

Name Type Description
accountBreach

string

dataExfiltration

string

dataSpillage

string

denialOfService

string

elevationOfPrivilege

string

maliciousInsider

string

missingCoverage

string

threatResistance

string

userImpact

The user impact of the assessment

Name Type Description
High

string

Low

string

Moderate

string