在裝置上執行即時回應命令

  • 發行項

適用於：

重要事項

本文中的部分資訊與發行前版本產品有關，在產品正式發行前可能會大幅度修改。 Microsoft 對此處提供的資訊，不提供任何明確或隱含的瑕疵擔保。

想要體驗適用於端點的 Microsoft Defender 嗎？ 注册免費試用版。

注意事項

如果您是美國政府客戶，請使用美國政府客戶 適用於端點的 Microsoft Defender 中所列的 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方案1和方案2支援裝置群組建立。

  7. 您可以在單一 API 呼叫上執行多個即時回應命令。 不過，當即時回應命令失敗時，將不會執行所有後續動作。

  8. 如果即時回應動作已在執行中，則無法在同一部計算機上執行多個實時回應會話 (後續要求會使用 HTTP 400 - ActiveRequestAlreadyExists) 來回應。

注意事項

計算機 API 中無法使用從 [裝置] 頁面起始的即時回應動作。

最低需求

在裝置上起始會話之前，請確定您符合下列需求：

權限

呼叫此 API 需要下列其中一個許可權。 若要深入瞭解，包括如何選擇許可權，請參閱 開始使用。

許可權類型 權限 許可權顯示名稱
應用程式 Machine.LiveResponse 在特定電腦上執行實時回應
委派 (公司或學校帳戶) Machine.LiveResponse 在特定電腦上執行實時回應

HTTP 要求

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

要求標頭

名稱 類型 描述
授權 字串 <持有人令牌>。 此為必要動作。
Content-Type 字串 application/json。 此為必要動作。

要求內文

參數 Type 描述
留言 字串 要與動作相關聯的批注。
命令 陣列 要執行的命令。 允許的值為 PutFile、RunScript、GetFile (必須依此順序排列，且重複) 沒有限制。

命令

命令類型 參數 描述
PutFile 機碼：FileName

值： <檔名>

 將檔案從連結庫放入裝置。 檔案會儲存在工作資料夾中，而且預設會在裝置重新啟動時刪除。 注意：沒有響應結果。
RunScript 機碼：ScriptName
值： <來自連結庫的腳本>

索引鍵：自變數
值： <腳本自變數>

 從裝置上的連結庫執行腳本。

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

回應範例

以下是回應的範例。

每個命令狀態的可能值為 「Created」、“Completed” 和 “Failed”。

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

提示

想要深入了解? Engage 技術社群中的 Microsoft 安全性社群：適用於端點的 Microsoft Defender 技術社群。