在设备上运行实时响应命令

  • 项目

适用于：

重要

本文中的某些信息与预发行的产品有关，该产品在商业发布之前可能有重大修改。 Microsoft 对此处所提供的信息不作任何明示或默示的保证。

希望体验 Microsoft Defender for Endpoint？ 注册免费试用版。

注意

如果你是美国政府客户，请使用美国政府客户Microsoft Defender for Endpoint中列出的 URI。

提示

为了提高性能，可以使用离地理位置更近的服务器：

  • 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 for Endpoint 计划 1 和计划 2 支持创建设备组。

  7. 可以在单个 API 调用上运行多个实时响应命令。 但是，当实时响应命令失败时，不会执行所有后续操作。

  8. 如果实时响应操作已在运行，则无法在同一 (台计算机上执行多个实时响应会话，后续请求将使用 HTTP 400 - ActiveRequestAlreadyExists) 响应。

注意

从“设备”页启动的实时响应操作在 machineactions API 中不可用。

最低要求

在设备上启动会话之前，请确保满足以下要求：

权限

要调用此 API，需要以下权限之一。 若要了解详细信息（包括如何选择权限），请参阅 入门。

权限类型 权限 权限显示名称
应用程序 Machine.LiveResponse 在特定计算机上运行实时响应
委派（工作或学校帐户） Machine.LiveResponse 在特定计算机上运行实时响应

HTTP 请求

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

请求标头

名称 类型 说明
Authorization String 持有者<令牌>。 必填。
Content-Type string application/json. 必需。

请求正文

参数 类型 说明
评论 字符串 要与操作关联的注释。
命令 Array 要运行的命令。 允许的值为 PutFile、RunScript、GetFile (必须按此顺序排列，对重复) 没有限制。

命令

命令类型 参数 说明
PutFile 项：FileName

值： <文件名>

 将库中的文件放入设备。 文件保存在工作文件夹中，并在设备重启时默认删除。 注意：没有响应结果。
RunScript 键：ScriptName
值： <库中的脚本>

键：Args
值： <脚本参数>

 在设备上从库运行脚本。

Args 参数将传递给脚本。

10 分钟后超时。
GetFile 键：路径
值： <文件路径>		 从设备收集文件。 注意：必须转义路径中的反斜杠。

响应

  • 如果成功，此方法返回 201 Created。

    操作实体。 如果未找到具有指定 ID 的计算机 - 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

Content-type：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"
                    }
                ]
            }
        }
    ]
}

提示

想要了解更多信息？ Engage技术社区中的 Microsoft 安全社区：Microsoft Defender for Endpoint技术社区。