[Auditbeat] Add fanotify watcher support for File integrity module on Linux

[r00tu53r]

Background

Auditbeat file_integrity on Linux uses inotify API for monitoring filesystem events. Though the inotify provides a stable API across a wide range of kernel versions starting from 2.6.13 it has a few drawbacks.

• It is the application's responsibility to cache a mapping (if one is needed) between watch descriptors and pathnames.
• Monitoring entire filesystems can get performance intensive as this has to be done at the application level.

Users using inotify to monitor growing / large directories have observed performance issues (#26247).

The Fanotify API introduced into Linux 2.6.37 ^{(1, 2, 3)} addresses some of the performance issues that is encountered when using inotify.

Requirement

The requirement is to enable Auditbeat's file integrity module to choose a filesystem watcher on Linux.

Proposed configuration

Add a configuration setting to choose the watcher.

- module: file_integrity
  watcher:
    linux: fanotify

watcher.linux can hold the supported watchers (inotify, fanotify).

Support

Auditbeat uses a Go library fsnotify for the inotify calls. The fsnotify library does not yet support calls to fanotify system calls. It is unlikely this will be supported in the near future as mentioned in the issue fsnotify/fsnotify#114.

Caveat

Not all fanotify return structures are defined / implemented in the sys/unix package. Some of the undefined structures include fanotify_event_info_fid, fanotify_event_info_header.

[r00tu53r]

Fanotify API

Though fanotify was introduced in 2.6.36 the feature set has taken a long time to reach and in some cases surpass that of “inotify”.

The table below describes the feature set / flags available across different kernel versions -

Kernel Version	Feature Set / Flags
v2.6.36	FAN_ACCESS, FAN_ACCESS_PERM, FAN_ALL_INIT_FLAGS, FAN_CLOEXEC, FAN_CLOSE, FAN_CLOSE_NOWRITE, FAN_CLOSE_WRITE, FAN_EVENT_ON_CHILD, FAN_MARK_ADD, FAN_MARK_DONT_FOLLOW, FAN_MARK_FLUSH, FAN_MARK_IGNORED_MASK,FAN_MARK_IGNORED_SURV_MODIFY,FAN_MARK_MOUNT, FAN_MARK_ONLYDIR, FAN_MARK_REMOVE, FAN_MODIFY, FAN_NONBLOCK, FAN_OPEN, FAN_OPEN_PERM, FAN_Q_OVERFLOW
v2.6.37	FAN_ALL_CLASS_BITS, FAN_CLASS_CONTENT, FAN_CLASS_NOTIF, FAN_CLASS_PRE_CONTENT, FAN_ONDIR, FAN_UNLIMITED_MARKS, FAN_UNLIMITED_QUEUE
v4.15	FAN_ENABLE_AUDIT
v4.20	FAN_MARK_FILESYSTEM, FAN_MARK_INODE, FAN_REPORT_TID
v5.0	FAN_OPEN_EXEC, FAN_OPEN_EXEC_PERM
v5.1	FAN_ATTRIB, FAN_CREATE, FAN_DELETE, FAN_DELETE_SELF, FAN_MOVE, FAN_MOVED_FROM, FAN_MOVED_TO, FAN_MOVE_SELF, FAN_REPORT_FID
v5.9	FAN_REPORT_DFID_NAME, FAN_REPORT_DIR_FID, FAN_REPORT_NAME
v5.15	FAN_REPORT_PIDFD
v5.16	FAN_FS_ERROR

To get information about the name of the directory/file that was modified the FAN_REPORT_NAME and/or FAN_REPORT_DFID_NAME must be set in the fanotify_init call. And the corresponding return flags (FAN_EVENT_INFO_TYPE_FID, FAN_EVENT_INFO_TYPE_DFID, FAN_EVENT_INFO_TYPE_DFID_NAME, FAN_EVENT_INFO_TYPE_DFID_NAME) must be checked in the mask before accessing the structure.

This means for Auditbeat to support the required features that matches inotify the users kernel versions must at minimum v5.9.

Support

The fanotify API is available only if the kernel was built with the CONFIG_FANOTIFY configuration option enabled. In addition, fanotify permission handling is available only if the CONFIG_FANOTIFY_ACCESS_PERMISSIONS configuration option is enabled.

Refer to NOTES section of the fanotify man(7) page.

Limitations

Fanotify has certain limitations that might affect the implementation / application.

Refer to Limitaions and caveats section of the fanotify man(7) page.

[elasticmachine]

Pinging @elastic/security-external-integrations (Team:Security-External Integrations)

[elasticmachine]

Pinging @elastic/sec-linux-platform (Team:Security-Linux Platform)

[andrewkroh]

Closing because we are taking a different path than fanotify. The module will instead get a kprobe and eBPF backend implementation.