Configuring FIM Add-on for PCF

Page last updated:

This topic describes how to configure and use the File Integrity Monitoring Add-on for PCF (FIM Add-on).

Listing Directories to be Monitored

The FIM Add-on monitors a set of critical system directories. The list of directories to be monitored by the FIM Add-on can be configured using the fim.dirs property. The default value of fim.dirs is:

fim:
  dirs:
    - /bin
    - /etc
    - /lib
    - /lib64
    - /opt
    - /sbin
    - /srv
    - /usr
    - /var/lib
    - /var/vcap/bosh
    - /var/vcap/data/packages
    - /var/vcap/monit/job
    - /var/vcap/data/jobs

Configure the Output Destination

FIM supports three types of output:

  • stdout: sends messages to /var/vcap/sys/log/fim/fim.stdout.log.
  • stderr: sends messages to /var/vcap/sys/log/fim/fim.stderr.log.
  • syslog: sends messages to /var/log/messages.

The output is configured using the fim.outputs property.

Note: Currently, FIM only supports selecting one output at a time.

The default value of the fim.outputs property:

fim:
  outputs:
    - syslog

Configure the Output Format

By default, the FIM Add-on generates messages in the Common Event Format. Output format can be configured as a Golang text template using the fim.format property. The default value of fim.format is:

fim:
  format: "CEF:0|cloud_foundry|fim|1.0.0|{{.Map.optype}}|file integrity monitoring event|5| {{.KeyValues}}"

This example output shows what log lines look like with the default fim.format configuration:

Apr 20 19:12:37 localhost filesnitch[819]: FILESNITCH CHECKIN {}
Apr 20 19:17:02 localhost filesnitch[819]: CEF:0|cloud_foundry|fim|1.0.0|1|file integrity monitoring event|5| fname="/etc/passwd.lock" hostname="8279dfa8-9f86-4bb1-8b92-65457d2ae989" opname="CREATE" optype=1 ts=1492715822
Apr 20 19:17:02 localhost filesnitch[819]: CEF:0|cloud_foundry|fim|1.0.0|4|file integrity monitoring event|5| fname="/etc/passwd.17721" hostname="8279dfa8-9f86-4bb1-8b92-65457d2ae989" opname="REMOVE" optype=4 ts=1492715822
Apr 20 19:17:02 localhost filesnitch[819]: CEF:0|cloud_foundry|fim|1.0.0|1|file integrity monitoring event|5| fname="/etc/group.lock" hostname="8279dfa8-9f86-4bb1-8b92-65457d2ae989" opname="CREATE" optype=1 ts=1492715822
Apr 20 19:17:02 localhost filesnitch[819]: CEF:0|cloud_foundry|fim|1.0.0|4|file integrity monitoring event|5| fname="/etc/group.17721" hostname="8279dfa8-9f86-4bb1-8b92-65457d2ae989" opname="REMOVE" optype=4 ts=1492715822
Apr 20 19:17:02 localhost filesnitch[819]: CEF:0|cloud_foundry|fim|1.0.0|1|file integrity monitoring event|5| fname="/etc/gshadow.lock" hostname="8279dfa8-9f86-4bb1-8b92-65457d2ae989" opname="CREATE" optype=1 ts=1492715822

Note: The FILESNITCH CHECKIN message is a logging marker that indicates filesnitch is operational in the absence of any filesystem events.

The key-values pairs in the final field of a CEF file log carry the following meaning:

  • fname is the name of the affected file.
  • hostname is the hostname of the VM on which the file event originated.
  • ts is the point in time at which FIM received the file event.
  • optype and opname are the type of file operation in the numeric and textual format, respectively. The possible values of the two fields are described by the table below.

    opname optype Example Trigger
    CREATE 1 touch newfile.txt, echo 'content' > newfile2.txt
    WRITE 2 echo 'hello world' >> file.txt
    REMOVE 4 rm file.txt
    RENAME 8 mv file.txt file.txt.orig
    CHMOD 16 chmod 0400 file.txt, touch existingfile.txt

Other template values are listed below.

JSON

The {{.Json}} string serializes an event into a standard JSON dictionary. Example:

{"fname":"/bin/binary","hostname":"plymouth","opname":"CREATE","optype":1,"ts":1475195084}

Key-Values

The {{.KeyValues}} string serializes an event into a series of key=value fields. Example:

fname="/bin/binary" hostname="plymouth" opname="CREATE" optype=1 ts=1475195258

Map

The {{.Map}} string provides attribute-level access on an event.

For example, the following variable definition:

fim:
  format: "{{.Map.fname}} {{.Map.hostname}} {{.Map.opname}} {{.Map.optype}} {{.Map.ts}}"

produces the following:

/bin/binary plymouth CREATE 1 da39a3ee5e6b4b0d3255bfef95601890afd80709 1475195574

Calculate File Hashes

The FIM Add-on supports hashing monitored files on WRITE or CREATE events using the sha256 algorithm. Hashing is disabled by default, and can be configured using the fim.digests property, as follows:

fim:
  digests:
    - sha256

File Size Threshold

The FIM Add-on sets a threshold on the size of files to be hashed. Use the fim.digest_threshold property to adjust this threshold. The property takes a value in bytes. The default value is 10000000.

fim:
  digest_threshold: 10000000
Create a pull request or raise an issue on the source for this page in GitHub