Assessments - Create Or Update

Dienst:

Defender for Cloud

API-Version:

2021-06-01

Erstellen Sie eine Sicherheitsbewertung für Ihre Ressource. Eine Bewertungsmetadaten, die diese Bewertung beschreiben, müssen vor dem Einfügen des Bewertungsergebnisses mit demselben Namen vor dem Einfügen des Bewertungsergebnisses vordefiniert sein.

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

URI-Parameter

Name	In	Erforderlich	Typ	Beschreibung
assessmentName	path	True	string	Der Bewertungsschlüssel – Eindeutiger Schlüssel für den Bewertungstyp
resourceId	path	True	string	Der Bezeichner der Ressource.
api-version	query	True	string	API-Version für den Vorgang

Anforderungstext

Name	Erforderlich	Typ	Beschreibung
properties.resourceDetails	True	ResourceDetails: OnPremiseResourceDetails AzureResourceDetails OnPremiseSqlResourceDetails	Details der Ressource, die bewertet wurde
properties.status	True	AssessmentStatus	Das Ergebnis der Bewertung
properties.additionalData		object	Zusätzliche Daten zur Bewertung
properties.metadata		SecurityAssessmentMetadataProperties	Beschreibt die Eigenschaften einer Bewertungsmetadaten.
properties.partnersData		SecurityAssessmentPartnerData	Daten zur Integration von Drittanbietern

Antworten

Name	Typ	Beschreibung
200 OK	SecurityAssessmentResponse	OK – Aktualisiert
201 Created	SecurityAssessmentResponse	Erstellt
Other Status Codes	CloudError	Fehlerantwort, die beschreibt, warum der Vorgang fehlgeschlagen ist.

Sicherheit

azure_auth

Azure Active Directory OAuth2-Fluss

Typ: oauth2
Ablauf: implicit
Autorisierungs-URL: https://login.microsoftonline.com/common/oauth2/authorize

Bereiche

Name	Beschreibung
user_impersonation	Identitätswechsel ihres Benutzerkontos

Beispiele

Create security recommendation task on a resource

Beispielanforderung

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=2021-06-01

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

Java

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

Go

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

JavaScript

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

dotnet

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

Beispiel für eine Antwort

Statuscode:

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

Statuscode:

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

Definitionen

Name	Beschreibung
AssessmentLinks	Links, die für die Bewertung relevant sind
AssessmentStatus	Das Ergebnis der Bewertung
AssessmentStatusCode	Programmgesteuerter Code für den Status der Bewertung
AssessmentStatusResponse	Das Ergebnis der Bewertung
assessmentType	BuiltIn, wenn die Bewertung basierend auf der integrierten Azure-Richtliniendefinition , benutzerdefiniert, wenn die Bewertung basierend auf der benutzerdefinierten Azure-Richtliniendefinition
AzureResourceDetails	Details der Azure-Ressource, die bewertet wurde
categories
CloudError	Häufige Fehlerantwort für alle Azure Resource Manager-APIs, um Fehlerdetails für fehlgeschlagene Vorgänge zurückzugeben. (Dies folgt auch dem OData-Fehlerantwortformat.)
CloudErrorBody	Das Fehlerdetails.
ErrorAdditionalInfo	Der Ressourcenverwaltungsfehler zusätzliche Informationen.
implementationEffort	Der Implementierungsaufwand, der zur Behebung dieser Bewertung erforderlich ist
OnPremiseResourceDetails	Details der lokalen Ressource, die bewertet wurde
OnPremiseSqlResourceDetails	Details der lokalen Sql-Ressource, die bewertet wurde
SecurityAssessment	Sicherheitsbewertung für eine Ressource
SecurityAssessmentMetadataPartnerData	Beschreibt den Partner, der die Bewertung erstellt hat.
SecurityAssessmentMetadataProperties	Beschreibt die Eigenschaften einer Bewertungsmetadaten.
SecurityAssessmentPartnerData	Daten zur Integration von Drittanbietern
SecurityAssessmentResponse	Sicherheitsbewertung für eine Ressource – Antwortformat
severity	Schweregrad der Bewertung
threats
userImpact	Die Auswirkungen der Benutzer auf die Bewertung

AssessmentLinks

Links, die für die Bewertung relevant sind

Name	Typ	Beschreibung
azurePortalUri	string	Link zur Bewertung im Azure-Portal

AssessmentStatus

Das Ergebnis der Bewertung

Name	Typ	Beschreibung
cause	string	Programmgesteuerter Code für die Ursache des Bewertungsstatus
code	AssessmentStatusCode	Programmgesteuerter Code für den Status der Bewertung
description	string	Lesbare Beschreibung des Bewertungsstatus

AssessmentStatusCode

Programmgesteuerter Code für den Status der Bewertung

Name	Typ	Beschreibung
Healthy	string	Die Ressource ist fehlerfrei.
NotApplicable	string	Die Bewertung für diese Ressource ist nicht aufgetreten.
Unhealthy	string	Die Ressource weist ein Sicherheitsproblem auf, das behoben werden muss

AssessmentStatusResponse

Das Ergebnis der Bewertung

Name	Typ	Beschreibung
cause	string	Programmgesteuerter Code für die Ursache des Bewertungsstatus
code	AssessmentStatusCode	Programmgesteuerter Code für den Status der Bewertung
description	string	Lesbare Beschreibung des Bewertungsstatus
firstEvaluationDate	string	Die Zeit, zu der die Bewertung erstellt und zuerst ausgewertet wurde. Zurückgegeben als UTC-Zeit im ISO 8601-Format
statusChangeDate	string	Der Zeitpunkt, zu dem der Status der Bewertung zuletzt geändert wurde. Zurückgegeben als UTC-Zeit im ISO 8601-Format

assessmentType

BuiltIn, wenn die Bewertung basierend auf der integrierten Azure-Richtliniendefinition , benutzerdefiniert, wenn die Bewertung basierend auf der benutzerdefinierten Azure-Richtliniendefinition

Name	Typ	Beschreibung
BuiltIn	string	Verwaltete Bewertungen von Microsoft Defender für Cloud
CustomPolicy	string	Benutzerdefinierte Richtlinien, die automatisch von Azure-Richtlinie zu Microsoft Defender für Cloud aufgenommen werden
CustomerManaged	string	Benutzerbewertungen, die direkt vom Benutzer oder einem anderen Drittanbieter an Microsoft Defender für Cloud übertragen werden
VerifiedPartner	string	Eine Bewertung, die von einem überprüften Drittanbieter erstellt wurde, wenn der Benutzer sie mit ASC verbunden hat

AzureResourceDetails

Details der Azure-Ressource, die bewertet wurde

Name	Typ	Beschreibung
id	string	Azure-Ressourcen-ID der bewerteten Ressource
source	string: Azure	Die Plattform, auf der sich die bewertete Ressource befindet

categories

Name	Typ	Beschreibung
Compute	string
Data	string
IdentityAndAccess	string
IoT	string
Networking	string

CloudError

Häufige Fehlerantwort für alle Azure Resource Manager-APIs, um Fehlerdetails für fehlgeschlagene Vorgänge zurückzugeben. (Dies folgt auch dem OData-Fehlerantwortformat.)

Name	Typ	Beschreibung
error.additionalInfo	ErrorAdditionalInfo[]	Die zusätzlichen Informationen des Fehlers.
error.code	string	Der Fehlercode.
error.details	CloudErrorBody[]	Die Fehlerdetails.
error.message	string	Die Fehlermeldung.
error.target	string	Das Fehlerziel.

CloudErrorBody

Das Fehlerdetails.

Name	Typ	Beschreibung
additionalInfo	ErrorAdditionalInfo[]	Die zusätzlichen Informationen des Fehlers.
code	string	Der Fehlercode.
details	CloudErrorBody[]	Die Fehlerdetails.
message	string	Die Fehlermeldung.
target	string	Das Fehlerziel.

ErrorAdditionalInfo

Der Ressourcenverwaltungsfehler zusätzliche Informationen.

Name	Typ	Beschreibung
info	object	Die zusätzlichen Informationen.
type	string	Der zusätzliche Informationstyp.

implementationEffort

Der Implementierungsaufwand, der zur Behebung dieser Bewertung erforderlich ist

Name	Typ	Beschreibung
High	string
Low	string
Moderate	string

OnPremiseResourceDetails

Details der lokalen Ressource, die bewertet wurde

Name	Typ	Beschreibung
machineName	string	Der Name des Computers
source	string: OnPremise	Die Plattform, auf der sich die bewertete Ressource befindet
sourceComputerId	string	Die oms-Agent-ID, die auf dem Computer installiert ist
vmuuid	string	Die eindeutige ID des Computers
workspaceId	string	Azure-Ressourcen-ID des Arbeitsbereichs, an den der Computer angefügt ist

OnPremiseSqlResourceDetails

Details der lokalen Sql-Ressource, die bewertet wurde

Name	Typ	Beschreibung
databaseName	string	Der sql-Datenbankname, der auf dem Computer installiert ist
machineName	string	Der Name des Computers
serverName	string	Der auf dem Computer installierte Sql Server-Name
source	string: OnPremiseSql	Die Plattform, auf der sich die bewertete Ressource befindet
sourceComputerId	string	Die oms-Agent-ID, die auf dem Computer installiert ist
vmuuid	string	Die eindeutige ID des Computers
workspaceId	string	Azure-Ressourcen-ID des Arbeitsbereichs, an den der Computer angefügt ist

SecurityAssessment

Sicherheitsbewertung für eine Ressource

Name	Typ	Beschreibung
id	string	Ressourcen-ID
name	string	Ressourcenname
properties.additionalData	object	Zusätzliche Daten zur Bewertung
properties.displayName	string	Benutzerfreundlicher Anzeigename der Bewertung
properties.links	AssessmentLinks	Links, die für die Bewertung relevant sind
properties.metadata	SecurityAssessmentMetadataProperties	Beschreibt die Eigenschaften einer Bewertungsmetadaten.
properties.partnersData	SecurityAssessmentPartnerData	Daten zur Integration von Drittanbietern
properties.resourceDetails	ResourceDetails: AzureResourceDetails OnPremiseResourceDetails OnPremiseSqlResourceDetails	Details der Ressource, die bewertet wurde
properties.status	AssessmentStatus	Das Ergebnis der Bewertung
type	string	Ressourcentyp

SecurityAssessmentMetadataPartnerData

Beschreibt den Partner, der die Bewertung erstellt hat.

Name	Typ	Beschreibung
partnerName	string	Name des Unternehmens des Partners
productName	string	Name des Produkts des Partners, der die Bewertung erstellt hat
secret	string	Geheimer Schlüssel, um den Partner zu authentifizieren und zu überprüfen, ob die Bewertung erstellt wurde – schreibgeschützt

SecurityAssessmentMetadataProperties

Beschreibt die Eigenschaften einer Bewertungsmetadaten.

Name	Typ	Beschreibung
assessmentType	assessmentType	BuiltIn, wenn die Bewertung basierend auf der integrierten Azure-Richtliniendefinition , benutzerdefiniert, wenn die Bewertung basierend auf der benutzerdefinierten Azure-Richtliniendefinition
categories	categories[]	Die Kategorien von Ressourcen, die gefährdet sind, wenn die Bewertung fehlerhaft ist
description	string	Lesbare Beschreibung der Bewertung
displayName	string	Benutzerfreundlicher Anzeigename der Bewertung
implementationEffort	implementationEffort	Der Implementierungsaufwand, der zur Behebung dieser Bewertung erforderlich ist
partnerData	SecurityAssessmentMetadataPartnerData	Beschreibt den Partner, der die Bewertung erstellt hat.
policyDefinitionId	string	Azure-Ressourcen-ID der Richtliniendefinition, die diese Bewertungsberechnung aktiviert
preview	boolean	True, wenn sich diese Bewertung im Vorschauversionsstatus befindet
remediationDescription	string	Menschliche lesbare Beschreibung, was Sie tun sollten, um dieses Sicherheitsproblem zu beheben
severity	severity	Schweregrad der Bewertung
threats	threats[]	Bedrohungsauswirkungen der Bewertung
userImpact	userImpact	Die Auswirkungen der Benutzer auf die Bewertung

SecurityAssessmentPartnerData

Daten zur Integration von Drittanbietern

Name	Typ	Beschreibung
partnerName	string	Name des Unternehmens des Partners
secret	string	geheim, um den Partner zu authentifizieren – schreibgeschützt

SecurityAssessmentResponse

Sicherheitsbewertung für eine Ressource – Antwortformat

Name	Typ	Beschreibung
id	string	Ressourcen-ID
name	string	Ressourcenname
properties.additionalData	object	Zusätzliche Daten zur Bewertung
properties.displayName	string	Benutzerfreundlicher Anzeigename der Bewertung
properties.links	AssessmentLinks	Links, die für die Bewertung relevant sind
properties.metadata	SecurityAssessmentMetadataProperties	Beschreibt die Eigenschaften einer Bewertungsmetadaten.
properties.partnersData	SecurityAssessmentPartnerData	Daten zur Integration von Drittanbietern
properties.resourceDetails	ResourceDetails: AzureResourceDetails OnPremiseResourceDetails OnPremiseSqlResourceDetails	Details der Ressource, die bewertet wurde
properties.status	AssessmentStatusResponse	Das Ergebnis der Bewertung
type	string	Ressourcentyp

severity

Schweregrad der Bewertung

Name	Typ	Beschreibung
High	string
Low	string
Medium	string

threats

Name	Typ	Beschreibung
accountBreach	string
dataExfiltration	string
dataSpillage	string
denialOfService	string
elevationOfPrivilege	string
maliciousInsider	string
missingCoverage	string
threatResistance	string

userImpact

Die Auswirkungen der Benutzer auf die Bewertung

Name	Typ	Beschreibung
High	string
Low	string
Moderate	string