Добавление, обновление и удаление определения сканирования

Статья
08/14/2024

Область применения:

Хотите попробовать Microsoft Defender для конечной точки? Зарегистрироваться для бесплатной пробной версии.

Хотите испытать Управление уязвимостями Microsoft Defender? Узнайте больше о том, как зарегистрироваться в общедоступной пробной версии Управление уязвимостями Microsoft Defender.

Важно!

Некоторые сведения относятся к предварительно выпущенному продукту, который может быть существенно изменен перед выпуском. Корпорация Майкрософт не дает явных или подразумеваемых гарантий относительно предоставленных здесь сведений.

Примечание.

Если вы являетесь клиентом для государственных организаций США, используйте URI, перечисленные в Microsoft Defender для конечной точки для клиентов государственных организаций США.

Совет

Для повышения производительности можно использовать сервер ближе к географическому расположению:

us.api.security.microsoft.com
eu.api.security.microsoft.com
uk.api.security.microsoft.com
au.api.security.microsoft.com
swa.api.security.microsoft.com
ina.api.security.microsoft.com

Описание API

API для добавления, обновления или удаления проверки, прошедшей проверку подлинности.

Ограничения

Ограничения скорости для этого API — 100 вызовов в минуту и 1500 вызовов в час.

Вы можете опубликовать публикацию на компьютерах, которые видели в последний раз в соответствии с настроенным периодом хранения.

Разрешения

Для вызова этого API требуется одно из следующих разрешений. Дополнительные сведения, включая выбор разрешений, см. в статье Использование API Defender для конечных точек.

Тип разрешения	Разрешение	Отображаемое имя разрешения
Приложение	Machine.ReadWrite.All	Чтение и запись всех сведений о сканировании.
Делегированные (рабочая или учебная учетная запись)	Machine.Read.Write	Чтение и запись всех сведений о сканировании.

При получении маркера с использованием учетных данных пользователя:

Для просмотра данных пользователь должен иметь по крайней мере следующее разрешение роли: ViewData или TvmViewData (см. раздел Создание ролей и управление ими).
Чтобы изменить данные, пользователь должен иметь по крайней мере следующее разрешение роли: ManageSecurity (см. раздел Создание ролей и управление ими).

HTTP-запрос

POST https://api.securitycenter.microsoft.com/api/DeviceAuthenticatedScanDefinitions

Заголовки запросов

Имя	Тип	Описание
Авторизация	String	Bearer {token}. Обязательное поле.
Content-Type	string	application/json. Обязательное поле.

Текст запроса

В тексте запроса укажите объект JSON со следующими параметрами:

Параметр	Тип	Описание
`scanType`	Перечисление	Тип сканирования. Возможные значения: "Windows", "Сеть". Обязательное поле.
`scanName`	String	Имя сканирования. Обязательное поле.
`isActive`	Логический	Состояние активного выполнения сканирования. Обязательное поле.
`target`	String	Список целевых объектов, разделенных запятыми, ip-адреса или имена узлов. Обязательное поле.
`intervalInHours`	Целое	Интервал, через который выполняется сканирование. Обязательное поле.
`targetType`	String	Тип целевого объекта в целевом поле. Возможные типы: "IP-адрес" или "имя узла". Значение по умолчанию — IP-адрес. Обязательное поле.
`scannerAgent`	Объект	идентификатор компьютера. Обязательный.
`scanAuthenticationParams`	Объект	Объект, представляющий параметры проверки подлинности, см . раздел Свойства объекта параметров проверки подлинности для ожидаемых полей. Это свойство является обязательным при создании новой проверки и необязательным при обновлении сканирования.

Отклик

В случае успешного выполнения этот метод возвращает код ответа 200 — ОК и новое или обновленное определение сканирования в тексте ответа.

Пример запроса на добавление нового сканирования

Ниже приведен пример запроса, который добавляет новое сканирование.

POST https://api.securitycenter.microsoft.com/api/DeviceAuthenticatedScanDefinitions

 {
"scanType": "Windows", 
"scanName": "Test Windows scan", 
"isActive": true, 
"target": "127.0.0.1", 
"intervalInHours": 1, 
"targetType": "Ip",
"scannerAgent": {
    "machineId": "eb663a27ae9d032f61bc268a79eedf14c4b90f77",
},
"scanAuthenticationParams": { 
    "@odata.type": "#microsoft.windowsDefenderATP.api.WindowsAuthParams", 
    "type": "Kerberos", 
    "username": "username", 
    "domain": "password",
    "isGmsaUser": true
    }
}

Пример отклика

Ниже приведен пример отклика.

 {
"@odata.context": "https://api.securitycenter.microsoft.com/api/$metadata#DeviceAuthenticatedScanDefinitions/$entity",
    "id": "289224fb-1686-472c-9751-5555960854ca",
    "scanType": "Windows",
    "scanName": "Test Windows scan",
    "isActive": true,
    "target": "127.0.0.1",
    "orgId": "0335a792-18d2-424b-aeed-559567054570",
    "intervalInHours": 1,
    "createdBy": "username@test.com",
    "targetType": "Ip",
    "scanAuthenticationParams": null,
    "scannerAgent": {
        "id": "0335a792-18d2-424b-aeed-559567054570_ eb663a27ae9d032f61bc268a79eedf14c4b90f77",
        "machineId": "eb663a27ae9d032f61bc268a79eedf14c4b90f77",
        "machineName": "DESKTOP-TEST",
        "lastSeen": "2023-01-04T09:40:03.2787058Z",
        "assignedApplicationId": "ae4a5cde-b4a1-4b76-8635-458b2cf15752",
        "scannerSoftwareVersion": "7.6.0.0",
        "lastCommandExecutionTimestamp": "2023-01-04T09:33:16Z",
        "mdeClientVersion": "10.8295.22621.1010"
    },
    "latestScan": {
        "status": null,
        "failureReason": null,
        "executionDateTime": null
    }

}

Пример запроса на обновление сканирования

Ниже приведен пример запроса, который обновляет проверку.

PATCH  https://api.securitycenter.microsoft.com/api/DeviceAuthenticatedScanDefinitions/289224fb-1686-472c-9751-5555960854ca

{
"scanName": "Test Update Windows scan", 
"isActive": false, 
"target": "127.0.0.2,127.0.0.3", 
"intervalInHours": 1, 
"targetType": "Ip",
"scanAuthenticationParams": { 
    "@odata.type": "#microsoft.windowsDefenderATP.api.WindowsAuthParams", 
    "type": "Kerberos", 
    "username": "username", 
    "domain": "password",
    "isGmsaUser": true
    }
 }

Пример ответа