Executar comandos de resposta ao vivo em um dispositivo

  • Artigo

Aplica-se a:

Importante

Algumas informações nesse artigo estão relacionadas ao produto pré-lançado que pode ser modificado de forma substancial antes de ser lançado comercialmente. A Microsoft não faz garantias, expressas ou implícitas, quanto às informações fornecidas aqui.

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

Observação

Se você for um cliente do governo dos EUA, use as URIs listadas em Microsoft Defender para Ponto de Extremidade para clientes do governo dos EUA.

Dica

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

  • api-us.securitycenter.microsoft.com
  • api-eu.securitycenter.microsoft.com
  • api-uk.securitycenter.microsoft.com
  • api-au.securitycenter.microsoft.com

Descrição da API

Executa uma sequência de comandos de resposta ao vivo em um dispositivo

Limitações

  1. As limitações de taxa para essa API são de 10 chamadas por minuto (solicitações adicionais são respondidas com HTTP 429).

  2. 25 sessões em execução simultâneas (solicitações que excedem o limite de limitação recebem uma resposta "429 – muitas solicitações").

  3. Se o computador não estiver disponível, a sessão será enfileirada por até três dias.

  4. Tempo limite de comando runScript após 10 minutos.

  5. Os comandos de resposta ao vivo não podem ser enfileirados e só podem ser executados um de cada vez.

  6. Se o computador que você está tentando executar essa chamada de API estiver em um grupo de dispositivos RBAC que não tenha um nível de correção automatizado atribuído a ele, você precisará pelo menos habilitar o nível mínimo de correção para um determinado Grupo de Dispositivos.

    Observação

    Há suporte para a criação do grupo de dispositivos no Plano 1 e no Plano 2 do Defender para Ponto de Extremidade.

  7. Vários comandos de resposta ao vivo podem ser executados em uma única chamada de API. No entanto, quando um comando de resposta ao vivo falhar, todas as ações subsequentes não serão executadas.

  8. Várias sessões de resposta ao vivo não podem ser executadas no mesmo computador (se a ação de resposta ao vivo já estiver em execução, as solicitações subsequentes serão respondidas com HTTP 400 - ActiveRequestAlreadyExists).

Observação

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

Requisitos mínimos

Antes de iniciar uma sessão em um dispositivo, verifique se você atende aos 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 da exibição de permissão
Application Machine.LiveResponse Executar resposta ao vivo em um computador específico
Delegado (conta corporativa ou de estudante) Machine.LiveResponse Executar resposta ao vivo em um 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 Comente para associar à ação.
Comandos Matriz Comandos a serem executados. Os valores permitidos são PutFile, RunScript, GetFile (devem estar nessa ordem sem limite de repetições).

Comandos

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

Valor: <nome do arquivo>

 Coloca um arquivo da biblioteca no dispositivo. Os arquivos são salvos em uma pasta de trabalho e são excluídos quando o dispositivo é reiniciado por padrão. OBSERVAÇÃO: não tem um resultado de resposta.
Runscript Chave: ScriptName
Valor: <Script da biblioteca>

Chave: Args
Valor: <argumentos de script>

 Executa um script da biblioteca em um dispositivo.

O parâmetro Args é passado para o script.

Tempo limite após 10 minutos.
GetFile Chave: Caminho
Valor: <Caminho do arquivo>		 Colete o arquivo de um dispositivo. OBSERVAÇÃO: os backslashes no caminho devem ser escapados.

Resposta

  • Se for bem-sucedido, esse método retornará 201 Criado.

    Entidade de ação. Se o computador com a ID especificada não foi encontrado – 404 Não encontrado.

Exemplo

Exemplo de solicitação

Aqui está um exemplo da solicitação.

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 comando status são "Created", "Completed" e "Failed".

HTTP/1.1 200 Ok

Tipo de conteúdo: aplicativo/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? Engage com a comunidade de Segurança da Microsoft em nossa Comunidade Tecnológica: Microsoft Defender para Ponto de Extremidade Tech Community.