Assessments - Create Or Update

Service:: Defender for Cloud

API Version:: 2021-06-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=2021-06-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	SecurityAssessmentResponse	OK - Updated
201 Created	SecurityAssessmentResponse	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=2021-06-01

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


import com.azure.resourcemanager.security.models.AssessmentStatus;
import com.azure.resourcemanager.security.models.AssessmentStatusCode;
import com.azure.resourcemanager.security.models.AzureResourceDetails;

/**
 * Samples for Assessments CreateOrUpdate.
 */
public final class Main {
    /*
     * x-ms-original-file:
     * specification/security/resource-manager/Microsoft.Security/stable/2021-06-01/examples/Assessments/
     * PutAssessment_example.json
     */
    /**
     * Sample code: Create security recommendation task on a resource.
     * 
     * @param manager Entry point to SecurityManager.
     */
    public static void
        createSecurityRecommendationTaskOnAResource(com.azure.resourcemanager.security.SecurityManager manager) {
        manager.assessments().define("8bb8be0a-6010-4789-812f-e4d661c4ed0e").withExistingResourceId(
            "subscriptions/20ff7fc3-e762-44dd-bd96-b71116dcdc23/resourceGroups/myRg/providers/Microsoft.Compute/virtualMachineScaleSets/vmss2")
            .withStatus(new AssessmentStatus().withCode(AssessmentStatusCode.HEALTHY))
            .withResourceDetails(new AzureResourceDetails()).create();
    }
}

To use the Azure SDK library in your project, see this documentation. To provide feedback on this code sample, open a GitHub issue

package armsecurity_test

import (
	"context"
	"log"

	"github.com/Azure/azure-sdk-for-go/sdk/azcore/to"
	"github.com/Azure/azure-sdk-for-go/sdk/azidentity"
	"github.com/Azure/azure-sdk-for-go/sdk/resourcemanager/security/armsecurity"
)

// Generated from example definition: https://github.com/Azure/azure-rest-api-specs/blob/9ac34f238dd6b9071f486b57e9f9f1a0c43ec6f6/specification/security/resource-manager/Microsoft.Security/stable/2021-06-01/examples/Assessments/PutAssessment_example.json
func ExampleAssessmentsClient_CreateOrUpdate() {
	cred, err := azidentity.NewDefaultAzureCredential(nil)
	if err != nil {
		log.Fatalf("failed to obtain a credential: %v", err)
	}
	ctx := context.Background()
	clientFactory, err := armsecurity.NewClientFactory("<subscription-id>", cred, nil)
	if err != nil {
		log.Fatalf("failed to create client: %v", err)
	}
	res, err := clientFactory.NewAssessmentsClient().CreateOrUpdate(ctx, "subscriptions/20ff7fc3-e762-44dd-bd96-b71116dcdc23/resourceGroups/myRg/providers/Microsoft.Compute/virtualMachineScaleSets/vmss2", "8bb8be0a-6010-4789-812f-e4d661c4ed0e", armsecurity.Assessment{
		Properties: &armsecurity.AssessmentProperties{
			ResourceDetails: &armsecurity.AzureResourceDetails{
				Source: to.Ptr(armsecurity.SourceAzure),
			},
			Status: &armsecurity.AssessmentStatus{
				Code: to.Ptr(armsecurity.AssessmentStatusCodeHealthy),
			},
		},
	}, nil)
	if err != nil {
		log.Fatalf("failed to finish the request: %v", err)
	}
	// You could use response here. We use blank identifier for just demo purposes.
	_ = res
	// If the HTTP response code is 200 as defined in example definition, your response structure would look as follows. Please pay attention that all the values in the output are fake values for just demo purposes.
	// res.AssessmentResponse = armsecurity.AssessmentResponse{
	// 	Name: to.Ptr("8bb8be0a-6010-4789-812f-e4d661c4ed0e"),
	// 	Type: to.Ptr("Microsoft.Security/assessments"),
	// 	ID: to.Ptr("/subscriptions/20ff7fc3-e762-44dd-bd96-b71116dcdc23/resourceGroups/myRg/providers/Microsoft.Compute/virtualMachineScaleSets/vmss1/providers/Microsoft.Security/assessments/8bb8be0a-6010-4789-812f-e4d661c4ed0e"),
	// 	Properties: &armsecurity.AssessmentPropertiesResponse{
	// 		DisplayName: to.Ptr("Install internal agent on VM"),
	// 		ResourceDetails: &armsecurity.AzureResourceDetails{
	// 			Source: to.Ptr(armsecurity.SourceAzure),
	// 			ID: to.Ptr("/subscriptions/20ff7fc3-e762-44dd-bd96-b71116dcdc23/resourceGroups/myRg/providers/Microsoft.Compute/virtualMachineScaleSets/vmss1/providers/Microsoft.Security/assessments/8bb8be0a-6010-4789-812f-e4d661c4ed0e"),
	// 		},
	// 		Status: &armsecurity.AssessmentStatusResponse{
	// 			Code: to.Ptr(armsecurity.AssessmentStatusCodeHealthy),
	// 		},
	// 	},
	// }
}

To use the Azure SDK library in your project, see this documentation. To provide feedback on this code sample, open a GitHub issue

const { SecurityCenter } = require("@azure/arm-security");
const { DefaultAzureCredential } = require("@azure/identity");

/**
 * This sample demonstrates how to 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
 *
 * @summary 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
 * x-ms-original-file: specification/security/resource-manager/Microsoft.Security/stable/2021-06-01/examples/Assessments/PutAssessment_example.json
 */
async function createSecurityRecommendationTaskOnAResource() {
  const resourceId =
    "subscriptions/20ff7fc3-e762-44dd-bd96-b71116dcdc23/resourceGroups/myRg/providers/Microsoft.Compute/virtualMachineScaleSets/vmss2";
  const assessmentName = "8bb8be0a-6010-4789-812f-e4d661c4ed0e";
  const assessment = {
    resourceDetails: { source: "Azure" },
    status: { code: "Healthy" },
  };
  const credential = new DefaultAzureCredential();
  const client = new SecurityCenter(credential);
  const result = await client.assessments.createOrUpdate(resourceId, assessmentName, assessment);
  console.log(result);
}

To use the Azure SDK library in your project, see this documentation. To provide feedback on this code sample, open a GitHub issue

using Azure;
using Azure.ResourceManager;
using System;
using System.Threading.Tasks;
using Azure.Core;
using Azure.Identity;
using Azure.ResourceManager.SecurityCenter.Models;
using Azure.ResourceManager.SecurityCenter;

// Generated from example definition: specification/security/resource-manager/Microsoft.Security/stable/2021-06-01/examples/Assessments/PutAssessment_example.json
// this example is just showing the usage of "Assessments_CreateOrUpdate" operation, for the dependent resources, they will have to be created separately.

// get your azure access token, for more details of how Azure SDK get your access token, please refer to https://learn.microsoft.com/en-us/dotnet/azure/sdk/authentication?tabs=command-line
TokenCredential cred = new DefaultAzureCredential();
// authenticate your client
ArmClient client = new ArmClient(cred);

// this example assumes you already have this SecurityAssessmentResource created on azure
// for more information of creating SecurityAssessmentResource, please refer to the document of SecurityAssessmentResource
string resourceId = "subscriptions/20ff7fc3-e762-44dd-bd96-b71116dcdc23/resourceGroups/myRg/providers/Microsoft.Compute/virtualMachineScaleSets/vmss2";
string assessmentName = "8bb8be0a-6010-4789-812f-e4d661c4ed0e";
ResourceIdentifier securityAssessmentResourceId = SecurityAssessmentResource.CreateResourceIdentifier(resourceId, assessmentName);
SecurityAssessmentResource securityAssessment = client.GetSecurityAssessmentResource(securityAssessmentResourceId);

// invoke the operation
SecurityAssessmentCreateOrUpdateContent content = new SecurityAssessmentCreateOrUpdateContent
{
    ResourceDetails = new AzureResourceDetails(),
    Status = new SecurityAssessmentStatus(SecurityAssessmentStatusCode.Healthy),
};
ArmOperation<SecurityAssessmentResource> lro = await securityAssessment.UpdateAsync(WaitUntil.Completed, content);
SecurityAssessmentResource result = lro.Value;

// the variable result is a resource, you could call other operations on this instance as well
// but just for demo, we get its data from this resource instance
SecurityAssessmentData resourceData = result.Data;
// for demo we just print out the id
Console.WriteLine($"Succeeded on id: {resourceData.Id}");

To use the Azure SDK library in your project, see this documentation. To provide feedback on this code sample, open a GitHub issue

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
AssessmentStatusResponse	The result 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
SecurityAssessmentResponse	Security assessment on a resource - response format
severity	The severity level of the assessment
threats
userImpact	The user impact of the assessment

AssessmentLinks

Object

Links relevant to the assessment

Name	Type	Description
azurePortalUri	string	Link to assessment in Azure Portal

AssessmentStatus

Object

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

Enumeration

Programmatic code for the status of the assessment

Value	Description
Healthy	The resource is healthy
Unhealthy	The resource has a security issue that needs to be addressed
NotApplicable	Assessment for this resource did not happen

AssessmentStatusResponse

Object

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
firstEvaluationDate	string (date-time)	The time that the assessment was created and first evaluated. Returned as UTC time in ISO 8601 format
statusChangeDate	string (date-time)	The time that the status of the assessment last changed. Returned as UTC time in ISO 8601 format

assessmentType

Enumeration

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

Value	Description
BuiltIn	Microsoft Defender for Cloud managed assessments
CustomPolicy	User defined policies that are automatically ingested from Azure Policy to Microsoft Defender for Cloud
CustomerManaged	User assessments pushed directly by the user or other third party to Microsoft Defender for Cloud
VerifiedPartner	An assessment that was created by a verified 3rd party if the user connected it to ASC

AzureResourceDetails

Object

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

Value	Description
Compute
Networking
Data
IdentityAndAccess
IoT

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	CloudErrorBody[]	The error details.
error.message	string	The error message.
error.target	string	The error target.

CloudErrorBody

Object

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

Object

The resource management error additional info.

Name	Type	Description
info	object	The additional info.
type	string	The additional info type.

implementationEffort

Enumeration

The implementation effort required to remediate this assessment

Value	Description
Low
Moderate
High

OnPremiseResourceDetails

Object

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

Object

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

Object

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

Object

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

Object

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

Object

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

SecurityAssessmentResponse

Object

Security assessment on a resource - response format

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	AssessmentStatusResponse	The result of the assessment
type	string	Resource type

severity

Enumeration

The severity level of the assessment

Value	Description
Low
Medium
High

threats

Enumeration

Value	Description
accountBreach
dataExfiltration
dataSpillage
maliciousInsider
elevationOfPrivilege
threatResistance
missingCoverage
denialOfService

userImpact

Enumeration

The user impact of the assessment

Value	Description
Low
Moderate
High

Share via

Assessments - Create Or Update

URI Parameters

Request Body

Responses

Security

azure_auth

Scopes

Examples

Create security recommendation task on a resource

Sample request

Sample response

Definitions

AssessmentLinks

AssessmentStatus

AssessmentStatusCode

AssessmentStatusResponse

assessmentType

AzureResourceDetails

categories

CloudError

CloudErrorBody

ErrorAdditionalInfo

implementationEffort

OnPremiseResourceDetails

OnPremiseSqlResourceDetails

SecurityAssessment

SecurityAssessmentMetadataPartnerData

SecurityAssessmentMetadataProperties

SecurityAssessmentPartnerData

SecurityAssessmentResponse

severity

threats

userImpact