Ejecución de comandos de respuesta en directo en un dispositivo

  • Artículo

Se aplica a:

Importante

Parte de la información contenida en este artículo se refiere a un producto preliminar que puede sufrir modificaciones sustanciales antes de su lanzamiento comercial. Microsoft no otorga garantías, expresas o implícitas, con respecto a la información que aquí se proporciona.

¿Quiere experimentar Microsoft Defender para punto de conexión? Regístrese para obtener una prueba gratuita.

Nota:

Si es cliente del Gobierno de EE. UU., use los URI que aparecen en Microsoft Defender para punto de conexión para los clientes del Gobierno de EE. UU.

Sugerencia

Para mejorar el rendimiento, puede usar el servidor más cercano a la ubicación 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

Descripción de la API

Ejecuta una secuencia de comandos de respuesta dinámica en un dispositivo.

Limitaciones

  1. Las limitaciones de velocidad de esta API son de 10 llamadas por minuto (las solicitudes adicionales se responden con HTTP 429).

  2. 25 sesiones en ejecución simultánea (las solicitudes que superan el límite de limitación reciben una respuesta "429 - Demasiadas solicitudes").

  3. Si la máquina no está disponible, la sesión se pone en cola hasta tres días.

  4. Tiempos de espera del comando RunScript después de 10 minutos.

  5. Los comandos de respuesta dinámica no se pueden poner en cola y solo se pueden ejecutar de uno en uno.

  6. Si la máquina que intenta ejecutar esta llamada API está en un grupo de dispositivos RBAC que no tiene asignado un nivel de corrección automatizado, debe habilitar al menos el nivel de corrección mínimo para un grupo de dispositivos determinado.

    Nota:

    La creación de grupos de dispositivos se admite en El plan 1 y el plan 2 de Defender para punto de conexión.

  7. Se pueden ejecutar varios comandos de respuesta dinámica en una sola llamada API. Sin embargo, cuando se produce un error en un comando de respuesta dinámica, no se ejecutarán todas las acciones posteriores.

  8. No se pueden ejecutar varias sesiones de respuesta dinámica en el mismo equipo (si la acción de respuesta activa ya se está ejecutando, las solicitudes posteriores se responden con HTTP 400 - ActiveRequestAlreadyExists).

Nota:

Las acciones de respuesta dinámica iniciadas desde la página Dispositivo no están disponibles en la API machineactions.

Requisitos mínimos

Antes de iniciar una sesión en un dispositivo, asegúrese de cumplir los siguientes requisitos:

Permisos

Se requiere uno de los siguientes permisos para llamar a esta API. Para más información, incluido cómo elegir permisos, consulte Introducción.

Tipo de permiso Permiso Nombre para mostrar del permiso
Aplicación Machine.LiveResponse Ejecución de una respuesta en directo en una máquina específica
Delegado (cuenta profesional o educativa) Machine.LiveResponse Ejecución de una respuesta en directo en una máquina específica

Solicitud HTTP

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

Encabezados de solicitud

Nombre Tipo Descripción
Authorization Cadena Token de portador<>. Obligatorio.
Content-Type string application/json. Obligatorio.

Cuerpo de la solicitud

Parámetro Tipo Descripción
Comentario Cadena Comentario que se va a asociar a la acción.
Comandos Matriz Comandos que se van a ejecutar. Los valores permitidos son PutFile, RunScript y GetFile (deben estar en este orden sin límite de repeticiones).

Comandos

Tipo de comando Parámetros Description
PutFile Clave: FileName

Valor: <nombre de archivo>

 Coloca un archivo de la biblioteca en el dispositivo. Los archivos se guardan en una carpeta de trabajo y se eliminan cuando el dispositivo se reinicia de forma predeterminada. NOTA: No tiene un resultado de respuesta.
Runscript Clave: ScriptName
Valor: <Script de la biblioteca>

Clave: Args
Valor: <Argumentos de script>

 Ejecuta un script desde la biblioteca en un dispositivo.

El parámetro Args se pasa al script.

Tiempos de espera después de 10 minutos.
GetFile Clave: Ruta de acceso
Valor: <Ruta de acceso del archivo>		 Recopilar archivo de un dispositivo. NOTA: Las barras diagonales inversas en la ruta de acceso deben tener escape.

Respuesta

  • Si se ejecuta correctamente, este método devuelve 201 Created.

    Entidad Action. Si no se encontró la máquina con el identificador especificado: 404 No encontrado.

Ejemplo

Ejemplo de solicitud

Este es un ejemplo de la solicitud.

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

Ejemplo de respuesta

Este es un ejemplo de la respuesta:

Los valores posibles para cada estado de comando son "Created", "Completed" y "Failed".

HTTP/1.1 200 Ok

Tipo de contenido: 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"
                    }
                ]
            }
        }
    ]
}

Sugerencia

¿Desea obtener más información? Engage con la comunidad de seguridad de Microsoft en nuestra comunidad tecnológica: Microsoft Defender para punto de conexión Tech Community.