File Integrity Module
editFile Integrity Module
editThe file_integrity
module sends events when a file is changed (created,
updated, or deleted) on disk. The events contain file metadata and hashes.
The module is implemented for Linux, macOS (Darwin), and Windows.
How it works
editThis 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.
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 changes since the last time it was run. It uses locally persisted data in order to only send events for new or modified files.
The operating system features that power this feature are as follows.
-
Linux -
inotify
is used, and therefore the kernel must have inotify support. Inotify was initially merged into the 2.6.13 Linux kernel. -
macOS (Darwin) - Uses the
FSEvents
API, present since macOS 10.5. This API coalesces multiple changes to a file into a single event. Auditbeat translates this coalesced changes into a meaningful sequence of actions. However, in rare situations the reported events may have a different ordering than what actually happened. -
Windows -
ReadDirectoryChangesW
is used.
The file integrity module should not be used to monitor paths on network file systems.
Configuration options
editThis module has some configuration options for tuning its behavior. The following example shows all configuration options with their default values for Linux.
- module: file_integrity paths: - /bin - /usr/bin - /sbin - /usr/sbin - /etc exclude_files: - '(?i)\.sw[nop]$' - '~$' - '/\.git($|/)' include_files: [] scan_at_start: true scan_rate_per_sec: 50 MiB max_file_size: 100 MiB hash_types: [sha1] recursive: false
This module also supports the standard configuration options described later.
-
paths
- A list of paths (directories or files) to watch. Globs are not supported. The specified paths should exist when the metricset is started. Paths should be absolute, although the file integrity module will attempt to resolve relative path events to their absolute file path.
-
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 to match bothinclude_files
and not matchexclude_files
to be selected. By default, no files are excluded. See Regular expression 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. -
include_files
-
A list of regular expressions used to specify which files to
select. When configured, only files matching the pattern will be monitored.
The expressions are matched against the full path of every file and directory.
When used in conjunction with
exclude_files
, file paths need to match bothinclude_files
and not matchexclude_files
to be selected. By default, all files are selected. See Regular expression 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. -
scan_at_start
-
A boolean value that controls if Auditbeat scans over the configured file paths at startup and send events for the files that have been modified since the last time Auditbeat was running. The default value is true.
This feature depends on data stored locally in
path.data
in order to determine if a file has changed. The first time Auditbeat runs it will send an event for each file it encounters. -
scan_rate_per_sec
-
When
scan_at_start
is enabled this sets an average read rate defined in bytes per second for the initial scan. This throttles the amount of CPU and I/O that Auditbeat consumes at startup. The default value is "50 MiB". Setting the value to "0" disables throttling. For convenience units can be specified as a suffix to the value. The supported units areb
(default),kib
,kb
,mib
,mb
,gib
,gb
,tib
,tb
,pib
,pb
,eib
, andeb
. -
max_file_size
-
The maximum size of a file in bytes for which
Auditbeat will compute hashes. Files larger than this size will not be
hashed. The default value is 100 MiB. For convenience units can be specified as
a suffix to the value. The supported units are
b
(default),kib
,kb
,mib
,mb
,gib
,gb
,tib
,tb
,pib
,pb
,eib
, andeb
. -
hash_types
-
A list of hash types to compute when the file changes.
The supported hash types are
blake2b_256
,blake2b_384
,blake2b_512
,md5
,sha1
,sha224
,sha256
,sha384
,sha512
,sha512_224
,sha512_256
,sha3_224
,sha3_256
,sha3_384
,sha3_512
, andxxh64
. The default value issha1
. -
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. Ifrecursive
is set totrue
, thefile_integrity
module will watch for changes on this directories and all their subdirectories.
Standard configuration options
editYou can specify the following options for any Auditbeat module.
-
module
- The name of the module to run.
-
enabled
- A Boolean value that specifies whether the module is enabled.
-
fields
- A dictionary of fields that will be sent with the dataset event. This setting is optional.
-
tags
- A list of tags that will be sent with the dataset event. This setting is optional.
-
processors
-
A list of processors to apply to the data generated by the dataset.
See Processors for information about specifying processors in your config.
-
index
-
If present, this formatted string overrides the index for events from this module (for elasticsearch outputs), or sets the
raw_index
field of the event’s metadata (for other outputs). This string can only refer to the agent name and version and the event timestamp; for access to dynamic fields, useoutput.elasticsearch.index
or a processor.Example value:
"%{[agent.name]}-myindex-%{+yyyy.MM.dd}"
might expand to"auditbeat-myindex-2019.12.13"
. -
keep_null
-
If this option is set to true, fields with
null
values will be published in the output document. By default,keep_null
is set tofalse
. -
service.name
-
A name given by the user to the service the data is collected from. It can be
used for example to identify information collected from nodes of different
clusters with the same
service.type
.
Example configuration
editThe File Integrity module supports the common configuration options that are described under configuring Auditbeat. Here is an example configuration:
auditbeat.modules: - module: file_integrity paths: - /bin - /usr/bin - /sbin - /usr/sbin - /etc