导出每个设备的安全配置评估

项目
04/27/2024

适用于：

希望体验 Microsoft Defender for Endpoint？注册免费试用版。

返回每个设备的所有配置及其状态。

可通过不同的 API 调用来获取不同类型的数据。由于数据量可能很大，因此可通过两种方式检索数据：

导出安全配置评估 JSON 响应：API 将组织中的所有数据作为 Json 响应拉取。此方法最适合 设备少于 100-K 的小型组织。响应是分页的，因此可以使用响应中的 @odata.nextLink 字段来提取下一个结果。
通过文件导出安全配置评估：此 API 解决方案支持更快、更可靠地拉取大量数据。因此，建议将它用于具有 100-K 个以上的设备的大型组织。此 API 将组织中的所有数据作为下载文件拉取。响应包含用于从 Azure 存储下载所有数据的 URL。通过此 API，可以从 Azure 存储下载所有数据，如下所示：
- 调用 API 以获取包含所有组织数据的下载 URL 列表。
- 使用下载 URL 下载所有文件，并根据需要处理数据。

使用 JSON 响应或通过文件) (收集的数据是当前状态的当前快照，不包含历史数据。为了收集历史数据，客户必须将数据保存在自己的数据存储中。

注意

除非另有说明，否则列出的所有导出评估方法是 完全导出 ， 并且按设备 (也称为 按设备) 。

1. 导出安全配置评估 (JSON 响应)

1.1 API 方法说明

此 API 响应包含公开设备上的安全配置评估，并返回 DeviceId、ConfigurationId 的每个唯一组合的条目。

1.1.1 限制

最大页面大小为 200,000。
此 API 的速率限制是每分钟 30 个调用和每小时 1000 个调用。

1.2 权限

要调用此 API，需要以下权限之一。若要了解详细信息（包括如何选择权限），请参阅使用Microsoft Defender for Endpoint API 了解详细信息。

权限类型	权限	权限显示名称
应用程序	Vulnerability.Read.All	“读取威胁和漏洞管理漏洞信息”
委派（工作或学校帐户）	Vulnerability.Read	“读取威胁和漏洞管理漏洞信息”

1.3 URL

GET /api/machines/SecureConfigurationsAssessmentByMachine

1.4 参数

pageSize (默认值 = 50,000) ：响应结果数。
$top：要返回 (的结果数不会返回@odata.nextLink，因此不会拉取所有数据) 。

1.5 属性

注意

下表中定义的属性按属性 ID 按字母顺序列出。运行此 API 时，生成的输出不一定按此表中列出的相同顺序返回。
响应中可能会返回一些其他列。这些列是临时的，可能会删除，请仅使用记录的列。

属性 (ID)	数据类型	说明	返回值的示例
ConfigurationCategory	string	配置所属的类别或分组：应用程序、OS、网络、帐户、安全控件	安全控制措施
ConfigurationId	string	特定配置的唯一标识符	scid-10000
ConfigurationImpact	string	配置对总体配置评分的影响程度 (1-10)	9
ConfigurationName	string	配置的显示名称	将设备载入到 Microsoft Defender for Endpoint
ConfigurationSubcategory	string	配置所属的子类别或子组。在许多情况下，它用于描述特定的功能。	载入设备
DeviceId	string	服务中设备的唯一标识符。	9eaf3a8b5962e0e6b1af9ec756664a9b823df2d1
DeviceName	string	设备的 FQDN) (完全限定的域名。	johnlaptop.europe.contoso.com
IsApplicable	布尔值	指示配置或策略是否适用	true
IsCompliant	布尔值	指示是否正确配置了配置或策略	false
IsExpectedUserImpact	布尔值	指示如果应用配置，是否会对用户造成影响	true
OSPlatform	string	在设备上运行的操作系统的平台。这表示特定的操作系统，包括同一系列中的变体，例如Windows 10和Windows 11。有关详细信息，请参阅 Microsoft Defender 漏洞管理 (MDVM) 支持的操作系统和平台。	Windows10 和 Windows 11
RbacGroupName	string	基于角色的访问控制 (RBAC) 组。如果此设备未分配给任何 RBAC 组，则值为“未分配”。如果组织不包含任何 RBAC 组，则值为“无”。	服务器
RecommendationReference	string	对与此软件相关的建议 ID 的引用。	sca-_-scid-20000
Timestamp	string	上次在设备上看到配置的时间	2020-11-03 10:13:34.8476880

1.6 示例

1.6.1 请求示例

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

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. 通过文件) 导出安全配置评估 (

2.1 API 方法说明

此 API 响应包含公开设备上的安全配置评估，并返回 DeviceId、ConfigurationId 的每个唯一组合的条目。

2.1.1 限制

此 API 的速率限制是每分钟 5 个调用和每小时 20 个调用。

2.2 权限

要调用此 API，需要以下权限之一。若要了解详细信息（包括如何选择权限），请参阅使用 Microsoft Defender for Endpoint API 了解详细信息。

权限类型	权限	权限显示名称
应用程序	Vulnerability.Read.All	“读取威胁和漏洞管理漏洞信息”
委派（工作或学校帐户）	Vulnerability.Read	“读取威胁和漏洞管理漏洞信息”

2.3 URL

GET /api/machines/SecureConfigurationsAssessmentExport

参数

sasValidHours：下载 URL 在最长 24 小时) (有效小时数。

2.5 属性

注意

这些文件是多行 Json 格式的 gzip 压缩 &。
下载 URL 仅在 3 小时内有效;否则可以使用参数。
为了获得数据的最大下载速度，可以确保从数据所在的同一 Azure 区域进行下载。

属性 (ID)	数据类型	说明	返回值的示例
导出文件	array[string]	保存组织当前快照的文件的下载 URL 列表	["Https://tvmexportstrstgeus.blob.core.windows.net/tvm-export...1", "https://tvmexportstrstgeus.blob.core.windows.net/tvm-export...2"]
GeneratedTime	string	生成导出的时间。	2021-05-20T08：00：00Z

2.6 示例

2.6.1 请求示例

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

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

另请参阅

其他相关

提示

想要了解更多信息？ Engage技术社区中的 Microsoft 安全社区：Microsoft Defender for Endpoint技术社区。