From 0021ab2046a784215b7d02d4e4d43dbbd9a85ab0 Mon Sep 17 00:00:00 2001 From: natasha-moore-elastic <137783811+natasha-moore-elastic@users.noreply.github.com> Date: Tue, 17 Dec 2024 10:15:18 +0000 Subject: [PATCH 1/2] Document ways to provide multiple Agent uninstall tokens (#6300) * Document ways to provide multiple Agent uninstall tokens * Apply suggestions from code review Co-authored-by: Benjamin Ironside Goldstein <91905639+benironside@users.noreply.github.com> --------- Co-authored-by: Benjamin Ironside Goldstein <91905639+benironside@users.noreply.github.com> (cherry picked from commit 87e3acb91306572e4077e375c6b0f45108ea2dd6) # Conflicts: # docs/serverless/edr-install-config/agent-tamper-protection.asciidoc # docs/serverless/edr-install-config/uninstall-agent.asciidoc --- .../agent-tamper-protection.asciidoc | 2 + docs/getting-started/uninstall-agent.asciidoc | 31 +++- .../agent-tamper-protection.asciidoc | 54 +++++++ .../uninstall-agent.asciidoc | 143 ++++++++++++++++++ 4 files changed, 229 insertions(+), 1 deletion(-) create mode 100644 docs/serverless/edr-install-config/agent-tamper-protection.asciidoc create mode 100644 docs/serverless/edr-install-config/uninstall-agent.asciidoc diff --git a/docs/getting-started/agent-tamper-protection.asciidoc b/docs/getting-started/agent-tamper-protection.asciidoc index 5728169a87..423c5c4cae 100644 --- a/docs/getting-started/agent-tamper-protection.asciidoc +++ b/docs/getting-started/agent-tamper-protection.asciidoc @@ -48,3 +48,5 @@ If you need the uninstall token to remove {agent} from an endpoint, you can find ** Click the *Show token* icon in the *Token* column to reveal a specific token. ** Click the *View uninstall command* icon in the *Actions* column to open the *Uninstall agent* flyout, containing the full uninstall command with the token. + +TIP: If you have many tamper-protected {agent} policies, you may want to <> in a single command. \ No newline at end of file diff --git a/docs/getting-started/uninstall-agent.asciidoc b/docs/getting-started/uninstall-agent.asciidoc index 25f940d8e2..1b00a45d00 100644 --- a/docs/getting-started/uninstall-agent.asciidoc +++ b/docs/getting-started/uninstall-agent.asciidoc @@ -5,7 +5,6 @@ To uninstall {agent} from a host, run the `uninstall` command from the directory If <> is enabled on the Agent policy for the host, you'll need to include the uninstall token in the command, using the `--uninstall-token` flag. You can <> on the Agent policy. Alternatively, find *{fleet}* in the navigation menu or by using the {kibana-ref}/introduction.html#kibana-navigation-search[global search field], and select *Uninstall tokens*. - For example, to uninstall {agent} on a macOS or Linux host: [source,shell] @@ -13,6 +12,36 @@ For example, to uninstall {agent} on a macOS or Linux host: sudo elastic-agent uninstall --uninstall-token 12345678901234567890123456789012 ---------------------------------- +[discrete] +[[multiple-uninstall-tokens]] +== Provide multiple uninstall tokens + +If you have multiple tamper-protected {agent} policies, you may want to provide multiple uninstall tokens in a single command. There are two ways to do this: + +* The `--uninstall-token` command can receive multiple uninstall tokens separated by a comma, without spaces. ++ +[source,shell] +---------------------------------- +sudo elastic-agent uninstall -f --uninstall-token 7b3d364db8e0deb1cda696ae85e42644,a7336b71e243e7c92d9504b04a774266 +---------------------------------- + +* `--uninstall-token`'s argument can also be a path to a text file with one uninstall token per line. ++ +NOTE: You must use the full file path, otherwise the file may not be found. ++ +[source,shell] +---------------------------------- +sudo elastic-agent uninstall -f --uninstall-token /tmp/tokens.txt +---------------------------------- ++ +In this example, `tokens.txt` would contain: ++ +[source,txt] +---------------------------------- +7b3d364db8e0deb1cda696ae85e42644 +a7336b71e243e7c92d9504b04a774266 +---------------------------------- + [discrete] [[uninstall-endpoint]] == Uninstall {elastic-endpoint} diff --git a/docs/serverless/edr-install-config/agent-tamper-protection.asciidoc b/docs/serverless/edr-install-config/agent-tamper-protection.asciidoc new file mode 100644 index 0000000000..07031a4696 --- /dev/null +++ b/docs/serverless/edr-install-config/agent-tamper-protection.asciidoc @@ -0,0 +1,54 @@ +[[security-agent-tamper-protection]] += Prevent {agent} uninstallation + +// :description: Block unauthorized attempts to uninstall {agent} on hosts. +// :keywords: serverless, security, how-to + + +For hosts enrolled in {elastic-defend}, you can prevent unauthorized attempts to uninstall {agent} and {elastic-endpoint} by enabling **Agent tamper protection** on the Agent policy. This offers an additional layer of security by preventing users from bypassing or disabling {elastic-defend}'s endpoint protections. + +When enabled, {agent} and {elastic-endpoint} can only be uninstalled on the host by including an uninstall token in the uninstall CLI command. One unique uninstall token is generated per Agent policy, and you can retrieve uninstall tokens in an Agent policy's settings or in the {fleet} UI. + +.Requirements +[NOTE] +==== +* Agent tamper protection requires the Endpoint Protection Complete <>. +* Hosts must be enrolled in the {elastic-defend} integration. +* {agent}s must be version 8.11.0 or later. +* This feature is supported for all operating systems. +==== + +[role="screenshot"] +image::images/agent-tamper-protection/agent-tamper-protection.png[Agent tamper protection setting highlighted on Agent policy settings page] + +[discrete] +[[enable-agent-tamper-protection]] +== Enable Agent tamper protection + +You can enable Agent tamper protection by configuring the {agent} policy. + +. Go to **{fleet}** -> **Agent policies**, then select the Agent policy you want to configure. +. Select the **Settings** tab on the policy details page. +. In the **Agent tamper protection** section, turn on the **Prevent agent tampering** setting. ++ +This makes the **Get uninstall command** link available, which you can follow to get the uninstall token and CLI command if you need to <> on this policy. ++ +[TIP] +==== +You can also access an Agent policy's uninstall tokens on the **Uninstall tokens** tab on the **{fleet}** page. Refer to <> for more information. +==== +. Select **Save changes**. + +[discrete] +[[fleet-uninstall-tokens]] +== Access uninstall tokens + +If you need the uninstall token to remove {agent} from an endpoint, you can find it in several ways: + +* **On the Agent policy** — Go to the Agent policy's **Settings** tab, then click the **Get uninstall command** link. The **Uninstall agent** flyout opens, containing the full uninstall command with the token. +* **On the {fleet} page** — Go to **{fleet}** -> **Uninstall tokens** for a list of the uninstall tokens generated for your Agent policies. You can: ++ +** Click the **Show token** icon in the **Token** column to reveal a specific token. +** Click the **View uninstall command** icon in the **Actions** column to open the **Uninstall agent** flyout, containing the full uninstall command with the token. + +TIP: If you have many tamper-protected {agent} policies, you may want to <> in a single command. \ No newline at end of file diff --git a/docs/serverless/edr-install-config/uninstall-agent.asciidoc b/docs/serverless/edr-install-config/uninstall-agent.asciidoc new file mode 100644 index 0000000000..a1051813f7 --- /dev/null +++ b/docs/serverless/edr-install-config/uninstall-agent.asciidoc @@ -0,0 +1,143 @@ +[[security-uninstall-agent]] += Uninstall {agent} + +// :description: Remove {agent} from a host. +// :keywords: serverless, security, how-to + + +To uninstall {agent} from a host, run the `uninstall` command from the directory where it's running. Refer to the {fleet-guide}/uninstall-elastic-agent.html[{fleet} and {agent} documentation] for more information. + +If <> is enabled on the Agent policy for the host, you'll need to include the uninstall token in the command, using the `--uninstall-token` flag. You can <> on the Agent policy or at **{fleet}** -> **Uninstall tokens**. + +For example: + +++++ +
+
+ + + +
+
+++++ +[source,shell] +---- +sudo elastic-agent uninstall --uninstall-token 12345678901234567890123456789012 +---- + +++++ +
+ + +
+++++ + +[discrete] +[[multiple-uninstall-tokens]] +== Provide multiple uninstall tokens + +If you have multiple tamper-protected {agent} policies, you may want to provide multiple uninstall tokens in a single command. There are two ways to do this: + +* The `--uninstall-token` command can receive multiple uninstall tokens separated by a comma, without spaces. ++ +[source,shell] +---------------------------------- +sudo elastic-agent uninstall -f --uninstall-token 7b3d364db8e0deb1cda696ae85e42644,a7336b71e243e7c92d9504b04a774266 +---------------------------------- + +* `--uninstall-token`'s argument can also be a path to a text file with one uninstall token per line. ++ +NOTE: You must use the full file path, otherwise the file may not be found. ++ +[source,shell] +---------------------------------- +sudo elastic-agent uninstall -f --uninstall-token /tmp/tokens.txt +---------------------------------- ++ +In this example, `tokens.txt` would contain: ++ +[source,txt] +---------------------------------- +7b3d364db8e0deb1cda696ae85e42644 +a7336b71e243e7c92d9504b04a774266 +---------------------------------- + +[discrete] +[[uninstall-endpoint]] +== Uninstall {elastic-endpoint} + +Use these commands to uninstall {elastic-endpoint} from a host **ONLY** if {fleet-guide}/uninstall-elastic-agent.html[uninstalling an {agent}] is unsuccessful. + +++++ +
+
+ + + +
+
+++++ +[source,shell] +---- +cd /tmp +cp /Library/Elastic/Endpoint/elastic-endpoint elastic-endpoint +sudo ./elastic-endpoint uninstall +rm elastic-endpoint +---- + +++++ +
+ + +
+++++ From d7d22be4e8db6f7dbc718a969b3135c6d42d250c Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" Date: Tue, 17 Dec 2024 10:17:55 +0000 Subject: [PATCH 2/2] Delete docs/serverless directory and its contents --- .../agent-tamper-protection.asciidoc | 54 ------- .../uninstall-agent.asciidoc | 143 ------------------ 2 files changed, 197 deletions(-) delete mode 100644 docs/serverless/edr-install-config/agent-tamper-protection.asciidoc delete mode 100644 docs/serverless/edr-install-config/uninstall-agent.asciidoc diff --git a/docs/serverless/edr-install-config/agent-tamper-protection.asciidoc b/docs/serverless/edr-install-config/agent-tamper-protection.asciidoc deleted file mode 100644 index 07031a4696..0000000000 --- a/docs/serverless/edr-install-config/agent-tamper-protection.asciidoc +++ /dev/null @@ -1,54 +0,0 @@ -[[security-agent-tamper-protection]] -= Prevent {agent} uninstallation - -// :description: Block unauthorized attempts to uninstall {agent} on hosts. -// :keywords: serverless, security, how-to - - -For hosts enrolled in {elastic-defend}, you can prevent unauthorized attempts to uninstall {agent} and {elastic-endpoint} by enabling **Agent tamper protection** on the Agent policy. This offers an additional layer of security by preventing users from bypassing or disabling {elastic-defend}'s endpoint protections. - -When enabled, {agent} and {elastic-endpoint} can only be uninstalled on the host by including an uninstall token in the uninstall CLI command. One unique uninstall token is generated per Agent policy, and you can retrieve uninstall tokens in an Agent policy's settings or in the {fleet} UI. - -.Requirements -[NOTE] -==== -* Agent tamper protection requires the Endpoint Protection Complete <>. -* Hosts must be enrolled in the {elastic-defend} integration. -* {agent}s must be version 8.11.0 or later. -* This feature is supported for all operating systems. -==== - -[role="screenshot"] -image::images/agent-tamper-protection/agent-tamper-protection.png[Agent tamper protection setting highlighted on Agent policy settings page] - -[discrete] -[[enable-agent-tamper-protection]] -== Enable Agent tamper protection - -You can enable Agent tamper protection by configuring the {agent} policy. - -. Go to **{fleet}** -> **Agent policies**, then select the Agent policy you want to configure. -. Select the **Settings** tab on the policy details page. -. In the **Agent tamper protection** section, turn on the **Prevent agent tampering** setting. -+ -This makes the **Get uninstall command** link available, which you can follow to get the uninstall token and CLI command if you need to <> on this policy. -+ -[TIP] -==== -You can also access an Agent policy's uninstall tokens on the **Uninstall tokens** tab on the **{fleet}** page. Refer to <> for more information. -==== -. Select **Save changes**. - -[discrete] -[[fleet-uninstall-tokens]] -== Access uninstall tokens - -If you need the uninstall token to remove {agent} from an endpoint, you can find it in several ways: - -* **On the Agent policy** — Go to the Agent policy's **Settings** tab, then click the **Get uninstall command** link. The **Uninstall agent** flyout opens, containing the full uninstall command with the token. -* **On the {fleet} page** — Go to **{fleet}** -> **Uninstall tokens** for a list of the uninstall tokens generated for your Agent policies. You can: -+ -** Click the **Show token** icon in the **Token** column to reveal a specific token. -** Click the **View uninstall command** icon in the **Actions** column to open the **Uninstall agent** flyout, containing the full uninstall command with the token. - -TIP: If you have many tamper-protected {agent} policies, you may want to <> in a single command. \ No newline at end of file diff --git a/docs/serverless/edr-install-config/uninstall-agent.asciidoc b/docs/serverless/edr-install-config/uninstall-agent.asciidoc deleted file mode 100644 index a1051813f7..0000000000 --- a/docs/serverless/edr-install-config/uninstall-agent.asciidoc +++ /dev/null @@ -1,143 +0,0 @@ -[[security-uninstall-agent]] -= Uninstall {agent} - -// :description: Remove {agent} from a host. -// :keywords: serverless, security, how-to - - -To uninstall {agent} from a host, run the `uninstall` command from the directory where it's running. Refer to the {fleet-guide}/uninstall-elastic-agent.html[{fleet} and {agent} documentation] for more information. - -If <> is enabled on the Agent policy for the host, you'll need to include the uninstall token in the command, using the `--uninstall-token` flag. You can <> on the Agent policy or at **{fleet}** -> **Uninstall tokens**. - -For example: - -++++ -
-
- - - -
-
-++++ -[source,shell] ----- -sudo elastic-agent uninstall --uninstall-token 12345678901234567890123456789012 ----- - -++++ -
- - -
-++++ - -[discrete] -[[multiple-uninstall-tokens]] -== Provide multiple uninstall tokens - -If you have multiple tamper-protected {agent} policies, you may want to provide multiple uninstall tokens in a single command. There are two ways to do this: - -* The `--uninstall-token` command can receive multiple uninstall tokens separated by a comma, without spaces. -+ -[source,shell] ----------------------------------- -sudo elastic-agent uninstall -f --uninstall-token 7b3d364db8e0deb1cda696ae85e42644,a7336b71e243e7c92d9504b04a774266 ----------------------------------- - -* `--uninstall-token`'s argument can also be a path to a text file with one uninstall token per line. -+ -NOTE: You must use the full file path, otherwise the file may not be found. -+ -[source,shell] ----------------------------------- -sudo elastic-agent uninstall -f --uninstall-token /tmp/tokens.txt ----------------------------------- -+ -In this example, `tokens.txt` would contain: -+ -[source,txt] ----------------------------------- -7b3d364db8e0deb1cda696ae85e42644 -a7336b71e243e7c92d9504b04a774266 ----------------------------------- - -[discrete] -[[uninstall-endpoint]] -== Uninstall {elastic-endpoint} - -Use these commands to uninstall {elastic-endpoint} from a host **ONLY** if {fleet-guide}/uninstall-elastic-agent.html[uninstalling an {agent}] is unsuccessful. - -++++ -
-
- - - -
-
-++++ -[source,shell] ----- -cd /tmp -cp /Library/Elastic/Endpoint/elastic-endpoint elastic-endpoint -sudo ./elastic-endpoint uninstall -rm elastic-endpoint ----- - -++++ -
- - -
-++++