From 9644bc8f0a369a87f9f5236977211f9fcf7bacee Mon Sep 17 00:00:00 2001 From: Nico Zanferrari Date: Mon, 3 Mar 2025 17:59:48 +0100 Subject: [PATCH] [Auditbeat] improve docs for exclude_files option of file_integrity (#35669) The exclude_files option can be used for excluding directories, too, if recursive is set to true. This improves the documentation and reference configuration for Auditbeat. I've also added a working example of a folder exclusion for Windows. Co-authored-by: Dan Kortschak <90160302+efd6@users.noreply.github.com> Co-authored-by: Andrew Kroh (cherry picked from commit 43cfcaed808b8c583fa7fa52d22899b8f63e144d) --- auditbeat/auditbeat.reference.yml | 10 +++++++--- auditbeat/docs/modules/file_integrity.asciidoc | 18 ++++++++++-------- .../file_integrity/_meta/config.yml.tmpl | 18 +++++++++++++++--- .../module/file_integrity/_meta/docs.asciidoc | 18 ++++++++++-------- x-pack/auditbeat/auditbeat.reference.yml | 10 +++++++--- 5 files changed, 49 insertions(+), 25 deletions(-) diff --git a/auditbeat/auditbeat.reference.yml b/auditbeat/auditbeat.reference.yml index 9d4919eb24fa..c54679448e90 100644 --- a/auditbeat/auditbeat.reference.yml +++ b/auditbeat/auditbeat.reference.yml @@ -80,6 +80,9 @@ auditbeat.modules: - /usr/sbin - /etc + # Detect changes to files included in subdirectories. Disabled by default. + recursive: false + # List of regular expressions to filter out notifications for unwanted files. # Wrap in single quotes to workaround YAML escaping rules. By default no files # are ignored. @@ -88,6 +91,10 @@ auditbeat.modules: - '~$' - '/\.git($|/)' + # If recursive is set to true, subdirectories can also be excluded here by + # specifying them. + # - '(?i)/tmp/' + # List of regular expressions used to explicitly include files. When configured, # Auditbeat will ignore files unless they match a pattern. #include_files: @@ -115,9 +122,6 @@ auditbeat.modules: # Default is sha1. hash_types: [sha1] - # Detect changes to files included in subdirectories. Disabled by default. - recursive: false - # Set to true to publish fields with null values in events. #keep_null: false diff --git a/auditbeat/docs/modules/file_integrity.asciidoc b/auditbeat/docs/modules/file_integrity.asciidoc index 5257099270bd..872ba5189255 100644 --- a/auditbeat/docs/modules/file_integrity.asciidoc +++ b/auditbeat/docs/modules/file_integrity.asciidoc @@ -19,7 +19,7 @@ This module uses features of the operating system to monitor file changes in realtime. When the module starts it creates a subscription with the OS to receive notifications of changes to the specified files or directories. Upon receiving notification of a change the module will read the file's metadata -and the compute a hash of the file's contents. +and then compute a hash of the file's contents. At startup this module will perform an initial scan of the configured files and directories to generate baseline data for the monitored paths and detect @@ -62,6 +62,7 @@ Linux. - /sbin - /usr/sbin - /etc + recursive: false exclude_files: - '(?i)\.sw[nop]$' - '~$' @@ -71,7 +72,6 @@ Linux. scan_rate_per_sec: 50 MiB max_file_size: 100 MiB hash_types: [sha1] - recursive: false ---- This module also supports the @@ -88,6 +88,12 @@ the watch target. If the link does not resolve to a valid target, the symbolic link itself will be watched; if the symlink target becomes valid after module start up this will not be picked up by the file system watches. +*`recursive`*:: By default, the watches set to the paths specified in +`paths` are not recursive. This means that only changes to the contents +of this directories are watched. If `recursive` is set to `true`, the +`file_integrity` module will watch for changes on this directory and all +its subdirectories. + *`exclude_files`*:: A list of regular expressions used to filter out events for unwanted files. The expressions are matched against the full path of every file and directory. When used in conjunction with `include_files`, file paths need @@ -96,6 +102,8 @@ By default, no files are excluded. See <> for a list of supported regexp patterns. It is recommended to wrap regular expressions in single quotation marks to avoid issues with YAML escaping rules. +If `recursive` is set to true, subdirectories can also be excluded here by +specifying them. *`include_files`*:: A list of regular expressions used to specify which files to select. When configured, only files matching the pattern will be monitored. @@ -144,12 +152,6 @@ when a file event involves the file. Files that are not targets of the specific file parser are only sniffed to examine whether analysis should proceed. This will usually only involve reading a small number of bytes. -*`recursive`*:: By default, the watches set to the paths specified in -`paths` are not recursive. This means that only changes to the contents -of this directories are watched. If `recursive` is set to `true`, the -`file_integrity` module will watch for changes on this directories and all -their subdirectories. - *`backend`*:: (*Linux only*) Select the backend which will be used to source events. Valid values: `auto`, `fsnotify`, `kprobes`, `ebpf`. Default: `fsnotify`. diff --git a/auditbeat/module/file_integrity/_meta/config.yml.tmpl b/auditbeat/module/file_integrity/_meta/config.yml.tmpl index b3a3784d15c3..e5d2cc55265a 100644 --- a/auditbeat/module/file_integrity/_meta/config.yml.tmpl +++ b/auditbeat/module/file_integrity/_meta/config.yml.tmpl @@ -27,6 +27,9 @@ {{ end -}} {{- if .Reference }} + # Detect changes to files included in subdirectories. Disabled by default. + recursive: false + # List of regular expressions to filter out notifications for unwanted files. # Wrap in single quotes to workaround YAML escaping rules. By default no files # are ignored. @@ -34,15 +37,27 @@ exclude_files: - '\.DS_Store$' - '\.swp$' + + # If recursive is set to true, subdirectories can also be excluded here by + # specifying them. + # - '(?i)/tmp/' {{- else if eq .GOOS "windows" }} exclude_files: - '(?i)\.lnk$' - '(?i)\.swp$' + + # If recursive is set to true, subdirectories can also be excluded here by + # specifying them. + # - '(?i)\\temp\\' {{- else }} exclude_files: - '(?i)\.sw[nop]$' - '~$' - '/\.git($|/)' + + # If recursive is set to true, subdirectories can also be excluded here by + # specifying them. + # - '(?i)/tmp/' {{- end }} # List of regular expressions used to explicitly include files. When configured, @@ -80,9 +95,6 @@ # Default is sha1. hash_types: [sha1] - # Detect changes to files included in subdirectories. Disabled by default. - recursive: false - # Set to true to publish fields with null values in events. #keep_null: false diff --git a/auditbeat/module/file_integrity/_meta/docs.asciidoc b/auditbeat/module/file_integrity/_meta/docs.asciidoc index 35031d8acea0..da5e303e847b 100644 --- a/auditbeat/module/file_integrity/_meta/docs.asciidoc +++ b/auditbeat/module/file_integrity/_meta/docs.asciidoc @@ -12,7 +12,7 @@ This module uses features of the operating system to monitor file changes in realtime. When the module starts it creates a subscription with the OS to receive notifications of changes to the specified files or directories. Upon receiving notification of a change the module will read the file's metadata -and the compute a hash of the file's contents. +and then compute a hash of the file's contents. At startup this module will perform an initial scan of the configured files and directories to generate baseline data for the monitored paths and detect @@ -55,6 +55,7 @@ Linux. - /sbin - /usr/sbin - /etc + recursive: false exclude_files: - '(?i)\.sw[nop]$' - '~$' @@ -64,7 +65,6 @@ Linux. scan_rate_per_sec: 50 MiB max_file_size: 100 MiB hash_types: [sha1] - recursive: false ---- This module also supports the @@ -81,6 +81,12 @@ the watch target. If the link does not resolve to a valid target, the symbolic link itself will be watched; if the symlink target becomes valid after module start up this will not be picked up by the file system watches. +*`recursive`*:: By default, the watches set to the paths specified in +`paths` are not recursive. This means that only changes to the contents +of this directories are watched. If `recursive` is set to `true`, the +`file_integrity` module will watch for changes on this directory and all +its subdirectories. + *`exclude_files`*:: A list of regular expressions used to filter out events for unwanted files. The expressions are matched against the full path of every file and directory. When used in conjunction with `include_files`, file paths need @@ -89,6 +95,8 @@ By default, no files are excluded. See <> for a list of supported regexp patterns. It is recommended to wrap regular expressions in single quotation marks to avoid issues with YAML escaping rules. +If `recursive` is set to true, subdirectories can also be excluded here by +specifying them. *`include_files`*:: A list of regular expressions used to specify which files to select. When configured, only files matching the pattern will be monitored. @@ -137,12 +145,6 @@ when a file event involves the file. Files that are not targets of the specific file parser are only sniffed to examine whether analysis should proceed. This will usually only involve reading a small number of bytes. -*`recursive`*:: By default, the watches set to the paths specified in -`paths` are not recursive. This means that only changes to the contents -of this directories are watched. If `recursive` is set to `true`, the -`file_integrity` module will watch for changes on this directories and all -their subdirectories. - *`backend`*:: (*Linux only*) Select the backend which will be used to source events. Valid values: `auto`, `fsnotify`, `kprobes`, `ebpf`. Default: `fsnotify`. diff --git a/x-pack/auditbeat/auditbeat.reference.yml b/x-pack/auditbeat/auditbeat.reference.yml index dd3655c8f720..6bc035a3efd0 100644 --- a/x-pack/auditbeat/auditbeat.reference.yml +++ b/x-pack/auditbeat/auditbeat.reference.yml @@ -80,6 +80,9 @@ auditbeat.modules: - /usr/sbin - /etc + # Detect changes to files included in subdirectories. Disabled by default. + recursive: false + # List of regular expressions to filter out notifications for unwanted files. # Wrap in single quotes to workaround YAML escaping rules. By default no files # are ignored. @@ -88,6 +91,10 @@ auditbeat.modules: - '~$' - '/\.git($|/)' + # If recursive is set to true, subdirectories can also be excluded here by + # specifying them. + # - '(?i)/tmp/' + # List of regular expressions used to explicitly include files. When configured, # Auditbeat will ignore files unless they match a pattern. #include_files: @@ -115,9 +122,6 @@ auditbeat.modules: # Default is sha1. hash_types: [sha1] - # Detect changes to files included in subdirectories. Disabled by default. - recursive: false - # Set to true to publish fields with null values in events. #keep_null: false