Выполнение динамических команд ответа на устройстве

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

• Microsoft Defender для конечной точки (план 2)

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

Описание API

Выполняет последовательность команд динамического ответа на устройстве

Ограничения

1. Ограничения скорости для этого API — 10 вызовов в минуту (на дополнительные запросы отвечает HTTP 429).

2. 25 одновременно выполняющихся сеансов (запросы, превышающие ограничение регулирования, получают ответ "429 — слишком много запросов").

3. Если компьютер недоступен, сеанс помещается в очередь на срок до трех дней.

4. Время ожидания команды RunScript через 10 минут.

5. Команды динамического ответа не могут быть поставлены в очередь и могут выполняться только по одному за раз.

6. Если компьютер, на котором вы пытаетесь выполнить этот вызов API, находится в группе устройств RBAC, для которых не назначен уровень автоматического исправления, необходимо как минимум включить минимальный уровень исправления для данной группы устройств.

   Примечание.

   Создание группы устройств поддерживается в Defender для конечной точки плана 1 и плана 2.

7. В одном вызове API можно выполнить несколько команд динамического ответа. Однако при сбое команды динамического ответа все последующие действия не будут выполняться.

8. На одном компьютере невозможно выполнить несколько сеансов динамического ответа (если действие динамического ответа уже выполняется, на последующие запросы отвечает HTTP 400 — ActiveRequestAlreadyExists).

Минимальные требования

Прежде чем начать сеанс на устройстве, убедитесь, что выполнены следующие требования:

• Убедитесь, что используется поддерживаемая версия Windows, macOS или Linux.

  Устройства должны работать под управлением одного из следующих компонентов:

  • Windows 11

  • Windows 10

    • Версия 1909 или более поздняя
    • Версия 1903 с KB4515384
    • Версия 1809 (RS 5) с KB4537818
    • Версия 1803 (RS 4) с KB4537795
    • Версия 1709 (RS 3) с KB4537816

  • Windows Server 2019 — применимо только для общедоступной предварительной версии

    • Версия 1903 или (с KB4515384) более поздняя
    • Версия 1809 (с KB4537818)

  • Windows Server 2022

  • macOS(требуются дополнительные профили конфигурации)

    • 13 (Вентура)
    • 12 (Монтерей)
    • 11 (Большой Сур)

  • Linux

    • Поддерживаемые дистрибутивы серверов Linux и версии ядра

Разрешения

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

HTTP-запрос

POST https://api.securitycenter.microsoft.com/API/machines/{machine_id}/runliveresponse

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

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

Команды

Отклик

• В случае успешного выполнения этот метод возвращает значение 201 Created.

  Сущность действия. Если компьютер с указанным идентификатором не найден — 404 Не найдено.

Пример

Пример запроса

Ниже приведен пример запроса.

POST https://api.securitycenter.microsoft.com/api/machines/1e5bc9d7e413ddd7902c2932e418702b84d0cc07/runliveresponse

```JSON
{
   "Commands":[
      {
         "type":"RunScript",
         "params":[
            {
               "key":"ScriptName",
               "value":"minidump.ps1"
            },
            {
               "key":"Args",
               "value":"OfficeClickToRun"
            }

         ]
      },
      {
         "type":"GetFile",
         "params":[
            {
               "key":"Path",
               "value":"C:\\windows\\TEMP\\OfficeClickToRun.dmp.zip"
            }
         ]
      }
   ],
   "Comment":"Testing Live Response API"
}

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

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

Возможные значения для состояния каждой команды: "Создано", "Завершено" и "Сбой".

HTTP/1.1 200 Ok

Тип содержимого: application/json

{
    "@odata.context": "https://api.securitycenter.microsoft.com/api/$metadata#MachineActions/$entity",
    "id": "{machine_action_id}",
    "type": "LiveResponse",
    "requestor": "[email protected]",
    "requestorComment": "Testing Live Response API",
    "status": "Pending",
    "machineId": "{machine_id}",
    "computerDnsName": "hostname",
    "creationDateTimeUtc": "2021-02-04T15:36:52.7788848Z",
    "lastUpdateDateTimeUtc": "2021-02-04T15:36:52.7788848Z",
    "errorHResult": 0,
    "commands": [
        {
            "index": 0,
            "startTime": null,
            "endTime": null,
            "commandStatus": "Created",
            "errors": [],
            "command": {
                "type": "RunScript",
                "params": [
                    {
                        "key": "ScriptName",
                        "value": "minidump.ps1"
                    },{
                        "key": "Args",
                        "value": "OfficeClickToRun"
                    }
                ]
            }
        }, {
            "index": 1,
            "startTime": null,
            "endTime": null,
            "commandStatus": "Created",
            "errors": [],
            "command": {
                "type": "GetFile",
                "params": [{
                        "key": "Path", "value": "C:\\windows\\TEMP\\OfficeClickToRun.dmp.zip"
                    }
                ]
            }
        }
    ]
}

Статьи по теме

• Получение API действий компьютера
• Получение результата реагирования в реальном времени
• Отмена действия компьютера