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 at 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.

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 for more information.

Configuration

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

Required directives

The following directives are required for the module to start.

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.

Optional directives

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.

EscapeGlobPatterns

This boolean directive specifies whether the backslash (\) character in glob patterns or wildcarded entries should be enabled as an escape sequence. If set to TRUE, this directive implies that the backslash character (\) needs to be escaped by another backslash character (\\). File and directory patterns on Windows do not require escaping and are processed as non-escaped even if this directive is set to TRUE. The default is FALSE.

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).

Use the EscapeGlobPatterns global directive instead.

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

/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

FollowSymlinks

If set to TRUE, this boolean directive specifies that the module should treat symlnked directories as regular directories. If Recursive also is TRUE then the module will traverse the symlinked directories similar to regular directories. The Exclude directive with the symlinks and target files works as usual except of the case when the symlink name is defined in File directive and the target of that symlink is defined in Exclude directive. The default value of FollowSymlinks is FALSE – the module in this case does not follow the symlinked directories.

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 Agent 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>