From 18e7d59ac1417a0a7dfec74c88996fda0ab20290 Mon Sep 17 00:00:00 2001 From: Joe Peeples Date: Thu, 8 Sep 2022 10:26:29 -0400 Subject: [PATCH 1/5] First draft - Create new reference topic for advanced settings - Create new troubleshooting section - Xrefs and plumbing --- .../configure-integration-policy.asciidoc | 1 + docs/getting-started/index.asciidoc | 1 + .../linux-file-monitoring.asciidoc | 78 +++++++++++++++++++ .../management/ts-management.asciidoc | 18 ++++- 4 files changed, 97 insertions(+), 1 deletion(-) create mode 100644 docs/getting-started/linux-file-monitoring.asciidoc diff --git a/docs/getting-started/configure-integration-policy.asciidoc b/docs/getting-started/configure-integration-policy.asciidoc index f831ea99b0..6631bdf2d0 100644 --- a/docs/getting-started/configure-integration-policy.asciidoc +++ b/docs/getting-started/configure-integration-policy.asciidoc @@ -187,6 +187,7 @@ This section includes: * <> * <> +* <> [discrete] [[save-policy]] diff --git a/docs/getting-started/index.asciidoc b/docs/getting-started/index.asciidoc index 8115ae2133..04af933af0 100644 --- a/docs/getting-started/index.asciidoc +++ b/docs/getting-started/index.asciidoc @@ -20,6 +20,7 @@ include::install-elastic-endpoint.asciidoc[leveloffset=+1] include::configure-integration-policy.asciidoc[leveloffset=+1] include::endpoint-diagnostic-data.asciidoc[leveloffset=+2] include::self-healing-rollback.asciidoc[leveloffset=+2] +include::linux-file-monitoring.asciidoc[leveloffset=+2] include::threat-intel-integrations.asciidoc[leveloffset=+1] include::advanced-setting.asciidoc[leveloffset=+1] include::uninstall-endpoint.asciidoc[leveloffset=+1] diff --git a/docs/getting-started/linux-file-monitoring.asciidoc b/docs/getting-started/linux-file-monitoring.asciidoc new file mode 100644 index 0000000000..78188bcec7 --- /dev/null +++ b/docs/getting-started/linux-file-monitoring.asciidoc @@ -0,0 +1,78 @@ +[[linux-file-monitoring]] += Configure Linux file system monitoring + +By default, {endpoint-cloud-sec} monitors specific Linux file system types that Elastic has tested for compatibility. If your network includes nonstandard, proprietary, or otherwise unrecognized Linux file systems, you can configure the integration policy to extend monitoring and protections to those additional file systems. You can also have {endpoint-cloud-sec} ignore unrecognized file system types if they don't require monitoring or cause unexpected problems. + +CAUTION: Ignoring file systems can create a gaps in your security coverage. Use additional security layers for any file systems ignored by {endpoint-cloud-sec}. + +To monitor or ignore additional file systems, configure the following advanced settings related to *fanotify*, a Linux feature that monitors file system events. Go to *Manage* -> *Policies*, click a policy's name, then scroll down and select *Show advanced settings*. + +NOTE: Even when configured to monitor all file systems (`ignore_unknown_filesystems` is `false`), {endpoint-cloud-sec} will still ignore specific file systems that Elastic has internally identified as incompatible. The following settings apply to any _other_ file systems. + +[[ignore-unknown-filesystems]] +`linux.advanced.fanotify.ignore_unknown_filesystems`:: Determines whether to ignore unrecognized file systems. Enter one of the following: ++ +-- +* `true`: (Default) Monitor only Elastic-tested file systems, and ignore all others. You can still monitor or ignore specific file systems with `monitored_filesystems` and `ignored_filesystems`, respectively. + +* `false`: Monitor all file systems. You can still ignore specific file systems with `ignored_filesystems`. +-- ++ +NOTE: If you've upgraded from 8.3 or earlier, this value will be `false` for backwards compatibility. If you don't need to monitor additional file systems, it's recommended to change `ignore_unknown_filesystems` to `true` after upgrading. + +[[monitored-filesystems]] +`linux.advanced.fanotify.monitored_filesystems`:: Specifies additional file systems to monitor. Enter a comma-separated list of <> as they appear in `/proc/filesystems` (for example: `jfs,ufs,ramfs`). ++ +NOTE: It's recommended to avoid monitoring network-backed file systems. ++ +This setting isn't recognized if `ignore_unknown_filesystems` is `false`, since that would mean you're already monitoring _all_ file systems. ++ +Entries in this setting are overridden by entries in `ignored_filesystems`. + +[[ignored-filesystems]] +`linux.advanced.fanotify.ignored_filesystems`:: Specifies additional file systems to ignore. Enter a comma-separated list of <> as they appear in `/proc/filesystems` (for example: `ext4,tmpfs`). ++ +Entries in this setting override entries in `monitored_filesystems`. + +[[find-file-system-names]] +== Find file system names + +This section provides a few ways to determine the file system names needed for `linux.advanced.fanotify.monitored_filesystems` and `linux.advanced.fanotify.ignored_filesystems`. + +Assuming a typical setup, {filebeat} will be installed alongside {elastic-endpoint} and will automatically ship {elastic-endpoint} logs to {es}. {elastic-endpoint} will generate a log message about the file that was scanned when an event occurred. + +. From the Hosts page (*Explore* -> *Hosts*), search for `message: "Current sync path"` to reveal the file path. + +. If you have access to the endpoint, run `findmnt -o FSTYPE -T ` to return the file system. For example: ++ +[source,shell] +---- +> findmnt -o FSTYPE -T /etc/passwd +FSTYPE +ext4 +---- ++ +This returns the file system name as `ext4`. + +Alternatively, you can also find the file system name by correlating data from two other log messages: + +. Search the logs for `message: "Current fdinfo"` to reveal the `mnt_id` value of the file path. In this example, the `mnt_id` value is `29`: ++ +[source,shell] +---- +pos: 12288 +flags: 02500002 +mnt_id: 29 +ino: 2367737 +---- + +. Search the logs for `message: "Current mountinfo"` to reveal the file system that corresponds to the `mnt_id` value you found in the previous step: ++ +[source,shell] +---- + +29 1 8:2 / / rw,relatime shared:1 - ext4 /dev/sda2 rw,errors=remount-ro + +---- ++ +The first number, `29`, is the `mnt_id`, and the first field after the hyphen (`-`) is the file system name, `ext4`. diff --git a/docs/troubleshooting/management/ts-management.asciidoc b/docs/troubleshooting/management/ts-management.asciidoc index aa1c139374..d060fb6289 100644 --- a/docs/troubleshooting/management/ts-management.asciidoc +++ b/docs/troubleshooting/management/ts-management.asciidoc @@ -33,7 +33,23 @@ TIP: If the {endpoint-cloud-sec} integration policy is not the cause of the `Unh .Disabled to avoid potential system deadlock (Linux) [%collapsible] ==== -This section is a placeholder for future documentation. +If you have an `Unhealthy` {agent} status with the message `Disabled due to potential system deadlock`, that means malware protection was disabled on the {endpoint-cloud-sec} integration policy due to errors while monitoring a Linux host. + +You can resolve the issue by configuring the policy's <> related to *fanotify*, a Linux feature that monitors file system events. By default, {endpoint-cloud-sec} works with fanotify to monitor specific file system types that Elastic has tested for compatibility, and ignores other unknown file system types. + +If your network includes nonstandard, proprietary, or otherwise unrecognized Linux file systems that cause errors while being monitored, you can configure {endpoint-cloud-sec} to ignore those file systems. This allows {endpoint-cloud-sec} to resume monitoring and protecting the hosts on the integration policy. + +CAUTION: Ignoring file systems can create a gaps in your security coverage. Use additional security layers for any file systems ignored by {endpoint-cloud-sec}. + +. Go to *Manage* -> *Policies*, then click a policy's name. + +. Scroll to the bottom of the policy and click *Show advanced settings*. + +. In the setting `linux.advanced.fanotify.ignored_filesystems`, enter a comma-separated list of file system names to ignore, as they appear in `/proc/filesystems` (for example: `ext4,tmpfs`). Refer to <> for more on determining the file system names. + +. Click *Save*. ++ +Once you save the policy, malware protection is re-enabled. ==== [discrete] From 4aed436762cde3c40b7e528e2ac72a45de914ed7 Mon Sep 17 00:00:00 2001 From: Joe Peeples Date: Thu, 8 Sep 2022 10:51:34 -0400 Subject: [PATCH 2/5] Fix typos --- docs/getting-started/linux-file-monitoring.asciidoc | 2 +- docs/troubleshooting/management/ts-management.asciidoc | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/getting-started/linux-file-monitoring.asciidoc b/docs/getting-started/linux-file-monitoring.asciidoc index 78188bcec7..e8fb220ead 100644 --- a/docs/getting-started/linux-file-monitoring.asciidoc +++ b/docs/getting-started/linux-file-monitoring.asciidoc @@ -3,7 +3,7 @@ By default, {endpoint-cloud-sec} monitors specific Linux file system types that Elastic has tested for compatibility. If your network includes nonstandard, proprietary, or otherwise unrecognized Linux file systems, you can configure the integration policy to extend monitoring and protections to those additional file systems. You can also have {endpoint-cloud-sec} ignore unrecognized file system types if they don't require monitoring or cause unexpected problems. -CAUTION: Ignoring file systems can create a gaps in your security coverage. Use additional security layers for any file systems ignored by {endpoint-cloud-sec}. +CAUTION: Ignoring file systems can create gaps in your security coverage. Use additional security layers for any file systems ignored by {endpoint-cloud-sec}. To monitor or ignore additional file systems, configure the following advanced settings related to *fanotify*, a Linux feature that monitors file system events. Go to *Manage* -> *Policies*, click a policy's name, then scroll down and select *Show advanced settings*. diff --git a/docs/troubleshooting/management/ts-management.asciidoc b/docs/troubleshooting/management/ts-management.asciidoc index d060fb6289..676bc27118 100644 --- a/docs/troubleshooting/management/ts-management.asciidoc +++ b/docs/troubleshooting/management/ts-management.asciidoc @@ -39,7 +39,7 @@ You can resolve the issue by configuring the policy's < *Policies*, then click a policy's name. From e03a301c2f27af23345474cce5206dee1c3b2c40 Mon Sep 17 00:00:00 2001 From: Joe Peeples Date: Mon, 12 Sep 2022 09:57:38 -0400 Subject: [PATCH 3/5] Add lead-in before steps --- docs/troubleshooting/management/ts-management.asciidoc | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/troubleshooting/management/ts-management.asciidoc b/docs/troubleshooting/management/ts-management.asciidoc index 676bc27118..68684c72a4 100644 --- a/docs/troubleshooting/management/ts-management.asciidoc +++ b/docs/troubleshooting/management/ts-management.asciidoc @@ -41,6 +41,8 @@ If your network includes nonstandard, proprietary, or otherwise unrecognized Lin CAUTION: Ignoring file systems can create gaps in your security coverage. Use additional security layers for any file systems ignored by {endpoint-cloud-sec}. +To resolve the potential system deadlock error: + . Go to *Manage* -> *Policies*, then click a policy's name. . Scroll to the bottom of the policy and click *Show advanced settings*. From c5548c3f97c60b8bb4919a139322424ad1e84790 Mon Sep 17 00:00:00 2001 From: Joe Peeples Date: Mon, 12 Sep 2022 12:15:10 -0400 Subject: [PATCH 4/5] Revise explanation about Agent, Filebeat, Endpoint --- docs/getting-started/linux-file-monitoring.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/getting-started/linux-file-monitoring.asciidoc b/docs/getting-started/linux-file-monitoring.asciidoc index e8fb220ead..c2a2029ca7 100644 --- a/docs/getting-started/linux-file-monitoring.asciidoc +++ b/docs/getting-started/linux-file-monitoring.asciidoc @@ -39,7 +39,7 @@ Entries in this setting override entries in `monitored_filesystems`. This section provides a few ways to determine the file system names needed for `linux.advanced.fanotify.monitored_filesystems` and `linux.advanced.fanotify.ignored_filesystems`. -Assuming a typical setup, {filebeat} will be installed alongside {elastic-endpoint} and will automatically ship {elastic-endpoint} logs to {es}. {elastic-endpoint} will generate a log message about the file that was scanned when an event occurred. +In a typical setup, when you install {agent}, {filebeat} is installed alongside {elastic-endpoint} and will automatically ship {elastic-endpoint} logs to {es}. {elastic-endpoint} will generate a log message about the file that was scanned when an event occurred. . From the Hosts page (*Explore* -> *Hosts*), search for `message: "Current sync path"` to reveal the file path. From 9a8b2dc74b4276184cbffa083da03489092608f9 Mon Sep 17 00:00:00 2001 From: Joe Peeples Date: Wed, 14 Sep 2022 12:04:42 -0400 Subject: [PATCH 5/5] Add feedback from Janeen's review --- docs/getting-started/linux-file-monitoring.asciidoc | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/getting-started/linux-file-monitoring.asciidoc b/docs/getting-started/linux-file-monitoring.asciidoc index c2a2029ca7..12168bc6c9 100644 --- a/docs/getting-started/linux-file-monitoring.asciidoc +++ b/docs/getting-started/linux-file-monitoring.asciidoc @@ -39,7 +39,9 @@ Entries in this setting override entries in `monitored_filesystems`. This section provides a few ways to determine the file system names needed for `linux.advanced.fanotify.monitored_filesystems` and `linux.advanced.fanotify.ignored_filesystems`. -In a typical setup, when you install {agent}, {filebeat} is installed alongside {elastic-endpoint} and will automatically ship {elastic-endpoint} logs to {es}. {elastic-endpoint} will generate a log message about the file that was scanned when an event occurred. +In a typical setup, when you install {agent}, {filebeat} is installed alongside {elastic-endpoint} and will automatically ship {elastic-endpoint} logs to {es}. {elastic-endpoint} will generate a log message about the file that was scanned when an event occurs. + +To find the system file name: . From the Hosts page (*Explore* -> *Hosts*), search for `message: "Current sync path"` to reveal the file path.