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

Статья
04/27/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

Описание API

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

Ограничения

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

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

Разрешения

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

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

Примечание.

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

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

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

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