[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 <andrew.kroh@elastic.co> (cherry picked from commit 43cfcae)
elastic · Mar 3, 2025 · 9644bc8 · 9644bc8
1 parent 160cce6
commit 9644bc8
Show file tree

Hide file tree

Showing 5 changed files with 49 additions and 25 deletions.
diff --git 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
@@ -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 <<regexp-support>>
 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
@@ -27,22 +27,37 @@
 {{ 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.
   {{- if eq .GOOS "darwin" }}
   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
@@ -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 <<regexp-support>>
 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
@@ -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