Executar comandos de resposta em direto num dispositivo

  • Artigo

Aplica-se a:

Importante

Algumas informações neste artigo estão relacionadas com um produto pré-lançado que pode ser substancialmente modificado antes de ser lançado comercialmente. A Microsoft não concede garantias, expressas ou implícitas, relativamente às informações aqui fornecidas.

Quer experimentar o Microsoft Defender para Ponto Final? Inscrever-se para uma avaliação gratuita.

Nota

Se for um cliente do Us Government, utilize os URIs listados no Microsoft Defender para Endpoint para clientes do Us Government.

Sugestão

Para um melhor desempenho, pode utilizar o servidor mais próximo da localização geográfica:

  • 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

Descrição da API

Executa uma sequência de comandos de resposta em direto num dispositivo

Limitações

  1. As limitações de taxa para esta API são de 10 chamadas por minuto (os pedidos adicionais são respondidos com HTTP 429).

  2. 25 sessões em execução simultâneas (os pedidos que excedem o limite de limitação recebem uma resposta "429 - Demasiados pedidos").

  3. Se o computador não estiver disponível, a sessão fica em fila de espera até três dias.

  4. Tempo limite do comando RunScript após 10 minutos.

  5. Os comandos de resposta em direto não podem ser em fila de colocação em fila e só podem ser executados um de cada vez.

  6. Se o computador que está a tentar executar esta chamada à API estiver num grupo de dispositivos RBAC que não tem um nível de remediação automatizado atribuído, terá de, pelo menos, ativar o Nível mínimo de Remediação para um determinado Grupo de Dispositivos.

    Nota

    A criação de grupos de dispositivos é suportada no Defender para Endpoint Plano 1 e Plano 2.

  7. Podem ser executados vários comandos de resposta em direto numa única chamada à API. No entanto, quando um comando de resposta em direto falha, todas as ações subsequentes não serão executadas.

  8. Não é possível executar várias sessões de resposta em direto no mesmo computador (se a ação de resposta em direto já estiver em execução, os pedidos subsequentes são respondidos com HTTP 400 – ActiveRequestAlreadyExists).

Nota

As ações de resposta em direto iniciadas a partir da página Dispositivo não estão disponíveis na API machineactions.

Requisitos Mínimos

Antes de poder iniciar uma sessão num dispositivo, certifique-se de que cumpre os seguintes requisitos:

Permissões

É necessária uma das seguintes permissões para chamar esta API. Para saber mais, incluindo como escolher permissões, consulte Introdução.

Tipo de permissão Permissão Nome a apresentar da permissão
Aplicação Machine.LiveResponse Executar resposta em direto num computador específico
Delegado (conta escolar ou profissional) Machine.LiveResponse Executar resposta em direto num computador específico

Pedido HTTP

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

Cabeçalhos de pedido

Name Tipo Descrição
Autorização Cadeia Token> de portador<. Obrigatório.
Tipo de Conteúdo cadeia application/json. Obrigatório.

Corpo do pedido

Parâmetro Tipo Descrição
Comentar Cadeia Comentário a associar à ação.
Comandos Matriz Comandos a executar. Os valores permitidos são PutFile, RunScript, GetFile (têm de estar nesta ordem sem limite de repetições).

Comandos

Tipo de Comando Parâmetros Descrição
PutFile Chave: FileName

Valor: <nome do ficheiro>

 Coloca um ficheiro da biblioteca no dispositivo. Os ficheiros são guardados numa pasta de trabalho e são eliminados quando o dispositivo é reiniciado por predefinição. NOTA: não tem um resultado de resposta.
RunScript Chave: ScriptName
Valor: <script da biblioteca>

Chave: Args
Valor: <argumentos de script>

 Executa um script a partir da biblioteca num dispositivo.

O parâmetro Args é transmitido para o script.

Tempos limite excedidos após 10 minutos.
GetFile Chave: Caminho
Valor: <caminho do ficheiro>		 Recolha o ficheiro de um dispositivo. NOTA: as barras invertidas no caminho têm de ser escapadas.

Resposta

  • Se for bem-sucedido, este método devolve 201 Criado.

    Entidade de ação. Se o computador com o ID especificado não tiver sido encontrado – 404 Não Encontrado.

Exemplos:

Exemplo de pedido

Eis um exemplo do pedido.

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

Exemplo de resposta

Eis um exemplo da resposta.

Os valores possíveis para cada estado de comando são "Criado", "Concluído" e "Com Falhas".

HTTP/1.1 200 Ok

Tipo de conteúdo: 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"
                    }
                ]
            }
        }
    ]
}

Sugestão

Quer saber mais? Engage com a comunidade de Segurança da Microsoft na nossa Comunidade Tecnológica: Microsoft Defender para Endpoint Tech Community.