POST /api/endpoint/action/runscript
Api key auth Basic 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.

    At least 1 element. Minimum length of each is 1.

  • case_ids array[string]

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

    At least 1 element. Minimum length of each is 1.

  • comment string

    Optional comment

  • endpoint_ids array[string] Required

    List of endpoint IDs (cannot contain empty strings)

    At least 1 element. Minimum length of each is 1.

  • parameters object Required

    One of the following set of parameters must be provided

    One of:
    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

    Optional parameters object

Responses

  • 200 application/json

    Action request was successfully created

    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://localhost:5601/api/endpoint/action/runscript' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --data '{"agent_type":"microsoft_defender_endpoint","parameters":{"args":"-param1 value1 -param2 value2","scriptName":"my-script.ps1"},"endpoint_ids":["ed518850-681a-4d60-bb98-e22640cae2a8"]}'
Request examples
Microsoft Defender Endpoint runscript 
{
  "agent_type": "microsoft_defender_endpoint",
  "parameters": {
    "args": "-param1 value1 -param2 value2",
    "scriptName": "my-script.ps1"
  },
  "endpoint_ids": [
    "ed518850-681a-4d60-bb98-e22640cae2a8"
  ]
}
SentinelOne runscript 
{
  "agent_type": "sentinel_one",
  "parameters": {
    "scriptId": "1111-2222-3333-4444-5555-6666-7777-8888",
    "scriptInput": "--delete --paths-to-delete /tmp/temp_file.txt,/tmp/random_file.txt"
  },
  "endpoint_ids": [
    "ed518850-681a-4d60-bb98-e22640cae2a8"
  ]
}