Esportare la valutazione della configurazione sicura per dispositivo

  • Articolo

Si applica a:

Se si desidera provare Microsoft Defender per endpoint, iscriversi a una versione di valutazione gratuita.

Restituisce tutte le configurazioni e il relativo stato, in base al dispositivo.

Sono disponibili diverse chiamate API per ottenere tipi diversi di dati. Poiché la quantità di dati può essere elevata, è possibile recuperarli in due modi:

  • Esportare la risposta JSON di valutazione della configurazione sicura: l'API esegue il pull di tutti i dati nell'organizzazione come risposte Json. Questo metodo è ideale per le organizzazioni di piccole dimensioni con meno di 100 K dispositivi. La risposta viene impaginata, quindi è possibile usare il campo @odata.nextLink dalla risposta per recuperare i risultati successivi.

  • Esportare la valutazione della configurazione sicura tramite file: questa soluzione API consente di eseguire il pull di grandi quantità di dati in modo più rapido e affidabile. È quindi consigliabile per le organizzazioni di grandi dimensioni, con più di 100 K dispositivi. Questa API esegue il pull di tutti i dati nell'organizzazione come file di download. La risposta contiene URL per scaricare tutti i dati da Archiviazione di Azure. Questa API consente di scaricare tutti i dati da Archiviazione di Azure come indicato di seguito:

    • Chiamare l'API per ottenere un elenco di URL di download con tutti i dati dell'organizzazione.

    • Scaricare tutti i file usando gli URL di download ed elaborare i dati come si desidera.

I dati raccolti (usando la risposta JSON o tramite file) sono lo snapshot corrente dello stato corrente e non contengono dati cronologici. Per raccogliere dati cronologici, i clienti devono salvare i dati nei propri archivi dati.

Nota

Se non diversamente indicato, tutti i metodi di valutazione dell'esportazione elencati sono l'esportazione completa e per dispositivo (detto anche per dispositivo).

1. Esportare la valutazione della configurazione sicura (risposta JSON)

Descrizione del metodo API 1.1

Questa risposta API contiene la valutazione della configurazione sicura nei dispositivi esposti e restituisce una voce per ogni combinazione univoca di DeviceId, ConfigurationId.

1.1.1 Limitazioni

  • La dimensione massima della pagina è 200.000.

  • Le limitazioni di frequenza per questa API sono 30 chiamate al minuto e 1000 chiamate all'ora.

1.2 Autorizzazioni

Per chiamare questa API è necessaria una delle autorizzazioni seguenti. Per altre informazioni, incluso come scegliere le autorizzazioni, vedere Usare le API Microsoft Defender per endpoint per informazioni dettagliate.

Tipo di autorizzazione Autorizzazione Nome visualizzato autorizzazioni
Applicazione Vulnerability.Read.All 'Leggere le informazioni sulla vulnerabilità di Gestione delle minacce e delle vulnerabilità'
Delegato (account aziendale o dell'istituto di istruzione) Vulnerability.Read 'Leggere le informazioni sulla vulnerabilità di Gestione delle minacce e delle vulnerabilità'

1.3 URL

GET /api/machines/SecureConfigurationsAssessmentByMachine

1.4 Parametri

  • pageSize (valore predefinito = 50.000): numero di risultati in risposta.
  • $top: numero di risultati da restituire (non restituisce @odata.nextLink e pertanto non esegue il pull di tutti i dati).

1.5 Proprietà

Nota

  • Le proprietà definite nella tabella seguente sono elencate in ordine alfabetico, in base all'ID proprietà. Quando si esegue questa API, l'output risultante non verrà necessariamente restituito nello stesso ordine elencato in questa tabella.
  • Nella risposta potrebbero essere restituite alcune colonne aggiuntive. Queste colonne sono temporanee e potrebbero essere rimosse. Usare solo le colonne documentate.

Proprietà (ID) Tipo di dati Descrizione Esempio di valore restituito
ConfigurationCategory stringa Categoria o raggruppamento a cui appartiene la configurazione: Applicazione, Sistema operativo, Rete, Account, Controlli di sicurezza Controlli di sicurezza
ConfigurationId stringa Identificatore univoco di una configurazione specifica scid-10000
ConfigurationImpact stringa Impatto nominale della configurazione sul punteggio di configurazione complessivo (1-10) 9
Configurationname stringa Nome visualizzato della configurazione Aggiungere dispositivi a Microsoft Defender per endpoint
ConfigurationSubcategory stringa Sottocategoria o sottoraggruppamento a cui appartiene la configurazione. In molti casi qui vengono descritte capacità o funzionalità specifiche. Eseguire l'onboarding di dispositivi
DeviceId stringa Identificatore univoco per il dispositivo nel servizio. 9eaf3a8b5962e0e6b1af9ec756664a9b823df2d1
DeviceName stringa Nome di dominio completo (FQDN) del dispositivo. johnlaptop.europe.contoso.com
IsApplicabile bool Indica se la configurazione o i criteri sono applicabili true
IsCompliant bool Indica se la configurazione o i criteri sono configurati correttamente False
IsExpectedUserImpact bool Indica se si verifica un impatto sull'utente se la configurazione verrà applicata true
OSPlatform stringa Piattaforma del sistema operativo in esecuzione nel dispositivo. Indica sistemi operativi specifici, incluse le varianti all'interno della stessa famiglia, ad esempio Windows 10 e Windows 11. Per informazioni dettagliate, vedere sistemi operativi e piattaforme supportati da Gestione delle vulnerabilità di Microsoft Defender (MDVM). Windows10 e Windows 11
RbacGroupName stringa Gruppo di controllo degli accessi in base al ruolo. Se questo dispositivo non è assegnato ad alcun gruppo di controllo degli accessi in base al ruolo, il valore sarà "Non assegnato". Se l'organizzazione non contiene gruppi di controllo degli accessi in base al ruolo, il valore sarà "Nessuno". Server
RecommendationReference stringa Riferimento all'ID raccomandazione correlato a questo software. sca-_-scid-20000
Data e ora stringa Ultima volta che la configurazione è stata visualizzata nel dispositivo 2020-11-03 10:13:34.8476880

Esempi 1.6

1.6.1 Esempio di richiesta

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

Esempio di risposta 1.6.2

{
    "@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. Esportare la valutazione della configurazione sicura (tramite file)

Descrizione del metodo API 2.1

Questa risposta API contiene la valutazione della configurazione sicura nei dispositivi esposti e restituisce una voce per ogni combinazione univoca di DeviceId, ConfigurationId.

2.1.1 Limitazioni

Le limitazioni di frequenza per questa API sono 5 chiamate al minuto e 20 chiamate all'ora.

2.2 Autorizzazioni

Per chiamare questa API è necessaria una delle autorizzazioni seguenti. Per altre informazioni, inclusa la scelta delle autorizzazioni, vedere Usare le API Microsoft Defender per endpoint per informazioni dettagliate.

Tipo di autorizzazione Autorizzazione Nome visualizzato autorizzazioni
Applicazione Vulnerability.Read.All 'Leggere le informazioni sulla vulnerabilità di Gestione delle minacce e delle vulnerabilità'
Delegato (account aziendale o dell'istituto di istruzione) Vulnerability.Read 'Leggere le informazioni sulla vulnerabilità di Gestione delle minacce e delle vulnerabilità'

URL 2.3

GET /api/machines/SecureConfigurationsAssessmentExport

Parametri

  • sasValidHours: numero di ore per cui gli URL di download saranno validi (massimo 24 ore).

2.5 Proprietà

Nota

  • I file sono compressi in gzip & in formato Json multilinea.
  • Gli URL di download sono validi solo per 3 ore; in caso contrario, è possibile usare il parametro .
  • Per la massima velocità di download dei dati, è possibile assicurarsi di scaricare dalla stessa area di Azure in cui si trovano i dati.

Proprietà (ID) Tipo di dati Descrizione Esempio di valore restituito
Esportare file array[string] Elenco di URL di download per i file che contengono lo snapshot corrente dell'organizzazione ["Https://tvmexportstrstgeus.blob.core.windows.net/tvm-export...1", "https://tvmexportstrstgeus.blob.core.windows.net/tvm-export...2"]
GeneratedTime stringa Ora in cui è stata generata l'esportazione. 2021-05-20T08:00:00Z

Esempi 2.6

2.6.1 Esempio di richiesta

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

Esempio di risposta 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"
}

Vedere anche

Altri elementi correlati

Consiglio

Per saperne di più, Engage con la community Microsoft Security nella community tech: Microsoft Defender per endpoint Tech Community.