Veilige configuratie-evaluatie per apparaat exporteren

  • Artikel

Van toepassing op:

Wilt u Microsoft Defender voor Eindpunt ervaren? Meld u aan voor een gratis proefversie.

Retourneert alle configuraties en hun status, per apparaat.

Er zijn verschillende API-aanroepen om verschillende typen gegevens op te halen. Omdat de hoeveelheid gegevens groot kan zijn, zijn er twee manieren waarop deze kunnen worden opgehaald:

  • JSON-antwoord voor beveiligde configuratie-evaluatie exporteren: de API haalt alle gegevens in uw organisatie op als Json-antwoorden. Deze methode is het beste voor kleine organisaties met minder dan 100 K-apparaten. Het antwoord is gepagineerd, zodat u het veld @odata.nextLink uit het antwoord kunt gebruiken om de volgende resultaten op te halen.

  • Veilige configuratie-evaluatie exporteren via bestanden: met deze API-oplossing kunt u grotere hoeveelheden gegevens sneller en betrouwbaarder ophalen. Daarom wordt het aanbevolen voor grote organisaties, met meer dan 100 K-apparaten. Deze API haalt alle gegevens in uw organisatie op als downloadbestanden. Het antwoord bevat URL's voor het downloaden van alle gegevens uit Azure Storage. Met deze API kunt u als volgt al uw gegevens downloaden uit Azure Storage:

    • Roep de API aan om een lijst met download-URL's met alle gegevens van uw organisatie op te halen.

    • Download alle bestanden met behulp van de download-URL's en verwerk de gegevens zoals u wilt.

Gegevens die worden verzameld (met behulp van een JSON-antwoord of via bestanden) zijn de huidige momentopname van de huidige status en bevatten geen historische gegevens. Om historische gegevens te verzamelen, moeten klanten de gegevens opslaan in hun eigen gegevensopslag.

Opmerking

Tenzij anders aangegeven, zijn alle vermelde exportevaluatiemethoden volledige export en per apparaat (ook wel per apparaat genoemd).

1. Veilige configuratie-evaluatie exporteren (JSON-antwoord)

Beschrijving van API-methode 1.1

Dit API-antwoord bevat de beveiligde configuratie-evaluatie op uw blootgestelde apparaten en retourneert een vermelding voor elke unieke combinatie van DeviceId, ConfigurationId.

1.1.1 Beperkingen

  • Het maximale paginaformaat is 200.000.

  • Frequentiebeperkingen voor deze API zijn 30 aanroepen per minuut en 1000 aanroepen per uur.

1.2 Machtigingen

Een van de volgende machtigingen is vereist om deze API aan te roepen. Zie Use Microsoft Defender voor Eindpunt API's (Api's voor Microsoft Defender voor Eindpunt gebruiken) voor meer informatie, waaronder het kiezen van machtigingen.

Machtigingstype Machtiging Weergavenaam van machtiging
Toepassing Vulnerability.Read.All 'Informatie over beveiligingsproblemen in bedreigings- en beveiligingsbeheer lezen'
Gedelegeerd (werk- of schoolaccount) Vulnerability.Read 'Informatie over beveiligingsproblemen in bedreigings- en beveiligingsbeheer lezen'

1.3 URL

GET /api/machines/SecureConfigurationsAssessmentByMachine

1.4 Parameters

  • pageSize (standaard = 50.000): aantal resultaten in antwoord.
  • $top: het aantal resultaten dat moet worden geretourneerd (retourneert niet @odata.nextLink en haalt daarom niet alle gegevens op).

1.5 Eigenschappen

Opmerking

  • De eigenschappen die in de volgende tabel zijn gedefinieerd, worden alfabetisch weergegeven, op eigenschaps-id. Wanneer u deze API uitvoert, wordt de resulterende uitvoer niet noodzakelijkerwijs geretourneerd in dezelfde volgorde die in deze tabel wordt vermeld.
  • Er kunnen enkele extra kolommen worden geretourneerd in het antwoord. Deze kolommen zijn tijdelijk en kunnen worden verwijderd. Gebruik alleen de gedocumenteerde kolommen.

Eigenschap (id) Gegevenstype: Beschrijving Voorbeeld van een geretourneerde waarde
ConfigurationCategory tekenreeks Categorie of groep waartoe de configuratie behoort: Toepassing, besturingssysteem, netwerk, accounts, beveiligingsbesturingselementen Beveiligingsbesturingselementen
ConfigurationId tekenreeks Unieke id voor een specifieke configuratie scid-10000
ConfigurationImpact tekenreeks Beoordeeld effect van de configuratie op de algehele configuratiescore (1-10) 9
ConfigurationName tekenreeks Weergavenaam van de configuratie Onboarden apparaten naar Microsoft Defender voor Eindpunt
ConfigurationSubcategory tekenreeks Subcategorie of subgroep waartoe de configuratie behoort. In veel gevallen beschrijft dit specifieke mogelijkheden of functies. Apparaten onboarden
DeviceId tekenreeks Unieke id voor het apparaat in de service. 9eaf3a8b5962e0e6b1af9ec756664a9b823df2d1
DeviceName tekenreeks Fully Qualified Domain Name (FQDN) van het apparaat. johnlaptop.europe.contoso.com
IsApplicable Bool Geeft aan of de configuratie of het beleid van toepassing is Waar
IsCompliant Bool Geeft aan of de configuratie of het beleid juist is geconfigureerd Valse
IsExpectedUserImpact Bool Geeft aan of er gevolgen voor de gebruiker zijn als de configuratie wordt toegepast Waar
OSPlatform tekenreeks Platform van het besturingssysteem dat op het apparaat wordt uitgevoerd. Dit geeft specifieke besturingssystemen aan, inclusief variaties binnen dezelfde familie, zoals Windows 10 en Windows 11. Zie Microsoft Defender Vulnerability Management ondersteunde besturingssystemen en platforms (MDVM) voor meer informatie. Windows10 en Windows 11
RbacGroupName tekenreeks De RBAC-groep (op rollen gebaseerd toegangsbeheer). Als dit apparaat niet is toegewezen aan een RBAC-groep, is de waarde 'Niet toegewezen'. Als de organisatie geen RBAC-groepen bevat, is de waarde 'Geen'. Servers
RecommendationReference tekenreeks Een verwijzing naar de aanbevelings-id met betrekking tot deze software. sca-_-scid-20000
Tijdstempel tekenreeks De laatste keer dat de configuratie is gezien op het apparaat 2020-11-03 10:13:34.8476880

1.6 Voorbeelden

1.6.1 Voorbeeld van aanvraag

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

1.6.2 Voorbeeld van antwoord

{
    "@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. Veilige configuratie-evaluatie exporteren (via bestanden)

Beschrijving van API-methode 2.1

Dit API-antwoord bevat de beveiligde configuratie-evaluatie op uw blootgestelde apparaten en retourneert een vermelding voor elke unieke combinatie van DeviceId, ConfigurationId.

2.1.1 Beperkingen

Tariefbeperkingen voor deze API zijn 5 aanroepen per minuut en 20 aanroepen per uur.

2.2 Machtigingen

Een van de volgende machtigingen is vereist om deze API aan te roepen. Zie Use Microsoft Defender voor Eindpunt API's (Api's voor Microsoft Defender voor Eindpunt gebruiken) voor meer informatie, waaronder het kiezen van machtigingen.

Machtigingstype Machtiging Weergavenaam van machtiging
Toepassing Vulnerability.Read.All 'Informatie over beveiligingsproblemen in bedreigings- en beveiligingsbeheer lezen'
Gedelegeerd (werk- of schoolaccount) Vulnerability.Read 'Informatie over beveiligingsproblemen in bedreigings- en beveiligingsbeheer lezen'

2.3 URL

GET /api/machines/SecureConfigurationsAssessmentExport

Parameters

  • sasValidHours: het aantal uren dat de download-URL's geldig zijn (maximaal 24 uur).

2.5 Eigenschappen

Opmerking

  • De bestanden zijn gzip gecomprimeerd & in Json-indeling met meerdere regels.
  • De download-URL's zijn slechts 3 uur geldig; anders kunt u de parameter gebruiken.
  • Voor een maximale downloadsnelheid van uw gegevens kunt u ervoor zorgen dat u downloadt vanuit dezelfde Azure-regio waarin uw gegevens zich bevinden.

Eigenschap (id) Gegevenstype: Beschrijving Voorbeeld van een geretourneerde waarde
Bestanden exporteren matrix[tekenreeks] Een lijst met download-URL's voor bestanden met de huidige momentopname van de organisatie ["Https://tvmexportstrstgeus.blob.core.windows.net/tvm-export...1", "https://tvmexportstrstgeus.blob.core.windows.net/tvm-export...2"]
GeneratedTime tekenreeks Het tijdstip waarop de export is gegenereerd. 2021-05-20T08:00:00Z

2.6 Voorbeelden

2.6.1 Voorbeeld van aanvraag

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

2.6.2 Voorbeeld van antwoord

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

Zie ook

Overige gerelateerde

Tip

Wil je meer weten? Engage met de Microsoft Security-community in onze Tech Community: Microsoft Defender voor Eindpunt Tech Community.