导出每个设备的安全配置评估
适用于：
- Microsoft Defender for Endpoint 计划 1
- Microsoft Defender for Endpoint 计划 2
- Microsoft Defender 漏洞管理
- Microsoft Defender XDR
希望体验 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技术社区。