== File Integrity Module

The `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.

[float]
=== How it works

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.

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. {beatname_uc} 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.

[float]
=== Configuration options

This module has some configuration options for tuning its behavior. The
following example shows all configuration options with their default values for
Linux.

[source,yaml]
----
- 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
<<module-standard-options-{modulename},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. Symbolic links will
be resolved on module start and the link target will be watched if link resolution
is successful. Changes to the symbolic link after module start will not change
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.

*`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 both `include_files` and not match `exclude_files` to be selected.
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.

*`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 both `include_files` and not match `exclude_files` to be selected.
By default, all files are selected. 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.

*`scan_at_start`*:: A boolean value that controls if {beatname_uc} scans
over the configured file paths at startup and send events for the files
that have been modified since the last time {beatname_uc} 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 {beatname_uc} 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 {beatname_uc} 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 are `b` (default), `kib`, `kb`, `mib`, `mb`, `gib`, `gb`, `tib`, `tb`,
`pib`, `pb`, `eib`, and `eb`.

*`max_file_size`*:: The maximum size of a file in bytes for which
{beatname_uc} 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`, and `eb`.

*`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`, and `xxh64`. The default value is `sha1`.

*`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.

include::{docdir}/auditbeat-options.asciidoc[]
