Compartilhar via

Executar comandos de resposta em direto num dispositivo

  • Artigo

Aplica-se a:

Importante

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

Deseja experimentar o Microsoft Defender para Ponto de Extremidade? Inscreva-se para uma avaliação gratuita.

Observação

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

Dica

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
  • ina.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.

    Observação

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

Observação

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

Uma das seguintes permissões é necessária 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
Application Machine.LiveResponse Executar resposta em direto num computador específico
Delegado (conta corporativa ou de estudante) Machine.LiveResponse Executar resposta em direto num computador específico

Solicitação HTTP

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

Cabeçalhos de solicitação

Nome Tipo Descrição
Autorização Cadeia de caracteres Token> de portador<. Obrigatório.
Content-Type string application/json. Obrigatório.

Corpo da solicitação

Parâmetro Tipo Descrição
Comentário String 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.

Exemplo

Exemplo de solicitação

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

Veja um exemplo de 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"
                    }
                ]
            }
        }
    ]
}

Dica

Você deseja aprender mais? Contacte a comunidade de Segurança da Microsoft na nossa Comunidade Tecnológica: Microsoft Defender para Endpoint Tech Community.