Executar comandos de resposta ao vivo em um dispositivo
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 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:
- 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 ao vivo em um dispositivo
Limitações
As limitações de taxa para essa API são de 10 chamadas por minuto (solicitações adicionais são respondidas com HTTP 429).
25 sessões em execução simultâneas (solicitações que excedem o limite de limitação recebem uma resposta "429 – muitas solicitações").
Se o computador não estiver disponível, a sessão será enfileirada por até três dias.
Tempo limite de comando runScript após 10 minutos.
Os comandos de resposta ao vivo não podem ser enfileirados e só podem ser executados um de cada vez.
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.
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.
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:
Verifique se você está executando uma versão do Windows, macOS ou Linux com suporte.
Os dispositivos devem estar executando um dos seguintes:
Windows 11
Windows 10
- Versão 1909 ou posterior
- Versão 1903 com KB4515384
- Versão 1809 (RS 5) com KB4537818
- Versão 1803 (RS 4) com KB4537795
- Versão 1709 (RS 3) com KB4537816
Windows Server 2019 – Aplicável somente à visualização pública
Windows Server 2022
macOS(requer perfis de configuração adicionais)
- 13 (Ventura)
- 12 (Monterey)
- 11 (Big Sur)
Linux
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 |
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"
}
]
}
}
]
}
Tópicos relacionados
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.
Comentários
https://aka.ms/ContentUserFeedback.
Em breve: Ao longo de 2024, eliminaremos os problemas do GitHub como o mecanismo de comentários para conteúdo e o substituiremos por um novo sistema de comentários. Para obter mais informações, consulteEnviar e exibir comentários de