Поделиться через

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

  • Статья

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

Важно!

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

Хотите попробовать 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

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

Ограничения

  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).

Примечание.

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

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

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

Разрешения

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

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

HTTP-запрос

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

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

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

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

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

Команды

Тип команды Параметры Описание
PutFile Ключ: FileName

Значение: <имя файла>

 Помещает файл из библиотеки на устройство. Файлы сохраняются в рабочей папке и удаляются при перезапуске устройства по умолчанию. ПРИМЕЧАНИЕ. Не имеет результата ответа.
RunScript Ключ: ScriptName
Значение: <скрипт из библиотеки>

Ключ: Args
Значение: <аргументы скрипта>

 Выполняет скрипт из библиотеки на устройстве.

Параметр Args передается в скрипт.

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

Отклик

  • В случае успешного выполнения этот метод возвращает значение 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": "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"
                    }
                ]
            }
        }
    ]
}

Совет

Хотите узнать больше? Обратитесь к сообществу Майкрософт по безопасности в техническом сообществе Microsoft Defender для конечной точки Tech Community.