You are viewing docs on Elastic's new documentation system, currently in technical preview. For all other Elastic docs, visit elastic.co/guide.

Endpoint response actions

Perform response actions on endpoints using a terminal-like interface.

The response console allows you to perform response actions on an endpoint using a terminal-like interface. You can enter action commands and get near-instant feedback on them. Actions are also recorded in the endpoint's response actions history for reference.

Response actions are supported on all endpoint platforms (Linux, macOS, and Windows).

Requirements

  • Response actions and the response console UI require the Endpoint Protection Complete project feature.

  • Endpoints must have Elastic Agent version 8.4 or higher installed with the Elastic Defend integration to receive response actions.

  • Some response actions require specific user roles, indicated below. These are required to perform actions both in the response console and in other areas of the Elastic Security app (such as isolating a host from a detection alert).

  • Users must have the appropriate user role privileges for at least one response action to access the response console.

Launch the response console from any of the following places in Elastic Security:

  • Endpoints page → Actions menu () → Respond
  • Endpoint details flyout → Take actionRespond
  • Alert details flyout → Take actionRespond
  • Host details page → Respond

To perform an action on the endpoint, enter a response action command in the input area at the bottom of the console, then press Return. Output from the action is displayed in the console.

If a host is unavailable, pending actions will execute once the host comes online. Pending actions expire after two weeks and can be tracked in the response actions history.

Note

Some response actions may take a few seconds to complete. Once you enter a command, you can immediately enter another command while the previous action is running.

Activity in the response console is persistent, so you can navigate away from the page and any pending actions you've submitted will continue to run. To confirm that an action completed, return to the response console to view the console output or check the response actions history.

Important

Once you submit a response action, you can't cancel it, even if the action is pending for an offline host.

Response action commands

The following response action commands are available in the response console.

isolate

Isolate the host, blocking communication with other hosts on the network.

Required role: Tier 3 analyst, SOC manager, or Endpoint operations analyst

Example: isolate --comment "Isolate host related to detection alerts"

release

Release an isolated host, allowing it to communicate with the network again.

Required role: Tier 3 analyst, SOC manager, or Endpoint operations analyst

Example: release --comment "Release host, everything looks OK"

status

Show information about the host's status, including: Elastic Agent status and version, the Elastic Defend integration's policy status, and when the host was last active.

processes

Show a list of all processes running on the host. This action may take a minute or so to complete.

Required role: Tier 3 analyst, SOC manager, or Endpoint operations analyst

Tip

Use this command to get current PID or entity ID values, which are required for other response actions such as kill-process and suspend-process.

Entity IDs may be more reliable than PIDs, because entity IDs are unique values on the host, while PID values can be reused by the operating system.

kill-process

Terminate a process. You must include one of the following parameters to identify the process to terminate:

  • --pid : A process ID (PID) representing the process to terminate.
  • --entityId : An entity ID representing the process to terminate.

Required role: Tier 3 analyst, SOC manager, or Endpoint operations analyst

Example: kill-process --pid 123 --comment "Terminate suspicious process"

suspend-process

Suspend a process. You must include one of the following parameters to identify the process to suspend:

  • --pid : A process ID (PID) representing the process to suspend.
  • --entityId : An entity ID representing the process to suspend.

Required role: Tier 3 analyst, SOC manager, or Endpoint operations analyst

Example: suspend-process --pid 123 --comment "Suspend suspicious process"

get-file

Retrieve a file from a host. Files are downloaded in a password-protected .zip archive to prevent the file from running. Use password elastic to open the .zip in a safe environment.

You must include the following parameter to specify the file's location on the host:

  • --path : The file's full path (including the file name).

Required role: Tier 3 analyst, SOC manager, or Endpoint operations analyst

Example: get-file --path "/full/path/to/file.txt" --comment "Possible malware"

Tip

You can use the Osquery manager integration to query a host's operating system and gain insight into its files and directories, then use get-file to retrieve specific files.

Note

When Elastic Defend prevents file activity due to malware prevention, the file is quarantined on the host and a malware prevention alert is created. To retrieve this file with get-file, copy the path from the alert's Quarantined file path field (file.Ext.quarantine_path), which appears under Highlighted fields in the alert details flyout. Then paste the value into the --path parameter.

execute

Run a shell command on the host. The command's output and any errors appear in the response console, up to 2000 characters. The complete output (stdout and stderr) are also saved to a downloadable .zip archive (password: elastic). Use these parameters:

  • --command : (Required) A shell command to run on the host. The command must be supported by bash for Linux and macOS hosts, and cmd.exe for Windows.

    Note

    • Multiple consecutive dashes in the value must be escaped; single dashes do not need to be escaped. For example, to represent a directory named /opt/directory--name, use the following: /opt/directory\-\-name.

    • You can use quotation marks without escaping. For example: execute --command "cd "C:\Program Files\directory""

  • --timeout : (Optional) How long the host should wait for the command to complete. Use h for hours, m for minutes, s for seconds (for example, 2s is two seconds). If no timeout is specified, it defaults to four hours.

Required role: SOC manager or Endpoint operations analyst

Example: execute --command "ls -al" --timeout 2s --comment "Get list of all files"

Warning

This response action runs commands on the host using the same user account running the Elastic Defend integration, which normally has full control over the system. Be careful with any commands that could cause irrevocable changes.

upload

Upload a file to the host. The file is saved to the location on the host where Elastic Endpoint is installed. After you run the command, the full path is returned in the console for reference. Use these parameters:

  • --file : (Required) The file to send to the host. As soon as you type this parameter, a popup appears — select it to navigate to the file, or drag and drop the file onto the popup.
  • --overwrite : (Optional) Overwrite the file on the host if it already exists.

Required role: Tier 3 analyst, SOC manager, or Endpoint operations analyst

Example: upload --file --comment "Upload remediation script"

Tip

You can follow this with the execute response action to upload and run scripts for mitigation or other purposes.

Note

The default file size maximum is 25 MB, configurable in kibana.yml with the maxUploadResponseActionFileBytes setting. You must enter the value in bytes (the maximum is 104857600 bytes, or 100 MB).

Supporting commands and parameters

--comment

Add to a command to include a comment explaining or describing the action. Comments are included in the response actions history.

--help

Add to a command to get help for that command.

Example: isolate --help

clear

Clear all output from the response console.

help

List supported commands in the console output area.

Tip

You can also get a list of commands in the Help panel, which stays on the screen independently of the output area.

Help panel

Click Help in the upper-right to open the Help panel, which lists available response action commands and parameters as a reference.

Note

This panel displays only the response actions that you have the user role privileges to perform.

You can use this panel to build commands with less typing. Click the add icon () to add a command to the input area, enter any additional parameters or a comment, then press Return to run the command.

If the endpoint is running an older version of Elastic Agent, some response actions may not be supported, as indicated by an informational icon and tooltip. Upgrade Elastic Agent on the endpoint to be able to use the latest response actions.

Response actions history

Click Response actions history to display a log of the response actions performed on the endpoint, such as isolating a host or terminating a process. You can filter the information displayed in this view. Refer to Response actions history for more details.

On this page