Assessments - Create Or Update

參考

服務:: Defender for Cloud

API 版本:: 2021-06-01

在您的資源上建立安全性評定。描述此評定的評估元數據必須先以相同名稱預先定義，才能插入評量結果

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

URI 參數

名稱	位於	必要	類型	Description
assessmentName	path	True	string	評定金鑰 - 評量類型的唯一索引鍵
resourceId	path	True	string	資源的標識碼。
api-version	query	True	string	作業的 API 版本

要求本文

名稱	必要	類型	Description
properties.resourceDetails	True	ResourceDetails: OnPremiseResourceDetails AzureResourceDetails OnPremiseSqlResourceDetails	已評估之資源的詳細數據
properties.status	True	AssessmentStatus	評量的結果
properties.additionalData		object	有關評量的其他數據
properties.metadata		SecurityAssessmentMetadataProperties	描述評估元數據的屬性。
properties.partnersData		SecurityAssessmentPartnerData	第三方合作夥伴整合的相關數據

回應

名稱	類型	Description
200 OK	SecurityAssessmentResponse	確定 - 已更新
201 Created	SecurityAssessmentResponse	創建
Other Status Codes	CloudError	描述作業失敗原因的錯誤回應。

安全性

azure_auth

Azure Active Directory OAuth2 Flow

類型: oauth2
Flow: implicit
授權 URL: https://login.microsoftonline.com/common/oauth2/authorize

範圍

名稱	Description
user_impersonation	模擬您的用戶帳戶

範例

Create security recommendation task on a resource

範例要求

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 System;
using System.Threading.Tasks;
using Azure;
using Azure.Core;
using Azure.Identity;
using Azure.ResourceManager;
using Azure.ResourceManager.SecurityCenter;
using Azure.ResourceManager.SecurityCenter.Models;

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

範例回覆

狀態碼:: 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"
    }
  }
}

狀態碼:: 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"
    }
  }
}

定義

名稱	Description
AssessmentLinks	與評量相關的連結
AssessmentStatus	評量的結果
AssessmentStatusCode	評估狀態的程式設計程序代碼
AssessmentStatusResponse	評量的結果
assessmentType	根據內建的 Azure 原則定義進行評量時，BuiltIn 會根據自定義 Azure 原則定義自定義評量
AzureResourceDetails	已評估的 Azure 資源詳細數據
categories
CloudError	所有 Azure Resource Manager API 的常見錯誤回應，以傳回失敗作業的錯誤詳細數據。（這也遵循 OData 錯誤回應格式。）。
CloudErrorBody	錯誤詳細數據。
ErrorAdditionalInfo	資源管理錯誤其他資訊。
implementationEffort	補救此評估所需的實作工作
OnPremiseResourceDetails	評估的內部部署資源詳細數據
OnPremiseSqlResourceDetails	已評估之內部部署 Sql 資源的詳細數據
SecurityAssessment	資源的安全性評估
SecurityAssessmentMetadataPartnerData	描述建立評定的合作夥伴
SecurityAssessmentMetadataProperties	描述評估元數據的屬性。
SecurityAssessmentPartnerData	第三方合作夥伴整合的相關數據
SecurityAssessmentResponse	資源的安全性評估 - 回應格式
severity	評定的嚴重性層級
threats
userImpact	評估的用戶影響

AssessmentLinks

與評量相關的連結

名稱	類型	Description
azurePortalUri	string	Azure 入口網站中評量的連結

AssessmentStatus

評量的結果

名稱	類型	Description
cause	string	評估狀態原因的程式設計程序代碼
code	AssessmentStatusCode	評估狀態的程式設計程序代碼
description	string	評估狀態的人類可讀描述

AssessmentStatusCode

評估狀態的程式設計程序代碼

名稱	類型	Description
Healthy	string	資源狀況良好
NotApplicable	string	此資源的評定未發生
Unhealthy	string	資源有需要解決的安全性問題

AssessmentStatusResponse

評量的結果

名稱	類型	Description
cause	string	評估狀態原因的程式設計程序代碼
code	AssessmentStatusCode	評估狀態的程式設計程序代碼
description	string	評估狀態的人類可讀描述
firstEvaluationDate	string	建立評定並首次評估的時間。以 ISO 8601 格式的 UTC 時間傳回
statusChangeDate	string	評估狀態上次變更的時間。以 ISO 8601 格式的 UTC 時間傳回

assessmentType

根據內建的 Azure 原則定義進行評量時，BuiltIn 會根據自定義 Azure 原則定義自定義評量

名稱	類型	Description
BuiltIn	string	適用於雲端的Defender受控評量Microsoft
CustomPolicy	string	自動從 Azure 原則擷取到適用於雲端的 Defender Microsoft 使用者定義的原則
CustomerManaged	string	由使用者或其他第三方直接推送至適用於雲端的Defender Microsoft用戶評量
VerifiedPartner	string	如果使用者將它連線至 ASC，由已驗證的第三方所建立的評量

AzureResourceDetails

已評估的 Azure 資源詳細數據

名稱	類型	Description
id	string	已評估資源的 Azure 資源識別碼
source	string: Azure	評估資源所在的平臺

名稱	類型	Description
Compute	string
Data	string
IdentityAndAccess	string
IoT	string
Networking	string

CloudError

所有 Azure Resource Manager API 的常見錯誤回應，以傳回失敗作業的錯誤詳細數據。（這也遵循 OData 錯誤回應格式。）。

名稱	類型	Description
error.additionalInfo	ErrorAdditionalInfo[]	錯誤其他資訊。
error.code	string	錯誤碼。
error.details	CloudErrorBody[]	錯誤詳細數據。
error.message	string	錯誤訊息。
error.target	string	錯誤目標。

CloudErrorBody

錯誤詳細數據。

名稱	類型	Description
additionalInfo	ErrorAdditionalInfo[]	錯誤其他資訊。
code	string	錯誤碼。
details	CloudErrorBody[]	錯誤詳細數據。
message	string	錯誤訊息。
target	string	錯誤目標。

ErrorAdditionalInfo

資源管理錯誤其他資訊。

名稱	類型	Description
info	object	其他資訊。
type	string	其他信息類型。

implementationEffort

補救此評估所需的實作工作

名稱	類型	Description
High	string
Low	string
Moderate	string

OnPremiseResourceDetails

評估的內部部署資源詳細數據

名稱	類型	Description
machineName	string	計算機的名稱
source	string: OnPremise	評估資源所在的平臺
sourceComputerId	string	計算機上安裝的 oms 代理程式識別碼
vmuuid	string	計算機的唯一標識碼
workspaceId	string	計算機所連結工作區的 Azure 資源識別碼

OnPremiseSqlResourceDetails

已評估之內部部署 Sql 資源的詳細數據

名稱	類型	Description
databaseName	string	計算機上安裝的 Sql 資料庫名稱
machineName	string	計算機的名稱
serverName	string	計算機上安裝的 Sql Server 名稱
source	string: OnPremiseSql	評估資源所在的平臺
sourceComputerId	string	計算機上安裝的 oms 代理程式識別碼
vmuuid	string	計算機的唯一標識碼
workspaceId	string	計算機所連結工作區的 Azure 資源識別碼

SecurityAssessment

資源的安全性評估

名稱	類型	Description
id	string	資源標識碼
name	string	資源名稱
properties.additionalData	object	有關評量的其他數據
properties.displayName	string	評估的使用者易記顯示名稱
properties.links	AssessmentLinks	與評量相關的連結
properties.metadata	SecurityAssessmentMetadataProperties	描述評估元數據的屬性。
properties.partnersData	SecurityAssessmentPartnerData	第三方合作夥伴整合的相關數據
properties.resourceDetails	ResourceDetails: AzureResourceDetails OnPremiseResourceDetails OnPremiseSqlResourceDetails	已評估之資源的詳細數據
properties.status	AssessmentStatus	評量的結果
type	string	資源類型

SecurityAssessmentMetadataPartnerData

描述建立評定的合作夥伴

名稱	類型	Description
partnerName	string	合作夥伴公司的名稱
productName	string	建立評量之合作夥伴的產品名稱
secret	string	驗證合作夥伴並確認其已建立評定的秘密 - 僅寫入

SecurityAssessmentMetadataProperties

描述評估元數據的屬性。

名稱	類型	Description
assessmentType	assessmentType	根據內建的 Azure 原則定義進行評量時，BuiltIn 會根據自定義 Azure 原則定義自定義評量
categories	categories[]	評量狀況不良時有風險的資源類別
description	string	評估的人類可讀描述
displayName	string	評估的使用者易記顯示名稱
implementationEffort	implementationEffort	補救此評估所需的實作工作
partnerData	SecurityAssessmentMetadataPartnerData	描述建立評定的合作夥伴
policyDefinitionId	string	開啟此評量計算的原則定義 Azure 資源識別碼
preview	boolean	True 是表示如果此評量處於預覽版本狀態
remediationDescription	string	人類可讀的關於您應該執行哪些動作來減輕此安全性問題的描述
severity	severity	評定的嚴重性層級
threats	threats[]	評估的威脅影響
userImpact	userImpact	評估的用戶影響

SecurityAssessmentPartnerData

第三方合作夥伴整合的相關數據

名稱	類型	Description
partnerName	string	合作夥伴公司的名稱
secret	string	驗證夥伴的秘密 - 僅寫入

SecurityAssessmentResponse

資源的安全性評估 - 回應格式

名稱	類型	Description
id	string	資源標識碼
name	string	資源名稱
properties.additionalData	object	有關評量的其他數據
properties.displayName	string	評估的使用者易記顯示名稱
properties.links	AssessmentLinks	與評量相關的連結
properties.metadata	SecurityAssessmentMetadataProperties	描述評估元數據的屬性。
properties.partnersData	SecurityAssessmentPartnerData	第三方合作夥伴整合的相關數據
properties.resourceDetails	ResourceDetails: AzureResourceDetails OnPremiseResourceDetails OnPremiseSqlResourceDetails	已評估之資源的詳細數據
properties.status	AssessmentStatusResponse	評量的結果
type	string	資源類型

severity

評定的嚴重性層級

名稱	類型	Description
High	string
Low	string
Medium	string

threats

名稱	類型	Description
accountBreach	string
dataExfiltration	string
dataSpillage	string
denialOfService	string
elevationOfPrivilege	string
maliciousInsider	string
missingCoverage	string
threatResistance	string

userImpact

評估的用戶影響

名稱	類型	Description
High	string
Low	string
Moderate	string

共用方式為

Assessments - Create Or Update

URI 參數

要求本文

回應

安全性

azure_auth

範圍

範例

Create security recommendation task on a resource

範例要求

範例回覆

定義

AssessmentLinks

AssessmentStatus

AssessmentStatusCode

AssessmentStatusResponse

assessmentType

AzureResourceDetails

categories

CloudError

CloudErrorBody

ErrorAdditionalInfo

implementationEffort

OnPremiseResourceDetails

OnPremiseSqlResourceDetails

SecurityAssessment

SecurityAssessmentMetadataPartnerData

SecurityAssessmentMetadataProperties

SecurityAssessmentPartnerData

SecurityAssessmentResponse

severity

threats

userImpact

其他資源