Экспорт инвентаризации сертификатов на устройство
Область применения:
- Microsoft Defender для конечной точки (план 1)
- Microsoft Defender для конечной точки (план 2)
- Управление уязвимостями в Microsoft Defender
- Microsoft Defender XDR
Хотите испытать Управление уязвимостями Microsoft Defender? Узнайте больше о том, как зарегистрироваться в общедоступной пробной версии Управление уязвимостями Microsoft Defender.
Существуют различные вызовы API для получения разных типов данных. Как правило, каждый вызов API содержит необходимые данные для устройств в вашей организации.
Ответ JSON API извлекает все данные в организации в виде ответов JSON. Этот метод лучше всего подходит для небольших организаций с менее чем 100 тыс. устройств. Ответ разбиется на страницы, поэтому для получения следующих результатов можно использовать поле @odata.nextLink из ответа.
через файлы Это решение API позволяет быстрее и надежнее извлекать большие объемы данных. Поэтому рекомендуется использовать его для крупных организаций с более чем 100 тыс. устройств. Этот API извлекает все данные в вашей организации в виде файлов скачивания. Ответ содержит URL-адреса для скачивания всех данных из службы хранилища Azure. Данные из службы хранилища Azure можно скачать следующим образом:
- Вызовите API, чтобы получить список URL-адресов для скачивания со всеми данными организации.
- Скачайте все файлы с помощью URL-адресов для скачивания и обработайте данные по мере того, как вам нравится.
Данные, собираемые с помощью ответа JSON или с помощью файлов, являются текущим snapshot текущего состояния. Он не содержит исторических данных. Для сбора исторических данных клиенты должны сохранять данные в собственных хранилищах данных.
Примечание.
Если не указано иное, все перечисленные методы оценки базовых показателей безопасности экспорта полностью экспортируются и по устройству (также называются по устройству).
1. Экспорт оценки сертификата (ответ JSON)
1.1 Описание метода API
Возвращает все оценки сертификатов для всех устройств на основе каждого устройства. Он возвращает таблицу с отдельной записью для каждого уникального сочетания DeviceId, Thumbprint и Path.
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/certificateAssessmentByMachine
1.4 Параметры
- pageSize (по умолчанию = 50 000): количество результатов в ответе.
- $top: число возвращаемых результатов (не возвращает @odata.nextLink и поэтому не извлекет все данные).
1.5. Свойства (ответ JSON)
Примечание.
Каждая запись составляет примерно 1 КБ данных. Это следует учитывать при выборе правильного параметра pageSize.
В ответе могут быть возвращены некоторые дополнительные столбцы. Эти столбцы являются временными и могут быть удалены. Используйте только задокументированные столбцы.
Свойства, определенные в следующей таблице, перечислены в алфавитном порядке по идентификатору свойства. При запуске этого API результирующие выходные данные не обязательно будут возвращаться в том же порядке, что и в этой таблице.
| Свойство (идентификатор) | Тип данных | Описание |
|---|---|---|
| DeviceId | String | Уникальный идентификатор устройства в службе. |
| DeviceName | String | Полное доменное имя (FQDN) устройства. |
| Thumbprint | Логический | Уникальный идентификатор сертификата. |
| Path | String | Расположение сертификата. |
| SignatureAlgorithm | String | Используемый алгоритм хэширования и шифрования. |
| KeySize | String | Размер ключа, используемого в алгоритме подписи. |
| ExpirationDate | String | Дата и время, после которых сертификат больше не действителен. |
| IssueDate | String | Самая ранняя дата и время вступления сертификата в силу. |
| SubjectType | String | Указывает, является ли владелец сертификата ЦС или конечной сущностью. |
| Серийный номер. | String | Уникальный идентификатор сертификата в системах центра сертификации. |
| IssuedTo | Объект | Сущность, к которой принадлежит сертификат; может быть устройством, отдельным лицом или организацией. |
| IssuedBy | Объект | Сущность, которая проверила сведения и подписала сертификат. |
| KeyUsage | String | Допустимый криптографический использует открытый ключ сертификата. |
| ExtendedKeyUsage | String | Другие допустимые варианты использования сертификата. |
| RbacGroupId | String | Идентификатор группы управления доступом на основе ролей (RBAC). |
| RbacGroupName | String | Группа управления доступом на основе ролей (RBAC). Если это устройство не назначено ни одной группе RBAC, значение будет "Unassigned". Если в организации нет групп RBAC, значение будет "Нет". |
1.6. Пример
1.6.1. Пример запроса
GET https://api.securitycenter.microsoft.com/api/machines/CertificateAssessmentByMachine
1.6.2. Пример ответа
{
"@odata.context":"https://127.0.0.1/api/$metadata#Collection(microsoft.windowsDefenderATP.api.AssetCertificateAssessment)",
"value":[
{
"deviceId":"49126b9e4a5473b5229c73799e9e55c48668101b",
"deviceName":"testmachine5",
"thumbprint":"A4B37F4F6DE956922273D5CB8E7E0AAFB7033B90",
"path":"LocalMachine\\TestSignRoot\\A4B37F4F6DE956922273D5CB8E7E0AAFB7033B90",
"signatureAlgorithm":"sha384ECDSA",
"keyLength":0,"notAfter":"0001-01-01T00:00:00Z",
"notBefore":"0001-01-01T00:00:00Z",
"subjectType":"CA",
"serialNumber":"6086A185EAFA2B9943B4671603F40323",
"subjectObject":null,
"issuerObject":null,
"keyUsageArray":null,
"extendedKeyUsageArray":null,
"isSelfSigned":false,
"rbacGroupId":4226,
"rbacGroupName":"testO6343398Gq31"}],
"@odata.nextLink":"https://127.0.0.1/api/machines/CertificateAssessmentByMachine?pagesize=1&$skiptoken=eyJFeHBvcnREZWZpbml0aW9uIjp7IlRpbWVQYXRoIjoiMjAyMi0wMy0yMS8wNTAxLyJ9LCJFeHBvcnRGaWxlSW5kZXgiOjAsIkxpbmVTdG9wcGVkQXQiOjF9"
}
2. Экспорт оценки сертификата (с помощью файлов)
2.1. Описание метода API
Возвращает все оценки сертификатов для всех устройств на основе каждого устройства. Он возвращает таблицу с отдельной записью для каждого уникального сочетания DeviceId, Thumbprint и Path.
2.1.1. Ограничения
- Ограничения скорости для этого API : 5 вызовов в минуту и 20 вызовов в час.
2.2 Разрешения
Для вызова этого API требуется одно из следующих разрешений. Дополнительные сведения, включая выбор разрешений, см. в статье Использование API Microsoft Defender для конечной точки.
| Тип разрешения | Разрешение | Отображаемое имя разрешения |
|---|---|---|
| Приложение | Vulnerability.Read.All | "Чтение сведений о программном обеспечении для управления угрозами и уязвимостями" |
| Делегированные (рабочая или учебная учетная запись) | Vulnerability.Read | "Чтение сведений о программном обеспечении для управления угрозами и уязвимостями" |
URL-адрес 2.3
GET /api/machines/certificateAssessmentExport
2.4. Параметры
- sasValidHours: количество часов, в течение которых будут действовать URL-адреса скачивания (максимум 24 часа).
2.5. Свойства (ответ JSON)
Примечание.
Файлы сжаты gzip & в многострочных форматах JSON.
URL-адреса для скачивания действительны только в течение 3 часов; В противном случае можно использовать параметр .
Чтобы увеличить скорость загрузки, убедитесь, что данные загружаются из того же региона Azure, где находятся данные.
Каждая запись составляет примерно 1 КБ данных. Это следует учитывать при выборе подходящего параметра pageSize.
В ответе могут быть возвращены некоторые дополнительные столбцы. Эти столбцы являются временными и могут быть удалены. Используйте только задокументированные столбцы.
| Свойство (идентификатор) | Тип данных | Описание |
|---|---|---|
| Экспорт файлов | String[array] | Список URL-адресов для скачивания файлов, содержащих текущие snapshot организации. |
| GeneratedTime | DateTime | Время создания экспорта. |
2.6. Пример
2.6.1. Пример запроса
GET https://api.securitycenter.contoso.com/api/machines/certificateAssessmentExport
2.6.2. Пример ответа
{
"@odata.context":"https://127.0.0.1/api/$metadata#microsoft.windowsDefenderATP.api.ExportFilesResponse",
"exportFiles":["https://tvmexportexternalstgeus.blob.core.windows.net/temp-5c080622-f613-42bb-9fee-e17ccdff90d3/2022-03-20/1318/CertificateAssessmentExport/json/OrgId=47d41a0c-188d-46d3-bbea-a93dbc0bfcaa/_RbacGroupId=4226/part-00000-65a62a9d-7a01-4d78-bbdb-6d3e07b34cc9.c000.json.gz?sv=2020-02-10&st=2022-03-20T13%3A35%3A37Z&se=2022-03-20T16%3A35%3A37Z&sr=b&sp=r&sig=IMmwTOYmGvU0ei5AHLNAxnFCmZkE2jvBHzRmuAu9xaA%3D","https://tvmexportexternalstgeus.blob.core.windows.net/temp-5c080622-f613-42bb-9fee-e17ccdff90d3/2022-03-20/1318/CertificateAssessmentExport/json/OrgId=47d41a0c-188d-46d3-bbea-a93dbc0bfcaa/_RbacGroupId=4414/part-00000-65a62a9d-7a01-4d78-bbdb-6d3e07b34cc9.c000.json.gz?sv=2020-02-10&st=2022-03-20T13%3A35%3A37Z&se=2022-03-20T16%3A35%3A37Z&sr=b&sp=r&sig=2r0y74WZsATa0DjQTwfBxNqL5vN2Wl0AZKHMNrxuJ30%3D","https://tvmexportexternalstgeus.blob.core.windows.net/temp-5c080622-f613-42bb-9fee-e17ccdff90d3/2022-03-20/1318/CertificateAssessmentExport/json/OrgId=47d41a0c-188d-46d3-bbea-a93dbc0bfcaa/_RbacGroupId=75/part-00000-65a62a9d-7a01-4d78-bbdb-6d3e07b34cc9.c000.json.gz?sv=2020-02-10&st=2022-03-20T13%3A35%3A37Z&se=2022-03-20T16%3A35%3A37Z&sr=b&sp=r&sig=uVdY4%2BBpMdPMwaD3G0RJTZkS4R9J8oN8I3tu%2FOcG35c%3D"],
"generatedTime":"2022-03-20T13:18:00Z"
}
Совет
Хотите узнать больше? Engage с сообществом Microsoft Security в нашем техническом сообществе: Microsoft Defender для конечной точки Техническое сообщество.