Executar comandos de resposta em direto num dispositivo
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
- ina.api.security.microsoft.com
Descrição da API
Executa uma sequência de comandos de resposta em direto num dispositivo
Limitações
As limitações de taxa para esta API são de 10 chamadas por minuto (os pedidos adicionais são respondidos com HTTP 429).
25 sessões em execução simultâneas (os pedidos que excedem o limite de limitação recebem uma resposta "429 - Demasiados pedidos").
Se o computador não estiver disponível, a sessão fica em fila de espera até três dias.
Tempo limite do comando RunScript após 10 minutos.
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.
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.
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.
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:
Verifique se está a executar uma versão suportada do Windows, macOS ou Linux.
Os dispositivos têm de estar a executar um dos seguintes procedimentos:
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 - Apenas aplicável para Pré-visualização pública
Windows Server 2022
macOS(requer perfis de configuração adicionais)
- 13 (Ventura)
- 12 (Monterey)
- 11 (Big Sur)
Linux
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<. Necessário. |
Tipo de Conteúdo | cadeia | application/json. Necessá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 |
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"
}
]
}
}
]
}
Tópicos relacionados
Sugestão
Quer saber mais? Contacte a comunidade de Segurança da Microsoft na nossa Comunidade Tecnológica: Microsoft Defender para Endpoint Tech Community.