From f6bd9d7117c6d7e2c6b262a7201af62d797ce79b Mon Sep 17 00:00:00 2001 From: Joe Peeples Date: Wed, 6 Mar 2024 16:48:42 -0500 Subject: [PATCH 1/6] Reorder & rename pages for flow Also matches newer organization scheme in serverless --- docs/management/admin/host-isolation-ov.asciidoc | 2 +- docs/management/manage-intro.asciidoc | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/management/admin/host-isolation-ov.asciidoc b/docs/management/admin/host-isolation-ov.asciidoc index d12fa08aaa..54d8475423 100644 --- a/docs/management/admin/host-isolation-ov.asciidoc +++ b/docs/management/admin/host-isolation-ov.asciidoc @@ -1,6 +1,6 @@ [[host-isolation-ov]] [chapter, role="xpack"] -= Host isolation += Isolate a host :frontmatter-description: Host isolation allows you to cut off a host's network access until you release it. :frontmatter-tags-products: [security, defend] diff --git a/docs/management/manage-intro.asciidoc b/docs/management/manage-intro.asciidoc index 724352fd44..2fdc1e080f 100644 --- a/docs/management/manage-intro.asciidoc +++ b/docs/management/manage-intro.asciidoc @@ -6,8 +6,8 @@ The following section provides an overview of the management tools admins can us include::{security-docs-root}/docs/management/admin/admin-pg-ov.asciidoc[leveloffset=+1] include::{security-docs-root}/docs/management/admin/response-actions.asciidoc[leveloffset=+2] -include::{security-docs-root}/docs/management/admin/response-actions-history.asciidoc[leveloffset=+2] include::{security-docs-root}/docs/management/admin/host-isolation-ov.asciidoc[leveloffset=+2] +include::{security-docs-root}/docs/management/admin/response-actions-history.asciidoc[leveloffset=+2] include::{security-docs-root}/docs/management/admin/response-actions-config.asciidoc[leveloffset=+2] include::{security-docs-root}/docs/management/admin/policy-list.asciidoc[leveloffset=+1] include::{security-docs-root}/docs/management/admin/trusted-apps.asciidoc[leveloffset=+1] From 13d7e8f52c300b48bbf84d9e5cb1f253ee0d7af1 Mon Sep 17 00:00:00 2001 From: Joe Peeples Date: Thu, 7 Mar 2024 12:02:55 -0500 Subject: [PATCH 2/6] More reordering and renaming for flow Also matches newer organization scheme in serverless --- docs/index.asciidoc | 2 ++ .../admin/response-actions.asciidoc | 22 ++++++++++++++++++- docs/management/manage-intro.asciidoc | 6 +---- 3 files changed, 24 insertions(+), 6 deletions(-) diff --git a/docs/index.asciidoc b/docs/index.asciidoc index 939a8ff35b..65cff813fa 100644 --- a/docs/index.asciidoc +++ b/docs/index.asciidoc @@ -36,6 +36,8 @@ include::cases/cases-index.asciidoc[] include::osquery/osquery-index.asciidoc[] +include::management/admin/response-actions.asciidoc[] + include::management/manage-intro.asciidoc[] include::siem-apis.asciidoc[] diff --git a/docs/management/admin/response-actions.asciidoc b/docs/management/admin/response-actions.asciidoc index c742577427..856a2fc96d 100644 --- a/docs/management/admin/response-actions.asciidoc +++ b/docs/management/admin/response-actions.asciidoc @@ -41,11 +41,13 @@ Activity in the response console is persistent, so you can navigate away from th IMPORTANT: Once you submit a response action, you can't cancel it, even if the action is pending for an offline host. +[discrete] [[response-action-commands]] == Response action commands The following response action commands are available in the response console. +[discrete] === `isolate` <>, blocking communication with other hosts on the network. @@ -53,6 +55,7 @@ Required privilege: *Host Isolation* Example: `isolate --comment "Isolate host related to detection alerts"` +[discrete] === `release` Release an isolated host, allowing it to communicate with the network again. @@ -60,9 +63,11 @@ Required privilege: *Host Isolation* Example: `release --comment "Release host, everything looks OK"` +[discrete] === `status` Show information about the host's status, including: {agent} status and version, the {elastic-defend} integration's policy status, and when the host was last active. +[discrete] === `processes` Show a list of all processes running on the host. This action may take a minute or so to complete. @@ -75,6 +80,7 @@ Use this command to get current PID or entity ID values, which are required for 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. ==== +[discrete] === `kill-process` Terminate a process. You must include one of the following parameters to identify the process to terminate: @@ -86,6 +92,7 @@ Required privilege: *Process Operations* Example: `kill-process --pid 123 --comment "Terminate suspicious process"` +[discrete] === `suspend-process` Suspend a process. You must include one of the following parameters to identify the process to suspend: @@ -97,6 +104,7 @@ Required privilege: *Process Operations* Example: `suspend-process --pid 123 --comment "Suspend suspicious process"` +[discrete] === `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. @@ -116,6 +124,7 @@ TIP: You can use the <> to query a host When {elastic-defend} prevents file activity due to <>, 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. ==== +[discrete] === `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: @@ -139,6 +148,7 @@ Example: `execute --command "ls -al" --timeout 2s --comment "Get list of all fil 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. +[discrete] === `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: @@ -154,29 +164,35 @@ TIP: You can follow this with the `execute` response action to upload and run sc 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). +[discrete] [[supporting-commands-parameters]] == Supporting commands and parameters +[discrete] === `--comment` Add to a command to include a comment explaining or describing the action. Comments are included in the response actions history. +[discrete] === `--help` Add to a command to get help for that command. Example: `isolate --help` +[discrete] === `clear` Clear all output from the response console. +[discrete] === `help` List supported commands in the console output area. TIP: You can also get a list of commands in the <>, which stays on the screen independently of the output area. +[discrete] [[help-panel]] == Help panel @@ -194,7 +210,7 @@ If the endpoint is running an older version of {agent}, some response actions ma [role="screenshot"] image::images/response-console-unsupported-command.png[Unsupported response action with tooltip,350] - +[discrete] [[actions-log]] == Response actions history @@ -202,3 +218,7 @@ Click *Response actions history* to display a log of the response actions perfor [role="screenshot"] image::images/response-actions-history-console.png[Response actions history with a few past actions,85%] + +include::host-isolation-ov.asciidoc[leveloffset=+1] +include::response-actions-history.asciidoc[leveloffset=+1] +include::response-actions-config.asciidoc[leveloffset=+1] diff --git a/docs/management/manage-intro.asciidoc b/docs/management/manage-intro.asciidoc index 2fdc1e080f..3b03526906 100644 --- a/docs/management/manage-intro.asciidoc +++ b/docs/management/manage-intro.asciidoc @@ -1,14 +1,10 @@ [[sec-manage-intro]] -= Endpoint management += Manage endpoint protection The following section provides an overview of the management tools admins can use to manage endpoints, integration policies, trusted applications, event filters, host isolation exceptions, and blocked applications. include::{security-docs-root}/docs/management/admin/admin-pg-ov.asciidoc[leveloffset=+1] -include::{security-docs-root}/docs/management/admin/response-actions.asciidoc[leveloffset=+2] -include::{security-docs-root}/docs/management/admin/host-isolation-ov.asciidoc[leveloffset=+2] -include::{security-docs-root}/docs/management/admin/response-actions-history.asciidoc[leveloffset=+2] -include::{security-docs-root}/docs/management/admin/response-actions-config.asciidoc[leveloffset=+2] include::{security-docs-root}/docs/management/admin/policy-list.asciidoc[leveloffset=+1] include::{security-docs-root}/docs/management/admin/trusted-apps.asciidoc[leveloffset=+1] include::{security-docs-root}/docs/management/admin/event-filters.asciidoc[leveloffset=+1] From aca13ae7724e1ec29995b34f513f0be2464eb65f Mon Sep 17 00:00:00 2001 From: Joe Peeples Date: Thu, 7 Mar 2024 15:30:40 -0500 Subject: [PATCH 3/6] First (mostly complete) draft Create new page, update related other pages --- .../admin/bidirectional-actions.asciidoc | 28 +++++++++++++++++++ .../admin/host-isolation-ov.asciidoc | 4 +-- .../admin/response-actions-config.asciidoc | 2 +- .../admin/response-actions-history.asciidoc | 11 ++++---- .../admin/response-actions.asciidoc | 2 ++ 5 files changed, 39 insertions(+), 8 deletions(-) create mode 100644 docs/management/admin/bidirectional-actions.asciidoc diff --git a/docs/management/admin/bidirectional-actions.asciidoc b/docs/management/admin/bidirectional-actions.asciidoc new file mode 100644 index 0000000000..5e76e1d472 --- /dev/null +++ b/docs/management/admin/bidirectional-actions.asciidoc @@ -0,0 +1,28 @@ +[[bidirectional-actions]] += Bidirectional response actions + +:frontmatter-description: Perform response actions on hosts protected by third-party endpoint security systems. +:frontmatter-tags-products: [security] +:frontmatter-tags-content-type: [reference] +:frontmatter-tags-user-goals: [manage] + +preview::[] + +[discrete] +[[sentinelone-response-actions]] +== SentinelOne response actions + +SentinelOne response actions allow you to direct SentinelOne to perform actions on protected hosts without needing to leave the {elastic-sec} UI. Prior <> is required to connect {elastic-sec} with SentinelOne. + +The following response actions and related features are supported for SentinelOne-protected hosts: + +* **Isolate and release a host** using any of these methods: ++ +-- +** From a detection alert +** From the response console +-- ++ +Refer to the instructions on <> and <> hosts for more details. + +* **View past response action activity** in the <> log. diff --git a/docs/management/admin/host-isolation-ov.asciidoc b/docs/management/admin/host-isolation-ov.asciidoc index 54d8475423..0141bea2fe 100644 --- a/docs/management/admin/host-isolation-ov.asciidoc +++ b/docs/management/admin/host-isolation-ov.asciidoc @@ -67,7 +67,7 @@ All actions executed on a host are tracked in the host’s response actions hist ==== NOTE: The response console is an https://www.elastic.co/pricing[Enterprise subscription] feature. -. Open the response console for the endpoint (*Manage* -> *Endpoints* -> *Actions* menu (*...*) -> *Respond*). +. Open the response console for the host (select the **Respond** button or actions menu option on the host, endpoint, or alert details view). . Enter the `isolate` command and an optional comment in the input area, for example: + `isolate --comment "Isolate this host"` @@ -124,7 +124,7 @@ image::images/host-isolated-notif.png[Host isolated notification message,350] ==== NOTE: The response console is an https://www.elastic.co/pricing[Enterprise subscription] feature. -. Open the response console for the endpoint (*Manage* -> *Endpoints* -> *Actions* menu (*...*) -> *Respond*). +. Open the response console for the host (select the **Respond** button or actions menu option on the host, endpoint, or alert details view). . Enter the `release` command and an optional comment in the input area, for example: + `release --comment "Release this host"` diff --git a/docs/management/admin/response-actions-config.asciidoc b/docs/management/admin/response-actions-config.asciidoc index 43744051fe..3b4f76f193 100644 --- a/docs/management/admin/response-actions-config.asciidoc +++ b/docs/management/admin/response-actions-config.asciidoc @@ -1,5 +1,5 @@ [[response-actions-config]] -= Response actions configuration += Configure bidirectional actions :frontmatter-description: Configure third-party systems to perform response actions on protected hosts. :frontmatter-tags-products: [security] diff --git a/docs/management/admin/response-actions-history.asciidoc b/docs/management/admin/response-actions-history.asciidoc index f6f8ca3e5f..85e618a2c6 100644 --- a/docs/management/admin/response-actions-history.asciidoc +++ b/docs/management/admin/response-actions-history.asciidoc @@ -6,7 +6,7 @@ :frontmatter-tags-content-type: [reference] :frontmatter-tags-user-goals: [manage] -{elastic-defend} keeps a log of the <> performed on endpoints, such as isolating a host or terminating a process. The log displays when each command was performed, the host on which the action was performed, the {kib} user who requested the action, any comments added to the action, and the action's current status. +{elastic-sec} keeps a log of the <> performed on endpoints, such as isolating a host or terminating a process. The log displays when each command was performed, the host on which the action was performed, the {kib} user who requested the action, any comments added to the action, and the action's current status. .Requirement [sidebar] @@ -27,9 +27,10 @@ image::images/response-actions-history-page.png[Response actions history page UI To filter and expand the information in the response actions history: * Enter a user name or comma-separated list of user names in the search field to display actions requested by those users. -* Use the *Hosts* menu to display actions performed on specific endpoints. (This menu is only available on the *Response actions history* page for all endpoints.) -* Use the *Actions* menu to display specific actions types. -* Use the *Statuses* menu to display actions with a specific status. -* Use the *Type* menu to display actions manually run by a user (`Triggered manually`) or automatically run by a rule (`Triggered by rule`). +* Use the various drop-down menus to filter the actions shown: +** *Hosts*: Show actions performed on specific endpoints. (Only available on the *Response actions history* page for all endpoints.) +** *Actions*: Show specific actions types. +** *Statuses*: Show actions with a specific status. +** *Type*: Show actions based on the endpoint protection agent type ({elastic-defend} or a third-party agent), and how the action was triggered (manually by a user or automatically by a detection rule). * Use the date and time picker to display actions within a specific time range. * Click the expand arrow on the right to display more details about an action. diff --git a/docs/management/admin/response-actions.asciidoc b/docs/management/admin/response-actions.asciidoc index 856a2fc96d..990b4b660b 100644 --- a/docs/management/admin/response-actions.asciidoc +++ b/docs/management/admin/response-actions.asciidoc @@ -30,6 +30,7 @@ Launch the response console from any of the following places in {elastic-sec}: * *Endpoints* page -> *Actions* menu (*...*) -> *Respond* * Endpoint details flyout -> *Take action* -> *Respond* * Alert details flyout -> *Take action* -> *Respond* +* Host details page → *Respond* To perform an action on the endpoint, enter a <> in the input area at the bottom of the console, then press *Return*. Output from the action is displayed in the console. @@ -221,4 +222,5 @@ image::images/response-actions-history-console.png[Response actions history with include::host-isolation-ov.asciidoc[leveloffset=+1] include::response-actions-history.asciidoc[leveloffset=+1] +include::bidirectional-actions.asciidoc[leveloffset=+1] include::response-actions-config.asciidoc[leveloffset=+1] From e40b36298011e0f7cb7f64670a02e910c62b8ffc Mon Sep 17 00:00:00 2001 From: Joe Peeples Date: Fri, 15 Mar 2024 12:28:28 -0400 Subject: [PATCH 4/6] Apply suggestions from review Co-authored-by: Ash <1849116+ashokaditya@users.noreply.github.com> --- docs/management/admin/bidirectional-actions.asciidoc | 2 +- docs/management/admin/response-actions-history.asciidoc | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/management/admin/bidirectional-actions.asciidoc b/docs/management/admin/bidirectional-actions.asciidoc index 5e76e1d472..0b881a309d 100644 --- a/docs/management/admin/bidirectional-actions.asciidoc +++ b/docs/management/admin/bidirectional-actions.asciidoc @@ -12,7 +12,7 @@ preview::[] [[sentinelone-response-actions]] == SentinelOne response actions -SentinelOne response actions allow you to direct SentinelOne to perform actions on protected hosts without needing to leave the {elastic-sec} UI. Prior <> is required to connect {elastic-sec} with SentinelOne. +You can direct SentinelOne to perform response actions on protected hosts without leaving the {elastic-sec} UI. Prior <> is required to connect {elastic-sec} with SentinelOne. The following response actions and related features are supported for SentinelOne-protected hosts: diff --git a/docs/management/admin/response-actions-history.asciidoc b/docs/management/admin/response-actions-history.asciidoc index 85e618a2c6..cd71633a28 100644 --- a/docs/management/admin/response-actions-history.asciidoc +++ b/docs/management/admin/response-actions-history.asciidoc @@ -31,6 +31,6 @@ To filter and expand the information in the response actions history: ** *Hosts*: Show actions performed on specific endpoints. (Only available on the *Response actions history* page for all endpoints.) ** *Actions*: Show specific actions types. ** *Statuses*: Show actions with a specific status. -** *Type*: Show actions based on the endpoint protection agent type ({elastic-defend} or a third-party agent), and how the action was triggered (manually by a user or automatically by a detection rule). +** *Types*: Show actions based on the endpoint protection agent type ({elastic-defend} or a third-party agent), and how the action was triggered (manually by a user or automatically by a detection rule). * Use the date and time picker to display actions within a specific time range. * Click the expand arrow on the right to display more details about an action. From 46910bb6e26516d32610401e96023f710a5ccb20 Mon Sep 17 00:00:00 2001 From: Joe Peeples Date: Fri, 15 Mar 2024 12:36:59 -0400 Subject: [PATCH 5/6] Use "third-party" vs. "bidirectional" --- docs/management/admin/response-actions-config.asciidoc | 4 ++-- docs/management/admin/response-actions.asciidoc | 2 +- ...ectional-actions.asciidoc => third-party-actions.asciidoc} | 4 ++-- 3 files changed, 5 insertions(+), 5 deletions(-) rename docs/management/admin/{bidirectional-actions.asciidoc => third-party-actions.asciidoc} (94%) diff --git a/docs/management/admin/response-actions-config.asciidoc b/docs/management/admin/response-actions-config.asciidoc index 3b4f76f193..735f6c81b3 100644 --- a/docs/management/admin/response-actions-config.asciidoc +++ b/docs/management/admin/response-actions-config.asciidoc @@ -1,5 +1,5 @@ [[response-actions-config]] -= Configure bidirectional actions += Configure third-party response actions :frontmatter-description: Configure third-party systems to perform response actions on protected hosts. :frontmatter-tags-products: [security] @@ -12,7 +12,7 @@ Endpoint response actions involving third-party systems require additional confi [[configure-sentinelone-response-actions]] == Configure SentinelOne response actions -SentinelOne response actions allow you to perform bidirectional actions on protected hosts, such as directing SentinelOne to isolate a suspicious endpoint from your network, without needing to leave the {elastic-sec} UI. +You can direct SentinelOne to perform response actions on protected hosts, such as isolating a suspicious endpoint from your network, without needing to leave the {elastic-sec} UI. preview::[] diff --git a/docs/management/admin/response-actions.asciidoc b/docs/management/admin/response-actions.asciidoc index 990b4b660b..01f6b11591 100644 --- a/docs/management/admin/response-actions.asciidoc +++ b/docs/management/admin/response-actions.asciidoc @@ -222,5 +222,5 @@ image::images/response-actions-history-console.png[Response actions history with include::host-isolation-ov.asciidoc[leveloffset=+1] include::response-actions-history.asciidoc[leveloffset=+1] -include::bidirectional-actions.asciidoc[leveloffset=+1] +include::third-party-actions.asciidoc[leveloffset=+1] include::response-actions-config.asciidoc[leveloffset=+1] diff --git a/docs/management/admin/bidirectional-actions.asciidoc b/docs/management/admin/third-party-actions.asciidoc similarity index 94% rename from docs/management/admin/bidirectional-actions.asciidoc rename to docs/management/admin/third-party-actions.asciidoc index 0b881a309d..cb50f31128 100644 --- a/docs/management/admin/bidirectional-actions.asciidoc +++ b/docs/management/admin/third-party-actions.asciidoc @@ -1,5 +1,5 @@ -[[bidirectional-actions]] -= Bidirectional response actions +[[third-party-actions]] += Third-party response actions :frontmatter-description: Perform response actions on hosts protected by third-party endpoint security systems. :frontmatter-tags-products: [security] From d4d12b6617f232e552f0b1ba1ebe1603b1efb873 Mon Sep 17 00:00:00 2001 From: Joe Peeples Date: Mon, 18 Mar 2024 16:44:21 -0400 Subject: [PATCH 6/6] Follow-up resolve merge conflict Add new page (automated-response-actions) to the TOC --- docs/management/admin/response-actions.asciidoc | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/management/admin/response-actions.asciidoc b/docs/management/admin/response-actions.asciidoc index 01f6b11591..8da977cd3d 100644 --- a/docs/management/admin/response-actions.asciidoc +++ b/docs/management/admin/response-actions.asciidoc @@ -220,6 +220,7 @@ Click *Response actions history* to display a log of the response actions perfor [role="screenshot"] image::images/response-actions-history-console.png[Response actions history with a few past actions,85%] +include::automated-response-actions.asciidoc[leveloffset=+1] include::host-isolation-ov.asciidoc[leveloffset=+1] include::response-actions-history.asciidoc[leveloffset=+1] include::third-party-actions.asciidoc[leveloffset=+1]