POST /api/endpoint/action/runscript
Api key auth

Spaces method and path for this operation:

post /s/{space_id}/api/endpoint/action/runscript

Refer to Spaces for more information.

Run a script on a host. Currently supported only for some agent types.

application/json

Body Required

  • agent_type string

    List of agent types to retrieve. Defaults to endpoint.

    Values are endpoint, sentinel_one, crowdstrike, or microsoft_defender_endpoint.

  • alert_ids array[string]

    If this action is associated with any alerts, they can be specified here. The action will be logged in any cases associated with the specified alerts. Max of 50.

    At least 1 but not more than 50 elements. Minimum length of each is 1.

  • case_ids array[string]

    The IDs of cases where the action taken will be logged. Max of 50.

    At least 1 but not more than 50 elements. Minimum length of each is 1.

  • comment string

    Optional comment

  • endpoint_ids array[string] Required

    List of endpoint IDs (cannot contain empty strings). Max of 250.

    At least 1 but not more than 250 elements. Minimum length of each is 1.

  • parameters object Required

    One of the following set of parameters must be provided for the agentType that is specified.

    One of:
    Elastic Defend Run Script Parameters object Security_Endpoint_Management_API_RawScriptParameters object Security_Endpoint_Management_API_HostPathScriptParameters object Security_Endpoint_Management_API_CloudFileScriptParameters object SentinelOne Run Script Parameters object Microsoft Defender Endpoint Run Script Parameters object
  • parameters object

    Parameters object

Responses

  • 200 application/json

    Indicates a successful call.

    Hide response attribute Show response attribute object
    • data object
      Hide data attributes Show data attributes object
      • agents array[string(uuid)]

        The agent IDs for the hosts that the response action was sent to

      • agentState object

        The state of the response action for each agent ID that it was sent to

        Hide agentState attribute Show agentState attribute object
        • * object(uuid) Additional properties
          Hide * attributes Show * attributes object(uuid)
          • completedAt string

            The date and time the response action was completed for the agent ID

          • isCompleted boolean

            Whether the response action is completed for the agent ID

          • wasSuccessful boolean

            Whether the response action was successful for the agent ID

      • agentType string

        List of agent types to retrieve. Defaults to endpoint.

        Values are endpoint, sentinel_one, crowdstrike, or microsoft_defender_endpoint.

      • command string Required

        The command for the response action

        Minimum length is 1. Values are isolate, unisolate, kill-process, suspend-process, running-processes, get-file, execute, upload, scan, runscript, cancel, or memory-dump.

      • completedAt string(date-time)

        The response action completion time

      • createdBy string

        The user who created the response action

      • hosts object

        An object containing the host names associated with the agent IDs the response action was sent to

        Hide hosts attribute Show hosts attribute object
        • * object(uuid) Additional properties
          Hide * attribute Show * attribute object(uuid)
          • name string

            The host name

      • id string(uuid)

        The response action ID

      • isComplete boolean

        Whether the response action is complete

      • isExpired boolean

        Whether the response action is expired

      • outputs object

        The outputs of the response action for each agent ID that it was sent to. Content different depending on the response action command and will only be present for agents that have responded to the response action

        Hide outputs attribute Show outputs attribute object
        • * object(uuid) Additional properties

          The agent id

          Hide * attributes Show * attributes object(uuid)

          • content object | string Required

            The response action output content for the agent ID. Exact format depends on the response action command.

            One of:
            object-1 object string-2 string
          • type string Required

            Values are json or text.

      • parameters object

        The parameters of the response action. Content different depending on the response action command

      • startedAt string(date-time)

        The response action start time

      • status string

        The response action status

      • wasSuccessful boolean

        Whether the response action was successful
POST /api/endpoint/action/runscript 
curl \
 --request POST 'https://<KIBANA_URL>/api/endpoint/action/runscript' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --data '{"agent_type":"endpoint","endpoint_ids":["ed518850-681a-4d60-bb98-e22640cae2a8"],"parameters":{"scriptId":"1111-2222-3333-4444-5555-6666-7777-8888","scriptInput":"--path= /usr/log/exec.log"}}'
Request examples
Endpoint runscript to collect logs 
{
  "agent_type": "endpoint",
  "endpoint_ids": [
    "ed518850-681a-4d60-bb98-e22640cae2a8"
  ],
  "parameters": {
    "scriptId": "1111-2222-3333-4444-5555-6666-7777-8888",
    "scriptInput": "--path= /usr/log/exec.log"
  }
}
Microsoft Defender Endpoint runscript 
{
  "agent_type": "microsoft_defender_endpoint",
  "endpoint_ids": [
    "ed518850-681a-4d60-bb98-e22640cae2a8"
  ],
  "parameters": {
    "args": "-param1 value1 -param2 value2",
    "scriptName": "my-script.ps1"
  }
}
SentinelOne runscript 
{
  "agent_type": "sentinel_one",
  "endpoint_ids": [
    "ed518850-681a-4d60-bb98-e22640cae2a8"
  ],
  "parameters": {
    "scriptId": "1111-2222-3333-4444-5555-6666-7777-8888",
    "scriptInput": "--delete --paths-to-delete /tmp/temp_file.txt,/tmp/random_file.txt"
  }
}
Response examples (200) 
{
  "data": {
    "agents": [
      "ed518850-681a-4d60-bb98-e22640cae2a8"
    ],
    "agentState": {
      "ed518850-681a-4d60-bb98-e22640cae2a8": {
        "isCompleted": false,
        "wasSuccessful": false
      }
    },
    "agentType": "sentinel_one",
    "command": "runscript",
    "createdBy": "elastic",
    "hosts": {
      "ed518850-681a-4d60-bb98-e22640cae2a8": {
        "name": "gke-node-1235412"
      }
    },
    "id": "233db9ea-6733-4849-9226-5a7039c7161d",
    "isCompleted": false,
    "isExpired": false,
    "outputs": {},
    "parameters": {
      "scriptId": "1111-2222-3333-4444-5555-6666-7777-8888"
    },
    "startedAt": "2022-07-29T19:08:49.126Z",
    "status": "pending",
    "wasSuccessful": false
  }
}