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.

Elastic Docs ›Auditbeat Reference [6.1] ›Modules ›Audit Module
« Audit Module Audit kernel metricset »

Audit file metricsetedit

The 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 worksedit

This 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 the ulimit 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 optionsedit

This 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 are b (default), kib, kb, mib, mb, gib, gb, tib, tb, pib, pb, eib, and eb.
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, and eb.
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.

Fieldsedit

For 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"
  }
}
« Audit Module Audit kernel metricset »