WARNING: Version 6.1 of Auditbeat has passed its EOL date.
This documentation is no longer being maintained and may be removed. If you are running this version, we strongly advise you to upgrade. For the latest information, see the current release documentation.
Audit file metricset
editAudit file metricset
editThe file
metricset sends events when a file is changed (created, updated, or
deleted) on disk. The events contain file metadata and hashes.
The metricset is implemented for Linux, macOS (Darwin), and Windows.
How it works
editThis metricset uses features of the operating system to monitor file changes in realtime. When the metricset 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 metricset will read the file’s metadata and the compute a hash of the file’s contents.
At startup this metricset 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) -
kqueue
is used. It requires one file descriptor for each file so please check theulimit
values used with Auditbeat. The FSEvents API was considered for the implementation, but FSEvents coalesces multiple notifications into a single event which is inconsistent with the metricset’s behavior on other operating systems. -
Windows -
ReadDirectoryChangesW
is used.
The file metricset should not be used to monitor paths on network file systems.
Configuration options
editThis metricset has some configuration options for tuning its behavior. The following example shows all configuration options with their default values for Linux.
- module: audit metricsets: [file] file.paths: - /bin - /usr/bin - /sbin - /usr/sbin - /etc file.scan_at_start: true file.scan_rate_per_sec: 50 MiB file.max_file_size: 100 MiB file.hash_types: [sha1]
-
file.paths
- A list of paths (directories or files) to watch. The watches are non-recursive and globs are not supported. The specified paths should exist when the metricset is started.
-
file.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. -
file.scan_rate_per_sec
-
When
file.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
. -
file.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
. -
file.hash_types
- A list of hash types to compute when the file changes. The supported hash types are md5, sha1, sha224, sha256, sha384, sha512, sha512_224, sha512_256, sha3_224, sha3_256, sha3_384 and sha3_512. The default value is sha1.
Fields
editFor a description of each field in the metricset, see the exported fields section.
Here is an example document generated by this metricset:
{ "@timestamp": "2017-10-06T17:35:33.773Z", "@metadata": { "beat": "noindex", "type": "doc", "version": "1.2.3" }, "audit": { "file": { "hashed": true, "inode": "15329399", "uid": 501, "group": "staff", "ctime": "2017-10-06T17:35:33.000Z", "gid": 20, "path": "/private/var/folders/8x/rnyk6yxn6w97lddn3bs02gf00000gn/T/audit-file387158249/file.data", "mode": "0600", "action": "created", "mtime": "2017-10-06T17:35:33.000Z", "size": 11, "owner": "akroh", "sha1": "2aae6c35c94fcfb415dbe95f408b9ce91ee846ed" } }, "metricset": { "module": "audit", "name": "file", "rtt": 5928 }, "beat": { "name": "host.example.com", "hostname": "host.example.com" } }