File Integrity Monitoring (im_fim)

This module is capable of scanning files and directories and reporting detected changes and deletions. On the first scan, the checksum of each file is recorded. This checksum is then compared to the checksum value calculated during successive scans. The im_fim module works on the filesystem level, so it only has access to file information such as ownership and last modification date, and no information about which user made a change.

To examine the supported platforms, see the list of installer packages in the Available Modules chapter.

Files are checked periodically, not in real-time. If there are multiple changes between two scans, only the cumulative effect is logged. For example, if one user modifies a file and another user reverts the changes before the next scan occurs, only the change in modification time is detected.

For real-time monitoring, auditing must be enabled on the host operating system. See File Integrity Monitoring in the User Guide for more information.

Configuration

The im_fim module accepts the following directives in addition to the common module directives. The File directive is required.

File: This mandatory directive specifies the name of the input file to scan. It must be a string type expression. See the im_file File directive for more details on how files can be specified. Wildcards are supported. More than one occurrence of the File directive can be used.

Digest: This specifies the digest method (hash function) to be used to calculate the checksum. The default is sha1. The following message digest methods can be used: md2, md5, mdc2, rmd160, sha, sha1, sha224, sha256, sha384, and sha512.

Exclude: This directive can specify a file or a set of files (using wildcards) to be excluded from the scan. More than one occurrence of the Exclude directive can be specified.

ExcludeSize: This directive can be used to specify an upper file size limit, in bytes. The checksum calculation will be skipped for files that exceed this limit, and changes will only be reported based on the file name and attributes.

NoEscape: This boolean directive specifies whether the backslash (\) in file paths should be disabled as an escape sequence. By default, NoEscape is FALSE (the path separator on Windows needs to be escaped).

Recursive

If set to TRUE, this boolean directive instructs the module to search for the filename within the specified directory and any sub-directories. You can use wildcards in combination with Recursive. However, it will only apply the recursive action on the stem of the path. See the examples in the table below. The default is FALSE.

File Directive Matches Directory Matches Filename Examples

File Directive	Matches Directory	Matches Filename	Examples
`/var/log/error.log`	`/var/log/*`	`error.log`	`/var/log/error.log` `/var/log/apt/error.log`
`/var/log/*.log`	`/var/log/*`	`*.log`	`/var/log/error.log` `/var/log/apt/history.log`
`/var/log/*/error.log`	`/var/log//`	`error.log`	`/var/log/apt/error.log` `/var/log/journal/error.log` `/var/log/journal/tmp/error.log`
`/var/*/apt/error.log`	`/var//apt/`	`error.log`	`/var/log/apt/error.log` `/var/log/apt/tmp/error.log` `/var/lib/apt/error.log` `/var/lib/apt/log/error.log`

/var/log/error.log

/var/log/*

error.log

/var/log/error.log
/var/log/apt/error.log

/var/log/*.log

/var/log/*

*.log

/var/log/error.log
/var/log/apt/history.log

/var/log/*/error.log

/var/log/*/*

error.log

/var/log/apt/error.log
/var/log/journal/error.log
/var/log/journal/tmp/error.log

/var/*/apt/error.log

/var/*/apt/*

error.log

/var/log/apt/error.log
/var/log/apt/tmp/error.log
/var/lib/apt/error.log
/var/lib/apt/log/error.log

ScanInterval: This directive specifies how long the module will wait between scans for modifications, in seconds. The default is 86400 seconds (1 day). The value of ScanInterval can be set to 0 to disable periodic scanning and instead invoke scans via the start_scan() procedure.

Functions

The following functions are exported by im_fim.

boolean is_scanning(): Returns TRUE if scanning is in progress.

Procedures

The following procedures are exported by im_fim.

start_scan();: Start the file integrity scan. This could be invoked from the Schedule block, for example.

Fields

The following fields are used by im_fim.

$raw_event (type: string): A list of event fields in key-value pairs.

$Digest (type: string): The calculated digest (checksum) value.

$DigestName (type: string): The name of the digest used to calculate the checksum value (for example, SHA1).

$EventTime (type: datetime): The time when the modification was detected.

$EventType (type: string): One of the following values: CHANGE, DELETE, RENAME, or NEW.

$FileName (type: string): The name of the file that the changes were detected on.

$FileSize (type: integer): The size of the file in bytes after the modification.

$Hostname (type: string): The name of the originating computer.

$ModificationTime (type: datetime): The modification time (mtime) of the file when the change is detected.

$Object (type: string): One of the following values: DIRECTORY or FILE.

$PrevDigest (type: string): The calculated digest (checksum) value from the previous scan.

$PrevFileName (type: string): The name of the file from the previous scan.

$PrevFileSize (type: integer): The size of the file in bytes from the previous scan.

$PrevModificationTime (type: datetime): The modification time (mtime) of the file from the previous scan.

$Severity (type: string): The severity name: WARNING.

$SeverityValue (type: integer): The WARNING severity level value: 3.

Examples

Example 1. Periodic file integrity monitoring

With this configuration, NXLog will monitor the specified directories recursively. Scans will occur hourly.

nxlog.conf

<Input fim>
    Module          im_fim
    File            "/etc/*"
    Exclude         "/etc/mtab"
    File            "/bin/*"
    File            "/sbin/*"
    File            "/usr/bin/*"
    File            "/usr/sbin/*"
    Recursive       TRUE
    ScanInterval    3600
</Input>

Example 2. Scheduled scan

The im_fim module provides a start_scan() procedure that can be called to invoke the scan. The following configuration sets ScanInterval to zero to disable periodic scanning and uses a Schedule block instead to trigger the scan every day at midnight.

nxlog.conf

<Input fim>
    Module          im_fim
    File            "/bin/*"
    File            "/sbin/*"
    File            "/usr/bin/*"
    File            "/usr/sbin/*"
    Recursive       TRUE
    ScanInterval    0
    <Schedule>
        When    @daily
        Exec    start_scan();
    </Schedule>
</Input>