Exportar avaliação de configuração segura por dispositivo

  • Artigo

Aplica-se a:

Deseja experimentar o Microsoft Defender para Ponto de Extremidade? Inscreva-se para uma avaliação gratuita.

Retorna todas as configurações e seus status, por dispositivo.

Há diferentes chamadas de API para obter diferentes tipos de dados. Como a quantidade de dados pode ser grande, há duas maneiras de serem recuperados:

  • Exportar resposta JSON de avaliação de configuração segura: a API puxa todos os dados em sua organização como respostas Json. Esse método é melhor para organizações pequenas com menos de 100 K dispositivos. A resposta é paginada, para que você possa usar o campo @odata.nextLink da resposta para buscar os próximos resultados.

  • Exportar avaliação de configuração segura por meio de arquivos: essa solução de API permite extrair quantidades maiores de dados de forma mais rápida e confiável. Portanto, é recomendável para organizações grandes, com mais de 100 K dispositivos. Essa API puxa todos os dados em sua organização como arquivos de download. A resposta contém URLs para baixar todos os dados do Armazenamento do Azure. Essa API permite baixar todos os dados do Armazenamento do Azure da seguinte maneira:

    • Chame a API para obter uma lista de URLs de download com todos os dados da organização.

    • Baixe todos os arquivos usando as URLs de download e processe os dados como quiser.

Os dados coletados (usando a resposta JSON ou por meio de arquivos) são os instantâneo atuais do estado atual e não contêm dados históricos. Para coletar dados históricos, os clientes devem salvar os dados em seus próprios armazenamentos de dados.

Observação

A menos que indicado o contrário, todos os métodos de avaliação de exportação listados são exportação completa e por dispositivo (também conhecido como por dispositivo).

1. Exportar avaliação de configuração segura (resposta JSON)

1.1 Descrição do método de API

Essa resposta à API contém a Avaliação de Configuração Segura em seus dispositivos expostos e retorna uma entrada para cada combinação exclusiva de DeviceId, ConfigurationId.

1.1.1 Limitações

  • O tamanho máximo da página é de 200.000.

  • As limitações de taxa para essa API são 30 chamadas por minuto e 1000 chamadas por hora.

1.2 Permissões

Uma das seguintes permissões é necessária para chamar esta API. Para saber mais, incluindo como escolher permissões, consulte Usar APIs Microsoft Defender para Ponto de Extremidade para obter detalhes.

Tipo de permissão Permissão Nome da exibição de permissão
Application Vulnerability.Read.All 'Ler informações de vulnerabilidade do Gerenciamento de Ameaças e Vulnerabilidades'
Delegado (conta corporativa ou de estudante) Vulnerabilidade.Leitura 'Ler informações de vulnerabilidade do Gerenciamento de Ameaças e Vulnerabilidades'

1.3 URL

GET /api/machines/SecureConfigurationsAssessmentByMachine

1.4 Parâmetros

  • pageSize (padrão = 50.000): número de resultados em resposta.
  • $top: número de resultados a serem retornados (não retorna @odata.nextLink e, portanto, não puxa todos os dados).

1.5 Propriedades

Observação

  • As propriedades definidas na tabela a seguir são listadas em ordem alfabética, por ID da propriedade. Ao executar essa API, a saída resultante não será necessariamente retornada na mesma ordem listada nesta tabela.
  • Algumas colunas adicionais podem ser retornadas na resposta. Essas colunas são temporárias e podem ser removidas, use apenas as colunas documentadas.

Propriedade (ID) Tipo de dados Descrição Exemplo de um valor retornado
ConfigurationCategory string Categoria ou agrupamento ao qual a configuração pertence: aplicativo, sistema operacional, rede, contas, controles de segurança Controles de segurança
ConfigurationId string Identificador exclusivo para uma configuração específica scid-10000
ConfigurationImpact string Impacto avaliado da configuração na classificação total (1-10) 9
ConfigurationName string Exibir o nome da configuração Dispositivos integrados ao Microsoft Defender para Ponto de Extremidade
ConfigurationSubcategory string Subcategoria ou subgrupo ao qual a configuração pertence. Em muitos casos, isso descreve capacidades ou recursos específicos. Dispositivos integrados
DeviceId cadeia de caracteres Identificador exclusivo para o dispositivo no serviço. 9eaf3a8b5962e0e6b1af9ec756664a9b823df2d1
DeviceName string FQDN (nome de domínio totalmente qualificado) do dispositivo. johnlaptop.europe.contoso.com
IsApplicable bool Indica se a configuração ou a política é aplicável verdadeiro
Iscompliant bool Indica se a configuração ou política está configurada corretamente falso
IsExpectedUserImpact bool Indica se haverá impacto do usuário se a configuração será aplicada verdadeiro
OSPlatform string Plataforma do sistema operacional em execução no dispositivo. Isso indica sistemas operacionais específicos, incluindo variações na mesma família, como Windows 10 e Windows 11. Consulte sistemas operacionais e plataformas compatíveis com Gerenciamento de Vulnerabilidades do Microsoft Defender (MDVM) para obter detalhes. Windows10 e Windows 11
RbacGroupName string O grupo RBAC (controle de acesso baseado em função). Se esse dispositivo não for atribuído a nenhum grupo RBAC, o valor será "Não atribuído". Se a organização não contiver nenhum grupo RBAC, o valor será "Nenhum". Servidores
RecommendationReference string Uma referência à ID de recomendação relacionada a este software. sca-_-scid-20000
Carimbo de data/hora string Da última vez que a configuração foi vista no dispositivo 2020-11-03 10:13:34.8476880

1.6 Exemplos

1.6.1 Exemplo de solicitação

GET https://api.securitycenter.microsoft.com/api/machines/SecureConfigurationsAssessmentByMachine?pageSize=5

1.6.2 Exemplo de resposta

{
    "@odata.context": "api.securitycenter.microsoft.com/api/$metadata#Collection(microsoft.windowsDefenderATP.api.AssetConfiguration)",
    "value": [
        {
            "deviceId": "00013ee62c6b12345b10214e1801b217b50ab455c293d",
            "rbacGroupName": "hhh",
            "deviceName": "ComputerPII_5d96860d69c73fdd06fc8d1679e1eb73eceb8330",
            "osPlatform": "Windows10" "Windows11",
            "osVersion": "NT kernel 6.x",
            "timestamp": "2021-01-11 09:47:58.854",
            "configurationId": "scid-10000",
            "configurationCategory": "Network",
            "configurationSubcategory": "",
            "configurationImpact": 5,
            "isCompliant": true,
            "isApplicable": true,
            "isExpectedUserImpact": false,
            "configurationName": "Disable insecure administration protocol - Telnet",
            "recommendationReference": "sca-_-scid-10000"
        },
        {
            "deviceId": "0002a1be533813b9a8c6de739785365bce7910",
            "rbacGroupName": "hhh",
            "deviceName": null,
            "osPlatform": "Windows10" "Windows11",
            "osVersion": "10.0",
            "timestamp": "2021-01-11 09:47:58.854",
            "configurationId": "scid-20000",
            "configurationCategory": "Security controls",
            "configurationSubcategory": "Onboard Devices",
            "configurationImpact": 9,
            "isCompliant": false,
            "isApplicable": true,
            "isExpectedUserImpact": false,
            "configurationName": "Onboard devices to Microsoft Defender for Endpoint",
            "recommendationReference": "sca-_-scid-20000"
        },
        {
            "deviceId": "0002a1de123456a8c06de736785395d4ce7610",
            "rbacGroupName": "hhh",
            "deviceName": null,
            "osPlatform": "Windows10" "Windows11",
            "osVersion": "10.0",
            "timestamp": "2021-01-11 09:47:58.854",
            "configurationId": "scid-10000",
            "configurationCategory": "Network",
            "configurationSubcategory": "",
            "configurationImpact": 5,
            "isCompliant": true,
            "isApplicable": true,
            "isExpectedUserImpact": false,
            "configurationName": "Disable insecure administration protocol - Telnet",
            "recommendationReference": "sca-_-scid-10000"
        },
        {
            "deviceId": "00044f912345bdaf756492dbe6db733b6a9c59ab4",
            "rbacGroupName": "hhh",
            "deviceName": "ComputerPII_18663d45912eed224b2be2f5ea3142726e63f16a.DomainPII_21eeb80b086e76bdfa178eadfa25e8de9acfa346.corp.contoso.com",
            "osPlatform": "Windows10" "Windows11",
            "osVersion": "10.0.17763.1637",
            "timestamp": "2021-01-11 09:47:58.854",
            "configurationId": "scid-39",
            "configurationCategory": "OS",
            "configurationSubcategory": "",
            "configurationImpact": 5,
            "isCompliant": true,
            "isApplicable": true,
            "isExpectedUserImpact": false,
            "configurationName": "Enable 'Domain member: Digitally sign secure channel data (when possible)'",
            "recommendationReference": "sca-_-scid-39"
        },
        {
            "deviceId": "00044f912345daf759462bde6bd733d6a9c56ab4",
            "rbacGroupName": "hhh",
            "deviceName": "ComputerPII_18663b45612eeb224d2de2f5ea3142726e63f16a.DomainPII_21eed80d086e76dbfa178eadfa25e8be9acfa346.corp.contoso.com",
            "osPlatform": "Windows10" "Windows11",
            "osVersion": "10.0.17763.1637",
            "timestamp": "2021-01-11 09:47:58.854",
            "configurationId": "scid-6093",
            "configurationCategory": "Security controls",
            "configurationSubcategory": "Antivirus",
            "configurationImpact": 5,
            "isCompliant": false,
            "isApplicable": false,
            "isExpectedUserImpact": false,
            "configurationName": "Enable Microsoft Defender Antivirus real-time behavior monitoring for Linux",
            "recommendationReference": "sca-_-scid-6093"
        }
    ],
    "@odata.nextLink": "https://api.securitycenter.microsoft.com/api/machines/SecureConfigurationsAssessmentByMachine?pagesize=5&$skiptoken=eyJFeHBvcnREZWZpbml0aW9uIjp7IlRpbWVQYXRoIjoiMjAyMS0wMS0xMS8xMTAxLyJ9LCJFeHBvcnRGaWxlSW5kZXgiOjAsIkxpbmVTdG9wcGVkQXQiOjV9"
}

2. Exportar avaliação de configuração segura (por meio de arquivos)

Descrição do método de API 2.1

Essa resposta à API contém a Avaliação de Configuração Segura em seus dispositivos expostos e retorna uma entrada para cada combinação exclusiva de DeviceId, ConfigurationId.

Limitações 2.1.1

As limitações de taxa para essa API são 5 chamadas por minuto e 20 chamadas por hora.

2.2 Permissões

Uma das seguintes permissões é necessária para chamar esta API. Para saber mais, incluindo como escolher permissões, consulte Usar APIs Microsoft Defender para Ponto de Extremidade para obter detalhes.

Tipo de permissão Permissão Nome da exibição de permissão
Application Vulnerability.Read.All 'Ler informações de vulnerabilidade do Gerenciamento de Ameaças e Vulnerabilidades'
Delegado (conta corporativa ou de estudante) Vulnerabilidade.Leitura 'Ler informações de vulnerabilidade do Gerenciamento de Ameaças e Vulnerabilidades'

2.3 URL

GET /api/machines/SecureConfigurationsAssessmentExport

Parâmetros

  • sasValidHours: o número de horas para o qual as URLs de download serão válidas (no máximo 24 horas).

2.5 Propriedades

Observação

  • Os arquivos são compactados gzip & no formato Json multiline.
  • As URLs de download são válidas apenas por 3 horas; caso contrário, você pode usar o parâmetro.
  • Para obter a velocidade máxima de download de seus dados, você pode ter certeza de que está baixando da mesma região do Azure na qual seus dados residem.

Propriedade (ID) Tipo de dados Descrição Exemplo de um valor retornado
Exportar arquivos array[string] Uma lista de URLs de download para arquivos que contêm o instantâneo atual da organização ["Https://tvmexportstrstgeus.blob.core.windows.net/tvm-export...1", "https://tvmexportstrstgeus.blob.core.windows.net/tvm-export...2"]
GeneratedTime string O tempo em que a exportação foi gerada. 2021-05-20T08:00:00Z

2.6 Exemplos

2.6.1 Exemplo de solicitação

GET https://api.securitycenter.microsoft.com/api/machines/SecureConfigurationsAssessmentExport

Exemplo de resposta 2.6.2

{
    "@odata.context": "https://api.securitycenter.microsoft.com/api/$metadata#contoso.windowsDefenderATP.api.ExportFilesResponse",
    "exportFiles": [
        "https://tvmexportstrstgeus.blob.core.windows.net/tvm-export/2021-01-11/1101/ScaExport/json/OrgId=12345678-195f-4223-9c7a-99fb420fd000/part-00393-e423630d-4c69-4490-8769-a4f5468c4f25.c000.json.gz?sv=2019-12-12&st=2021-01-11T11%3A55%3A51Z&se=2021-01-11T14%3A55%3A51Z&sr=b&sp=r&sig=...",
        "https://tvmexportstrstgeus.blob.core.windows.net/tvm-export/2021-01-11/1101/ScaExport/json/OrgId=12345678-195f-4223-9c7a-99fb420fd000/part-00394-e423630d-4c69-4490-8769-a4f5468c4f25.c000.json.gz?sv=2019-12-12&st=2021-01-11T11%3A55%3A51Z&se=2021-01-11T14%3A55%3A51Z&sr=b&sp=r&sig=...",
        "https://tvmexportstrstgeus.blob.core.windows.net/tvm-export/2021-01-11/1101/ScaExport/json/OrgId=12345678-195f-4223-9c7a-99fb420fd000/part-00394-e423630d-4c69-4490-8769-a4f5468c4f25.c001.json.gz?sv=2019-12-12&st=2021-01-11T11%3A55%3A51Z&se=2021-01-11T14%3A55%3A51Z&sr=b&sp=r&sig=..."
    ],
    "generatedTime": "2021-01-11T11:01:00Z"
}

Confira também

Outros relacionados

Dica

Você deseja aprender mais? Engage com a comunidade de Segurança da Microsoft em nossa Comunidade Tecnológica: Microsoft Defender para Ponto de Extremidade Tech Community.