Custom Recommendations - Create Or Update

Serviço:

Defender for Cloud

Versão da API:

2024-08-01

Cria ou atualiza uma recomendação personalizada sobre um determinado escopo

PUT https://management.azure.com/{scope}/providers/Microsoft.Security/customRecommendations/{customRecommendationName}?api-version=2024-08-01

Parâmetros do URI

Name	Em	Necessário	Tipo	Description
customRecommendationName	path	True	string	Nome da recomendação personalizada. Padrão Regex: [{]?[0-9a-fA-F]{8}-(?:[0-9a-fA-F]{4}-){3}[0-9a-fA-F]{12}[}]?$
scope	path	True	string	O âmbito da recomendação personalizada. Os escopos válidos são: grupo de gerenciamento (formato: 'providers/Microsoft.Management/managementGroups/{managementGroup}'), assinatura (formato: 'subscriptions/{subscriptionId}') ou conector de segurança (formato: 'subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Security/securityConnectors/{securityConnectorName})'
api-version	query	True	string	A versão da API a ser usada para esta operação.

Corpo do Pedido

Name	Tipo	Description
properties.cloudProviders	RecommendationSupportedClouds[]	Lista de todas as nuvens padrão suportadas.
properties.description	string	A descrição relativa às avaliações geradas pela presente recomendação.
properties.displayName	string	O nome de exibição das avaliações geradas por esta recomendação.
properties.query	string	Consulta KQL que representa os resultados de Recomendação necessários.
properties.remediationDescription	string	A descrição da reparação dos danos relacionada com as avaliações geradas pela presente recomendação.
properties.securityIssue	securityIssue	A severidade a relacionar com as avaliações geradas pela presente recomendação.
properties.severity	severityEnum	A severidade a relacionar com as avaliações geradas pela presente recomendação.

Respostas

Name	Tipo	Description
200 OK	CustomRecommendation	OK - Atualizado
201 Created	CustomRecommendation	Criado
Other Status Codes	ErrorResponse	Resposta de erro descrevendo por que a operação falhou

Segurança

azure_auth

Azure Ative Directory OAuth2 Flow

Tipo: oauth2
Fluxo: implicit
URL de Autorização: https://login.microsoftonline.com/common/oauth2/authorize

Âmbitos

Name	Description
user_impersonation	personificar a sua conta de utilizador

Exemplos

Create or update custom recommendation over management group scope

Create or update custom recommendation over security connector scope

Create or update custom recommendation over subscription scope

Create or update custom recommendation over management group scope

Pedido de amostra

HTTP

PUT https://management.azure.com/providers/Microsoft.Management/managementGroups/contoso/providers/Microsoft.Security/customRecommendations/33e7cc6e-a139-4723-a0e5-76993aee0771?api-version=2024-08-01

{
  "properties": {
    "query": "RawEntityMetadata | where Environment == 'GCP' and Identifiers.Type == 'compute.firewalls' | extend IslogConfigEnabled = tobool(Record.logConfig.enable) | extend HealthStatus = iff(IslogConfigEnabled, 'HEALTHY', 'UNHEALTHY')",
    "cloudProviders": [
      "AWS"
    ],
    "severity": "Medium",
    "displayName": "Password Policy",
    "description": "organization passwords policy",
    "remediationDescription": "Change password policy to...",
    "securityIssue": "Vulnerability"
  }
}

Java

import com.azure.resourcemanager.security.models.RecommendationSupportedClouds;
import com.azure.resourcemanager.security.models.SecurityIssue;
import com.azure.resourcemanager.security.models.SeverityEnum;
import java.util.Arrays;

/**
 * Samples for CustomRecommendations CreateOrUpdate.
 */
public final class Main {
    /*
     * x-ms-original-file:
     * specification/security/resource-manager/Microsoft.Security/stable/2024-08-01/examples/CustomRecommendations/
     * PutByManagementGroupCustomRecommendation_example.json
     */
    /**
     * Sample code: Create or update custom recommendation over management group scope.
     * 
     * @param manager Entry point to SecurityManager.
     */
    public static void createOrUpdateCustomRecommendationOverManagementGroupScope(
        com.azure.resourcemanager.security.SecurityManager manager) {
        manager.customRecommendations().define("33e7cc6e-a139-4723-a0e5-76993aee0771")
            .withExistingScope("providers/Microsoft.Management/managementGroups/contoso")
            .withQuery(
                "RawEntityMetadata | where Environment == 'GCP' and Identifiers.Type == 'compute.firewalls' | extend IslogConfigEnabled = tobool(Record.logConfig.enable) | extend HealthStatus = iff(IslogConfigEnabled, 'HEALTHY', 'UNHEALTHY')")
            .withCloudProviders(Arrays.asList(RecommendationSupportedClouds.AWS)).withSeverity(SeverityEnum.MEDIUM)
            .withSecurityIssue(SecurityIssue.VULNERABILITY).withDisplayName("Password Policy")
            .withDescription("organization passwords policy").withRemediationDescription("Change password policy to...")
            .create();
    }
}

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

Resposta da amostra

Código de estado:

200

{
  "id": "/providers/Microsoft.Management/managementGroups/contoso/providers/Microsoft.Security/customRecommendations/33e7cc6e-a139-4723-a0e5-76993aee0771",
  "name": "33e7cc6e-a139-4723-a0e5-76993aee0771",
  "type": "Microsoft.Security/customRecommendations",
  "systemData": {
    "createdBy": "user@contoso.com",
    "createdByType": "User",
    "createdAt": "2021-08-31T13:47:50.328Z",
    "lastModifiedBy": "user@contoso.com",
    "lastModifiedByType": "User",
    "lastModifiedAt": "2021-08-31T13:47:50.328Z"
  },
  "properties": {
    "query": "RawEntityMetadata | where Environment == 'GCP' and Identifiers.Type == 'compute.firewalls' | extend IslogConfigEnabled = tobool(Record.logConfig.enable) | extend HealthStatus = iff(IslogConfigEnabled, 'HEALTHY', 'UNHEALTHY')",
    "cloudProviders": [
      "AWS"
    ],
    "severity": "Medium",
    "displayName": "Password Policy",
    "description": "organization passwords policy",
    "remediationDescription": "Change password policy to...",
    "assessmentKey": "d5f442f7-7e77-4bcf-a450-a9c1b9a94eeb",
    "securityIssue": "Vulnerability"
  }
}

Código de estado:

201

{
  "id": "/providers/Microsoft.Management/managementGroups/contoso/providers/Microsoft.Security/customRecommendations/33e7cc6e-a139-4723-a0e5-76993aee0771",
  "name": "33e7cc6e-a139-4723-a0e5-76993aee0771",
  "type": "Microsoft.Security/customRecommendations",
  "systemData": {
    "createdBy": "user@contoso.com",
    "createdByType": "User",
    "createdAt": "2021-08-31T13:47:50.328Z",
    "lastModifiedBy": "user@contoso.com",
    "lastModifiedByType": "User",
    "lastModifiedAt": "2021-08-31T13:47:50.328Z"
  },
  "properties": {
    "query": "RawEntityMetadata | where Environment == 'GCP' and Identifiers.Type == 'compute.firewalls' | extend IslogConfigEnabled = tobool(Record.logConfig.enable) | extend HealthStatus = iff(IslogConfigEnabled, 'HEALTHY', 'UNHEALTHY')",
    "cloudProviders": [
      "AWS"
    ],
    "severity": "Medium",
    "displayName": "Password Policy",
    "description": "organization passwords policy",
    "remediationDescription": "Change password policy to...",
    "assessmentKey": "d5f442f7-7e77-4bcf-a450-a9c1b9a94eeb",
    "securityIssue": "Vulnerability"
  }
}

Create or update custom recommendation over security connector scope

Pedido de amostra

HTTP

PUT https://management.azure.com/subscriptions/20ff7fc3-e762-44dd-bd96-b71116dcdc23/resourceGroups/gcpResourceGroup/providers/Microsoft.Security/securityConnectors/gcpconnector/providers/Microsoft.Security/customRecommendations/33e7cc6e-a139-4723-a0e5-76993aee0771?api-version=2024-08-01

{
  "properties": {
    "query": "RawEntityMetadata | where Environment == 'GCP' and Identifiers.Type == 'compute.firewalls' | extend IslogConfigEnabled = tobool(Record.logConfig.enable) | extend HealthStatus = iff(IslogConfigEnabled, 'HEALTHY', 'UNHEALTHY')",
    "cloudProviders": [
      "AWS"
    ],
    "severity": "Medium",
    "displayName": "Password Policy",
    "description": "organization passwords policy",
    "remediationDescription": "Change password policy to...",
    "securityIssue": "Vulnerability"
  }
}

Java

import com.azure.resourcemanager.security.models.RecommendationSupportedClouds;
import com.azure.resourcemanager.security.models.SecurityIssue;
import com.azure.resourcemanager.security.models.SeverityEnum;
import java.util.Arrays;

/**
 * Samples for CustomRecommendations CreateOrUpdate.
 */
public final class Main {
    /*
     * x-ms-original-file:
     * specification/security/resource-manager/Microsoft.Security/stable/2024-08-01/examples/CustomRecommendations/
     * PutBySecurityConnectorCustomRecommendation_example.json
     */
    /**
     * Sample code: Create or update custom recommendation over security connector scope.
     * 
     * @param manager Entry point to SecurityManager.
     */
    public static void createOrUpdateCustomRecommendationOverSecurityConnectorScope(
        com.azure.resourcemanager.security.SecurityManager manager) {
        manager.customRecommendations().define("33e7cc6e-a139-4723-a0e5-76993aee0771").withExistingScope(
            "subscriptions/20ff7fc3-e762-44dd-bd96-b71116dcdc23/resourceGroups/gcpResourceGroup/providers/Microsoft.Security/securityConnectors/gcpconnector")
            .withQuery(
                "RawEntityMetadata | where Environment == 'GCP' and Identifiers.Type == 'compute.firewalls' | extend IslogConfigEnabled = tobool(Record.logConfig.enable) | extend HealthStatus = iff(IslogConfigEnabled, 'HEALTHY', 'UNHEALTHY')")
            .withCloudProviders(Arrays.asList(RecommendationSupportedClouds.AWS)).withSeverity(SeverityEnum.MEDIUM)
            .withSecurityIssue(SecurityIssue.VULNERABILITY).withDisplayName("Password Policy")
            .withDescription("organization passwords policy").withRemediationDescription("Change password policy to...")
            .create();
    }
}

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

Resposta da amostra

Código de estado:

200

{
  "id": "/subscriptions/20ff7fc3-e762-44dd-bd96-b71116dcdc23/resourceGroups/gcpResourceGroup/providers/Microsoft.Security/securityConnectors/gcpconnector/providers/Microsoft.Security/customRecommendations/33e7cc6e-a139-4723-a0e5-76993aee0771",
  "name": "33e7cc6e-a139-4723-a0e5-76993aee0771",
  "type": "Microsoft.Security/customRecommendations",
  "systemData": {
    "createdBy": "user@contoso.com",
    "createdByType": "User",
    "createdAt": "2021-08-31T13:47:50.328Z",
    "lastModifiedBy": "user@contoso.com",
    "lastModifiedByType": "User",
    "lastModifiedAt": "2021-08-31T13:47:50.328Z"
  },
  "properties": {
    "query": "RawEntityMetadata | where Environment == 'GCP' and Identifiers.Type == 'compute.firewalls' | extend IslogConfigEnabled = tobool(Record.logConfig.enable) | extend HealthStatus = iff(IslogConfigEnabled, 'HEALTHY', 'UNHEALTHY')",
    "cloudProviders": [
      "AWS"
    ],
    "severity": "Medium",
    "displayName": "Password Policy",
    "description": "organization passwords policy",
    "remediationDescription": "Change password policy to...",
    "assessmentKey": "d5f442f7-7e77-4bcf-a450-a9c1b9a94eeb",
    "securityIssue": "Vulnerability"
  }
}

Código de estado:

201

{
  "id": "/subscriptions/20ff7fc3-e762-44dd-bd96-b71116dcdc23/resourceGroups/gcpResourceGroup/providers/Microsoft.Security/securityConnectors/gcpconnector/providers/Microsoft.Security/customRecommendations/33e7cc6e-a139-4723-a0e5-76993aee0771",
  "name": "33e7cc6e-a139-4723-a0e5-76993aee0771",
  "type": "Microsoft.Security/customRecommendations",
  "systemData": {
    "createdBy": "user@contoso.com",
    "createdByType": "User",
    "createdAt": "2021-08-31T13:47:50.328Z",
    "lastModifiedBy": "user@contoso.com",
    "lastModifiedByType": "User",
    "lastModifiedAt": "2021-08-31T13:47:50.328Z"
  },
  "properties": {
    "query": "RawEntityMetadata | where Environment == 'GCP' and Identifiers.Type == 'compute.firewalls' | extend IslogConfigEnabled = tobool(Record.logConfig.enable) | extend HealthStatus = iff(IslogConfigEnabled, 'HEALTHY', 'UNHEALTHY')",
    "cloudProviders": [
      "AWS"
    ],
    "severity": "Medium",
    "displayName": "Password Policy",
    "description": "organization passwords policy",
    "remediationDescription": "Change password policy to...",
    "assessmentKey": "d5f442f7-7e77-4bcf-a450-a9c1b9a94eeb",
    "securityIssue": "Vulnerability"
  }
}

Create or update custom recommendation over subscription scope

Pedido de amostra

HTTP

PUT https://management.azure.com/subscriptions/e5d1b86c-3051-44d5-8802-aa65d45a279b/providers/Microsoft.Security/customRecommendations/33e7cc6e-a139-4723-a0e5-76993aee0771?api-version=2024-08-01

{
  "properties": {
    "query": "RawEntityMetadata | where Environment == 'GCP' and Identifiers.Type == 'compute.firewalls' | extend IslogConfigEnabled = tobool(Record.logConfig.enable) | extend HealthStatus = iff(IslogConfigEnabled, 'HEALTHY', 'UNHEALTHY')",
    "cloudProviders": [
      "AWS"
    ],
    "severity": "Medium",
    "displayName": "Password Policy",
    "description": "organization passwords policy",
    "remediationDescription": "Change password policy to...",
    "securityIssue": "Vulnerability"
  }
}

Java

import com.azure.resourcemanager.security.models.RecommendationSupportedClouds;
import com.azure.resourcemanager.security.models.SecurityIssue;
import com.azure.resourcemanager.security.models.SeverityEnum;
import java.util.Arrays;

/**
 * Samples for CustomRecommendations CreateOrUpdate.
 */
public final class Main {
    /*
     * x-ms-original-file:
     * specification/security/resource-manager/Microsoft.Security/stable/2024-08-01/examples/CustomRecommendations/
     * PutBySubscriptionCustomRecommendation_example.json
     */
    /**
     * Sample code: Create or update custom recommendation over subscription scope.
     * 
     * @param manager Entry point to SecurityManager.
     */
    public static void createOrUpdateCustomRecommendationOverSubscriptionScope(
        com.azure.resourcemanager.security.SecurityManager manager) {
        manager.customRecommendations().define("33e7cc6e-a139-4723-a0e5-76993aee0771")
            .withExistingScope("subscriptions/e5d1b86c-3051-44d5-8802-aa65d45a279b")
            .withQuery(
                "RawEntityMetadata | where Environment == 'GCP' and Identifiers.Type == 'compute.firewalls' | extend IslogConfigEnabled = tobool(Record.logConfig.enable) | extend HealthStatus = iff(IslogConfigEnabled, 'HEALTHY', 'UNHEALTHY')")
            .withCloudProviders(Arrays.asList(RecommendationSupportedClouds.AWS)).withSeverity(SeverityEnum.MEDIUM)
            .withSecurityIssue(SecurityIssue.VULNERABILITY).withDisplayName("Password Policy")
            .withDescription("organization passwords policy").withRemediationDescription("Change password policy to...")
            .create();
    }
}

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

Resposta da amostra

Código de estado:

200

{
  "id": "/subscriptions/e5d1b86c-3051-44d5-8802-aa65d45a279b/providers/Microsoft.Security/customRecommendations/33e7cc6e-a139-4723-a0e5-76993aee0771",
  "name": "33e7cc6e-a139-4723-a0e5-76993aee0771",
  "type": "Microsoft.Security/customRecommendations",
  "systemData": {
    "createdBy": "user@contoso.com",
    "createdByType": "User",
    "createdAt": "2021-08-31T13:47:50.328Z",
    "lastModifiedBy": "user@contoso.com",
    "lastModifiedByType": "User",
    "lastModifiedAt": "2021-08-31T13:47:50.328Z"
  },
  "properties": {
    "query": "RawEntityMetadata | where Environment == 'GCP' and Identifiers.Type == 'compute.firewalls' | extend IslogConfigEnabled = tobool(Record.logConfig.enable) | extend HealthStatus = iff(IslogConfigEnabled, 'HEALTHY', 'UNHEALTHY')",
    "cloudProviders": [
      "AWS"
    ],
    "severity": "Medium",
    "displayName": "Password Policy",
    "description": "organization passwords policy",
    "remediationDescription": "Change password policy to...",
    "assessmentKey": "d5f442f7-7e77-4bcf-a450-a9c1b9a94eeb",
    "securityIssue": "Vulnerability"
  }
}

Código de estado:

201

{
  "id": "/subscriptions/e5d1b86c-3051-44d5-8802-aa65d45a279b/providers/Microsoft.Security/customRecommendations/33e7cc6e-a139-4723-a0e5-76993aee0771",
  "name": "33e7cc6e-a139-4723-a0e5-76993aee0771",
  "type": "Microsoft.Security/customRecommendations",
  "systemData": {
    "createdBy": "user@contoso.com",
    "createdByType": "User",
    "createdAt": "2021-08-31T13:47:50.328Z",
    "lastModifiedBy": "user@contoso.com",
    "lastModifiedByType": "User",
    "lastModifiedAt": "2021-08-31T13:47:50.328Z"
  },
  "properties": {
    "query": "RawEntityMetadata | where Environment == 'GCP' and Identifiers.Type == 'compute.firewalls' | extend IslogConfigEnabled = tobool(Record.logConfig.enable) | extend HealthStatus = iff(IslogConfigEnabled, 'HEALTHY', 'UNHEALTHY')",
    "cloudProviders": [
      "AWS"
    ],
    "severity": "Medium",
    "displayName": "Password Policy",
    "description": "organization passwords policy",
    "remediationDescription": "Change password policy to...",
    "assessmentKey": "d5f442f7-7e77-4bcf-a450-a9c1b9a94eeb",
    "securityIssue": "Vulnerability"
  }
}

Definições

Name	Description
createdByType	O tipo de identidade que criou o recurso.
CustomRecommendation	Recomendação personalizada
ErrorAdditionalInfo	O erro de gerenciamento de recursos informações adicionais.
ErrorDetail	O detalhe do erro.
ErrorResponse	Resposta de erro
RecommendationSupportedClouds	Lista de todas as nuvens padrão suportadas.
securityIssue	A severidade a relacionar com as avaliações geradas pela presente recomendação.
severityEnum	A severidade a relacionar com as avaliações geradas pela presente recomendação.
systemData	Metadados referentes à criação e última modificação do recurso.

createdByType

O tipo de identidade que criou o recurso.

Name	Tipo	Description
Application	string
Key	string
ManagedIdentity	string
User	string

CustomRecommendation

Recomendação personalizada

Name	Tipo	Description
id	string	ID do recurso
name	string	Nome do recurso
properties.assessmentKey	string	A chave de metadados de avaliação utilizada quando é gerada uma avaliação para efeitos da presente recomendação.
properties.cloudProviders	RecommendationSupportedClouds[]	Lista de todas as nuvens padrão suportadas.
properties.description	string	A descrição relativa às avaliações geradas pela presente recomendação.
properties.displayName	string	O nome de exibição das avaliações geradas por esta recomendação.
properties.query	string	Consulta KQL que representa os resultados de Recomendação necessários.
properties.remediationDescription	string	A descrição da reparação dos danos relacionada com as avaliações geradas pela presente recomendação.
properties.securityIssue	securityIssue	A severidade a relacionar com as avaliações geradas pela presente recomendação.
properties.severity	severityEnum	A severidade a relacionar com as avaliações geradas pela presente recomendação.
systemData	systemData	Metadados do Azure Resource Manager contendo informações createdBy e modifiedBy.
type	string	Tipo de recurso

ErrorAdditionalInfo

O erro de gerenciamento de recursos informações adicionais.

Name	Tipo	Description
info	object	As informações adicionais.
type	string	O tipo de informação adicional.

ErrorDetail

O detalhe do erro.

Name	Tipo	Description
additionalInfo	ErrorAdditionalInfo[]	O erro informações adicionais.
code	string	O código de erro.
details	ErrorDetail[]	Os detalhes do erro.
message	string	A mensagem de erro.
target	string	O destino do erro.

ErrorResponse

Resposta de erro

Name	Tipo	Description
error	ErrorDetail	O objeto de erro.

RecommendationSupportedClouds

Lista de todas as nuvens padrão suportadas.

Name	Tipo	Description
AWS	string
Azure	string
GCP	string

securityIssue

A severidade a relacionar com as avaliações geradas pela presente recomendação.

Name	Tipo	Description
AnonymousAccess	string
BestPractices	string
ExcessivePermissions	string
NetworkExposure	string
TrafficEncryption	string
Vulnerability	string

severityEnum

A severidade a relacionar com as avaliações geradas pela presente recomendação.

Name	Tipo	Description
High	string
Low	string
Medium	string

systemData

Metadados referentes à criação e última modificação do recurso.

Name	Tipo	Description
createdAt	string	O carimbo de data/hora da criação de recursos (UTC).
createdBy	string	A identidade que criou o recurso.
createdByType	createdByType	O tipo de identidade que criou o recurso.
lastModifiedAt	string	O carimbo de data/hora da última modificação do recurso (UTC)
lastModifiedBy	string	A identidade que modificou o recurso pela última vez.
lastModifiedByType	createdByType	O tipo de identidade que modificou o recurso pela última vez.