Assessments - Create Or Update

Reference

Service:: Defender for Cloud

API Version:: 2020-01-01

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: OnPremiseResourceDetails AzureResourceDetails OnPremiseSqlResourceDetails	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

HTTP

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

Status code:: 200

{
  "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"
    }
  }
}

Status code:: 201

{
  "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

AssessmentLinks

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

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: AzureResourceDetails OnPremiseResourceDetails OnPremiseSqlResourceDetails	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

Share via