# 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
```json
{
    "@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
| Version | Details | Minimum Kibana version |
| --- | --- | --- |
| **1.17.0** | **Enhancement** - Add 9.2.0 Kibana constraint for the `etw` backend; pin ECS definitions to 9.3.0 and set ingest `ecs.version` to 9.3.0. | 9.2.0 |
| **1.16.0** | **Enhancement** - Add 9.0.0 constraint and update to ECS 8.17.0 | 9.0.0, 8.7.1 |
| **1.15.1** | **Bug fix** - Fix default backend to auto | 8.7.1 |
| **1.15.0** | **Enhancement** - New event sourcing backends added | 8.7.1 | 
| **1.14.2** | **Enhancement** - capture root requirement | 8.7.1 |
| **1.14.1** | **Enhancement** - Changed owners | 8.7.1 |
| **1.14.0** | **Enhancement** - ECS version updated to 8.11.0. | 8.7.1 |
| **1.12.0** | **Enhancement** - The format_version in the package manifest changed from 2.11.0 to 3.0.0. Removed dotted YAML keys from package manifest. Added 'owner.type: elastic' to package manifest. | 8.7.1 |
| **1.10.0** | **Enhancement** - Added dashboard for FIM events overview. | 8.7.1 |
| **1.0.0** | **Enhancement** - Make GA and compatible with 8.2 | 8.2.0 |
| **0.1.0** | **Enhancement** - Initial version | 8.3.0 |