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

  • Применяется к: Microsoft Defender for Endpoint Plan 1 and Plan 2

Важно!

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

Предварительные условия

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

Поддерживаемые операционные системы

Описание API

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

Ограничения

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

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

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

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

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

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

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

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

  • Действия динамического ответа, инициированные со страницы устройства, недоступны в machineactions API.

Разрешения

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

Тип разрешения Разрешение Отображаемое имя разрешения
Приложение Machine.LiveResponse Запуск динамического ответа на определенном компьютере
Делегированные (рабочая или учебная учетная запись) Machine.LiveResponse Запуск динамического ответа на определенном компьютере

HTTP-запрос

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

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

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

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

Параметр Тип Описание
Comment String Комментарий для связывания с действием.
Команды Array Команды для выполнения. Допустимые значения: PutFile, RunScript, GetFile (должны находиться в этом порядке без ограничений на повторения).

Команды

Тип команды Параметры Описание
PutFile Ключ: FileName
Значение: <имя файла>		 Помещает файл из библиотеки на устройство. Files сохраняются в рабочей папке и удаляются при перезапуске устройства по умолчанию. ПРИМЕЧАНИЕ. Не имеет результата ответа.
RunScript Ключ: ScriptName
Значение: <скрипт из библиотеки>
Ключ: Args
Значение: <аргументы скрипта>		 Выполняет скрипт из библиотеки на устройстве.
Параметр Args передается в скрипт.
Время ожидания через 10 минут.
GetFile Ключ: Путь
Значение: <путь к файлу>		 Сбор файла с устройства. ПРИМЕЧАНИЕ. Необходимо экранировать обратные косые слэши в пути.

Отклик

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

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

Пример

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

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

POST https://api.security.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 201 Created

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

{
    "@odata.context": "https://api.security.microsoft.com/api/$metadata#MachineActions/$entity",
    "id": "{machine_action_id}",
    "type": "LiveResponse",
    "requestor": "analyst@microsoft.com",
    "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"
                    }
                ]
            }
        }
    ]
}
  • Last updated on