Экспорт оценки безопасной конфигурации на устройство
Область применения:
- Microsoft Defender для конечной точки (план 1)
- Microsoft Defender для конечной точки (план 2)
- Управление уязвимостями в Microsoft Defender
- Microsoft Defender XDR
Хотите попробовать Microsoft Defender для конечной точки? Зарегистрироваться для бесплатной пробной версии.
Возвращает все конфигурации и их состояние для каждого устройства.
Существуют различные вызовы API для получения разных типов данных. Так как объем данных может быть большим, их можно извлечь двумя способами:
Экспорт ответа JSON оценки безопасной конфигурации. API извлекает все данные в организации в виде ответов JSON. Этот метод лучше всего подходит для небольших организаций с менее чем 100 тыс. устройств. Ответ разбиется на страницы, поэтому для получения следующих результатов можно использовать поле @odata.nextLink из ответа.
Экспорт безопасной оценки конфигурации с помощью файлов. Это решение API позволяет быстрее и надежнее извлекать большие объемы данных. Поэтому рекомендуется использовать его для крупных организаций с более чем 100-тысячными устройствами. Этот API извлекает все данные в вашей организации в виде файлов скачивания. Ответ содержит URL-адреса для скачивания всех данных из службы хранилища Azure. Этот API позволяет скачать все данные из службы хранилища Azure следующим образом:
Вызовите API, чтобы получить список URL-адресов для скачивания со всеми данными организации.
Скачайте все файлы с помощью URL-адресов для скачивания и обработайте данные по мере того, как вам нравится.
Собираемые данные (с помощью ответа JSON или файлов) являются текущим snapshot текущего состояния и не содержат исторических данных. Чтобы собирать исторические данные, клиенты должны сохранять их в собственных хранилищах данных.
Примечание.
Если не указано иное, все перечисленные методы оценки экспорта полностью экспортируются и по устройству (также называются по устройству).
1. Экспорт оценки безопасной конфигурации (ответ JSON)
1.1 Описание метода API
Этот ответ API содержит оценку безопасной конфигурации на доступных устройствах и возвращает запись для каждой уникальной комбинации DeviceId и ConfigurationId.
1.1.1. Ограничения
Максимальный размер страницы — 200 000.
Ограничения скорости для этого API: 30 вызовов в минуту и 1000 вызовов в час.
1.2 Разрешения
Для вызова этого API требуется одно из следующих разрешений. Дополнительные сведения, включая выбор разрешений, см. в статье Использование API Microsoft Defender для конечной точки.
| Тип разрешения | Разрешение | Отображаемое имя разрешения |
|---|---|---|
| Приложение | Vulnerability.Read.All | "Чтение сведений об уязвимостях управления угрозами и уязвимостями" |
| Делегированные (рабочая или учебная учетная запись) | Vulnerability.Read | "Чтение сведений об уязвимостях управления угрозами и уязвимостями" |
URL-адрес 1.3
GET /api/machines/SecureConfigurationsAssessmentByMachine
1.4 Параметры
- pageSize (по умолчанию = 50 000): количество результатов в ответе.
- $top: число возвращаемых результатов (не возвращает @odata.nextLink и, следовательно, не извлекает все данные).
1.5. Свойства
Примечание.
- Свойства, определенные в следующей таблице, перечислены в алфавитном порядке по идентификатору свойства. При запуске этого API результирующие выходные данные не обязательно будут возвращаться в том же порядке, что и в этой таблице.
- В ответе могут быть возвращены некоторые дополнительные столбцы. Эти столбцы являются временными и могут быть удалены. Используйте только задокументированные столбцы.
| Свойство (идентификатор) | Тип данных | Описание | Пример возвращаемого значения |
|---|---|---|---|
| ConfigurationCategory | string | Категория или группа, к которой относится настройка: приложение, ОС, сеть, учетные записи, элементы безопасности | Средства контроля безопасности |
| ConfigurationId | string | Уникальный идентификатор определенной настройки | scid-10000 |
| ConfigurationImpact | string | Оценка влияния настройки на общую оценку конфигурации (1–10) | 9 |
| ConfigurationName | string | Отображение названия настройки | Подключение устройств к Microsoft Defender для конечной точки |
| 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 | Ссылка на идентификатор рекомендации, связанный с этим программным обеспечением. | 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 требуется одно из следующих разрешений. Дополнительные сведения, включая выбор разрешений, см. в статье Использование API Microsoft Defender для конечной точки.
| Тип разрешения | Разрешение | Отображаемое имя разрешения |
|---|---|---|
| Приложение | Vulnerability.Read.All | "Чтение сведений об уязвимостях управления угрозами и уязвимостями" |
| Делегированные (рабочая или учебная учетная запись) | Vulnerability.Read | "Чтение сведений об уязвимостях управления угрозами и уязвимостями" |
URL-адрес 2.3
GET /api/machines/SecureConfigurationsAssessmentExport
Параметры
- sasValidHours: количество часов, в течение которых будут действовать URL-адреса скачивания (максимум 24 часа).
2.5. Свойства
Примечание.
- Файлы сжаты gzip & в многострочных форматах JSON.
- URL-адреса для скачивания действительны только в течение 3 часов; В противном случае можно использовать параметр .
- Для максимальной скорости загрузки данных можно убедиться, что вы скачиваете данные из того же региона Azure, в котором находятся данные.
| Свойство (идентификатор) | Тип данных | Описание | Пример возвращаемого значения |
|---|---|---|---|
| Экспорт файлов | array[string] | Список URL-адресов для скачивания файлов, содержащих текущий snapshot организации | ["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 Security в нашем техническом сообществе: Microsoft Defender для конечной точки Техническое сообщество.