File Integrity Monitoring Integration

Overview

This integration sends events when a file is changed (created, updated, or deleted) on disk. The events contain file metadata and hashes.

Supported OS: Linux, macOS (Darwin), and Windows.

⚠️ This integration should not be used to monitor paths on network file systems.

How it works

This integration uses features of the operating system to monitor file changes in realtime. When the integration 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 integration will read the file’s metadata and then compute a hash of the file’s contents.

At startup, this integration 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.

Compatibility

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.

Example Event

{
    "@timestamp": "2025-03-13T12:17:44.217Z",
    "agent": {
        "ephemeral_id": "a3670431-8505-4619-92b6-10c1ae66f027",
        "id": "09bea17f-617d-4342-8fa8-6021743dacc6",
        "name": "elastic-agent-67615",
        "type": "auditbeat",
        "version": "8.17.3"
    },
    "data_stream": {
        "dataset": "fim.event",
        "namespace": "55403",
        "type": "logs"
    },
    "ecs": {
        "version": "9.3.0"
    },
    "elastic_agent": {
        "id": "09bea17f-617d-4342-8fa8-6021743dacc6",
        "snapshot": false,
        "version": "8.17.3"
    },
    "event": {
        "action": [ "created" ],
        "agent_id_status": "verified",
        "category": [ "file" ],
        "dataset": "fim.event",
        "ingested": "2025-03-13T12:17:46Z",
        "kind": "event",
        "module": "file_integrity",
        "type": [ "creation" ]
    },
    "file": {
        "ctime": "2025-03-13T12:17:44.208Z",
        "gid": "0",
        "group": "root",
        "hash": {
            "sha1": "22596363b3de40b06f981fb85d82312e8c0ed511"
        },
        "inode": "1096549",
        "mode": "0644",
        "mtime": "2025-03-13T12:17:44.208Z",
        "owner": "root",
        "path": "/tmp/service_logs/hello",
        "size": 12,
        "type": "file",
        "uid": "0"
    },
    "host": {
        "architecture": "x86_64",
        "containerized": true,
        "hostname": "elastic-agent-67615",
        "ip": [ "172.20.0.2", "172.18.0.7" ],
        "mac": [ "02-42-AC-12-00-07", "02-42-AC-14-00-02" ],
        "name": "elastic-agent-67615",
        "os": {
            "family": "",
            "kernel": "5.15.153.1-microsoft-standard-WSL2",
            "name": "Wolfi",
            "platform": "wolfi",
            "type": "linux",
            "version": "20230201"
        }
    },
    "service": {
        "type": "file_integrity"
    },
    "tags": [ "fim-event" ]
}

Screenshots

This integration includes one or more Kibana dashboards that visualizes the data collected by the integration.

Changelog