Assessments - List

Reference

Service:: Defender for Cloud

API Version:: 2021-06-01

Get security assessments on all your scanned resources inside a scope

GET https://management.azure.com/{scope}/providers/Microsoft.Security/assessments?api-version=2021-06-01

URI Parameters

Name	In	Required	Type	Description
scope	path	True	string	Scope of the query, can be subscription (/subscriptions/0b06d9ea-afe6-4779-bd59-30e5c2d9d13f) or management group (/providers/Microsoft.Management/managementGroups/mgName).
api-version	query	True	string	API version for the operation

Responses

Name	Type	Description
200 OK	SecurityAssessmentList	OK
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

List security assessments

Sample request

GET https://management.azure.com/subscriptions/20ff7fc3-e762-44dd-bd96-b71116dcdc23/providers/Microsoft.Security/assessments?api-version=2021-06-01


/**
 * Samples for Assessments List.
 */
public final class Main {
    /*
     * x-ms-original-file:
     * specification/security/resource-manager/Microsoft.Security/stable/2021-06-01/examples/Assessments/
     * ListAssessments_example.json
     */
    /**
     * Sample code: List security assessments.
     * 
     * @param manager Entry point to SecurityManager.
     */
    public static void listSecurityAssessments(com.azure.resourcemanager.security.SecurityManager manager) {
        manager.assessments().list("subscriptions/20ff7fc3-e762-44dd-bd96-b71116dcdc23",
            com.azure.core.util.Context.NONE);
    }
}

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/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/ListAssessments_example.json
func ExampleAssessmentsClient_NewListPager() {
	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)
	}
	pager := clientFactory.NewAssessmentsClient().NewListPager("subscriptions/20ff7fc3-e762-44dd-bd96-b71116dcdc23", nil)
	for pager.More() {
		page, err := pager.NextPage(ctx)
		if err != nil {
			log.Fatalf("failed to advance page: %v", err)
		}
		for _, v := range page.Value {
			// You could use page here. We use blank identifier for just demo purposes.
			_ = v
		}
		// If the HTTP response code is 200 as defined in example definition, your page structure would look as follows. Please pay attention that all the values in the output are fake values for just demo purposes.
		// page.AssessmentList = armsecurity.AssessmentList{
		// 	Value: []*armsecurity.AssessmentResponse{
		// 		{
		// 			Name: to.Ptr("21300918-b2e3-0346-785f-c77ff57d243b"),
		// 			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/21300918-b2e3-0346-785f-c77ff57d243b"),
		// 			Properties: &armsecurity.AssessmentPropertiesResponse{
		// 				DisplayName: to.Ptr("Install endpoint protection solution on virtual machine scale sets"),
		// 				ResourceDetails: &armsecurity.AzureResourceDetails{
		// 					Source: to.Ptr(armsecurity.SourceAzure),
		// 					ID: to.Ptr("/subscriptions/20ff7fc3-e762-44dd-bd96-b71116dcdc23/resourceGroups/myRg/providers/Microsoft.Compute/virtualMachineScaleSets/vmss1"),
		// 				},
		// 				Status: &armsecurity.AssessmentStatusResponse{
		// 					Code: to.Ptr(armsecurity.AssessmentStatusCodeHealthy),
		// 					FirstEvaluationDate: to.Ptr(func() time.Time { t, _ := time.Parse(time.RFC3339Nano, "2021-04-12T09:07:18.675Z"); return t}()),
		// 					StatusChangeDate: to.Ptr(func() time.Time { t, _ := time.Parse(time.RFC3339Nano, "2021-04-12T09:07:18.675Z"); return t}()),
		// 				},
		// 			},
		// 		},
		// 		{
		// 			Name: to.Ptr("21300918-b2e3-0346-785f-c77ff57d243b"),
		// 			Type: to.Ptr("Microsoft.Security/assessments"),
		// 			ID: to.Ptr("/subscriptions/20ff7fc3-e762-44dd-bd96-b71116dcdc23/resourceGroups/myRg/providers/Microsoft.Compute/virtualMachineScaleSets/vmss2/providers/Microsoft.Security/assessments/21300918-b2e3-0346-785f-c77ff57d243b"),
		// 			Properties: &armsecurity.AssessmentPropertiesResponse{
		// 				AdditionalData: map[string]*string{
		// 					"linkedWorkspaceId": to.Ptr("/subscriptions/20ff7fc3-e762-44dd-bd96-b71116dcdc23/resourceGroups/myRg/providers/Microsoft.OperationalInsights/workspaces/myLaWorkspace"),
		// 				},
		// 				DisplayName: to.Ptr("Install endpoint protection solution on virtual machine scale sets"),
		// 				ResourceDetails: &armsecurity.AzureResourceDetails{
		// 					Source: to.Ptr(armsecurity.SourceAzure),
		// 					ID: to.Ptr("/subscriptions/20ff7fc3-e762-44dd-bd96-b71116dcdc23/resourceGroups/myRg/providers/Microsoft.Compute/virtualMachineScaleSets/vmss2"),
		// 				},
		// 				Status: &armsecurity.AssessmentStatusResponse{
		// 					Description: to.Ptr("The effective policy for the assessment was evaluated to off - use Microsoft.Authorization/policyAssignments to turn this assessment on"),
		// 					Cause: to.Ptr("OffByPolicy"),
		// 					Code: to.Ptr(armsecurity.AssessmentStatusCodeNotApplicable),
		// 					FirstEvaluationDate: to.Ptr(func() time.Time { t, _ := time.Parse(time.RFC3339Nano, "2021-04-12T09:07:18.675Z"); return t}()),
		// 					StatusChangeDate: to.Ptr(func() time.Time { t, _ := time.Parse(time.RFC3339Nano, "2021-04-12T09:07:18.675Z"); return t}()),
		// 				},
		// 			},
		// 	}},
		// }
	}
}

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 Get security assessments on all your scanned resources inside a scope
 *
 * @summary Get security assessments on all your scanned resources inside a scope
 * x-ms-original-file: specification/security/resource-manager/Microsoft.Security/stable/2021-06-01/examples/Assessments/ListAssessments_example.json
 */
async function listSecurityAssessments() {
  const scope = "subscriptions/20ff7fc3-e762-44dd-bd96-b71116dcdc23";
  const credential = new DefaultAzureCredential();
  const client = new SecurityCenter(credential);
  const resArray = new Array();
  for await (let item of client.assessments.list(scope)) {
    resArray.push(item);
  }
  console.log(resArray);
}

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

{
  "value": [
    {
      "id": "/subscriptions/20ff7fc3-e762-44dd-bd96-b71116dcdc23/resourceGroups/myRg/providers/Microsoft.Compute/virtualMachineScaleSets/vmss1/providers/Microsoft.Security/assessments/21300918-b2e3-0346-785f-c77ff57d243b",
      "name": "21300918-b2e3-0346-785f-c77ff57d243b",
      "type": "Microsoft.Security/assessments",
      "properties": {
        "resourceDetails": {
          "source": "Azure",
          "id": "/subscriptions/20ff7fc3-e762-44dd-bd96-b71116dcdc23/resourceGroups/myRg/providers/Microsoft.Compute/virtualMachineScaleSets/vmss1"
        },
        "displayName": "Install endpoint protection solution on virtual machine scale sets",
        "status": {
          "code": "Healthy",
          "statusChangeDate": "2021-04-12T09:07:18.6759138Z",
          "firstEvaluationDate": "2021-04-12T09:07:18.6759138Z"
        }
      }
    },
    {
      "id": "/subscriptions/20ff7fc3-e762-44dd-bd96-b71116dcdc23/resourceGroups/myRg/providers/Microsoft.Compute/virtualMachineScaleSets/vmss2/providers/Microsoft.Security/assessments/21300918-b2e3-0346-785f-c77ff57d243b",
      "name": "21300918-b2e3-0346-785f-c77ff57d243b",
      "type": "Microsoft.Security/assessments",
      "properties": {
        "resourceDetails": {
          "source": "Azure",
          "id": "/subscriptions/20ff7fc3-e762-44dd-bd96-b71116dcdc23/resourceGroups/myRg/providers/Microsoft.Compute/virtualMachineScaleSets/vmss2"
        },
        "displayName": "Install endpoint protection solution on virtual machine scale sets",
        "status": {
          "code": "NotApplicable",
          "cause": "OffByPolicy",
          "description": "The effective policy for the assessment was evaluated to off - use Microsoft.Authorization/policyAssignments to turn this assessment on",
          "statusChangeDate": "2021-04-12T09:07:18.6759138Z",
          "firstEvaluationDate": "2021-04-12T09:07:18.6759138Z"
        },
        "additionalData": {
          "linkedWorkspaceId": "/subscriptions/20ff7fc3-e762-44dd-bd96-b71116dcdc23/resourceGroups/myRg/providers/Microsoft.OperationalInsights/workspaces/myLaWorkspace"
        }
      }
    }
  ]
}

Definitions

Name	Description
AssessmentLinks	Links relevant to 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
SecurityAssessmentList	Page of a security assessments list
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

Links relevant to the assessment

Name	Type	Description
azurePortalUri	string	Link to assessment in Azure Portal

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

AssessmentStatusResponse

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

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

SecurityAssessmentList

Page of a security assessments list

Name	Type	Description
nextLink	string	The URI to fetch the next page.
value	SecurityAssessmentResponse[]	Collection of security assessments in this page

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

SecurityAssessmentResponse

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

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

Assessments - List

URI Parameters

Responses

Security

azure_auth

Scopes

Examples

List security assessments

Sample request

Sample response

Definitions

AssessmentLinks

AssessmentStatusCode

AssessmentStatusResponse

assessmentType

AzureResourceDetails

categories

CloudError

CloudErrorBody

ErrorAdditionalInfo

implementationEffort

OnPremiseResourceDetails

OnPremiseSqlResourceDetails

SecurityAssessmentList

SecurityAssessmentMetadataPartnerData

SecurityAssessmentMetadataProperties

SecurityAssessmentPartnerData

SecurityAssessmentResponse

severity

threats

userImpact

Additional resources