This manual corresponds to integrit version 4.0.

Copyright (C) 2006 Ed L. Cashin

Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies.

Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one.

Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions, except that this permission notice may be stated in a translation approved by the Foundation.

Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided also that the section entitled ``GNU General Public License'' is included exactly as in the original, and provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one.

Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions, except that the section entitled ``GNU General Public License'' may be included in a translation approved by the Free Software Foundation instead of in the original English.

This manual corresponds to integrit version 4.0.

Introduction
************

Description
===========

The integrit system detects intrusion by detecting when trusted files have been altered.

By creating an integrit database (update mode) that is a snapshot of a host system in a known state, the host's files can later be verified as unaltered by running integrit in check mode to compare current state to the recorded known state.  integrit can do a check and an update simultaneously.

Normal Use
==========

Using a product like integrit for intrusion detection is a repeating process, involving something like the following activities:

 1. generate a new current-state database while checking against an old known-state database that has been protected from modification (e.g. by putting it on read-only media or on a secure server), mailing the output to a remote machine (or more)

     This step can be done unattended, since the report that integrit generates at runtime includes the checksum of the newly-generated current-state database.  The output should be directed to a remote host, e.g., via a trusted sendmail binary.

     You may use a script to renice the integrit process and possibly do a sequence of runs, each with a different configuration file.

 2. read the report, possibly using UN*X or XML tools to massage it into a form to your liking

     There is an example GUI viewer for integrit's XML output in the examples directory of the distribution.

     Below please find a description of the syntax of integrit's human-readable output format.

 3. if the report looks fine, copy the new database to a secure server for export via read-only NFS, or a secure medium that can be made read-only. (saving the old one in case something goes wrong.)

 4. IMPORTANT: verify that the current checksum of the database you just copied over matches the one in the report. (This shows that no one has tampered with the database since the report and the new database were generated.)

 5. everything's OK, so the new database will be the known-state database the next time you repeat this process.

Invoking Integrit
*****************

Here is a list of command-line arguments that may be used when invoking integrit:

-C {conffile}

     Specify a runtime configuration file for integrit.

-V

     Show integrit version information and exit.

-h

     Show brief help.

-x

     Produce XML output.

-u

     Do update - create a new database that reflects the current state of the system.

-c

     Do check - compare the current state of the system to a database containing a snapshot of the system when it was in a known state.

-N

     Manually override specification of the current (``New'') database. Normally it is set in the configuration file.

-O

     Manually override specification of the known (``Old'') database. Normally it is set in the configuration file.

-q

     Lower integrit's level of verbosity.

-v

     Increase integrit's level of verbosity.

Configuration File
******************

The configuration file determines what integrit does when it runs. For that reason, it should be kept on a secure medium, like a CD-ROM or a directory that's exported via read-only NFS from a tightly-secured machine. (Your kernel may also support read-only files on the localhost.  The FreeBSD kernel, for example, when running in higher security levels, honors the ``immutable'' file attribute.  On such a system you could keep integrit's known database locally, but you'd have to install it in single-user mode.)

Please note that a trailing slash is never part of a filename, including directory names.  A slash is a path separator, and any other use is not supported.

Config File Elements
====================

  * comments

     The following kinds of lines in the configuration file are ignored by integrit: blank lines; lines consisting of whitespace only; lines having the # character as the first non-whitespace character.

  * known database

     The location of the known database (which contains information about the previous state of the host's files) is specified with a line like this:

               known=/root/databases/usr_known.cdb

  * current database

     The location of the current database (the one to be generated if integrit is doing an update) is specified in a similar manner.

              current=/root/databases/usr_current.cdb

  * the root of integrit's check

     The root of the filetree that integrit will cover is specified on a line like this:

              root=/usr

     Integrit's file tree walk starts at the root.  Everything integrit checks must be under the root.  In the above example, the "/boot" directory will never be checked because it is not under /usr.  You can specify slash as the root and then ignore lots of directories like /tmp, /proc, and /home, or you can use multiple configuration files.

     To search multiple roots, use multiple configure files and launch multiple instances of integrit, either in sequence or in parallel, depending on your needs.

  * behavior on errors

     By default integrit stops scanning at the first error. When running as root, errors usually mean severely broken permissions or media errors that the administrator should take note of immediately. When stop_on_err is set to ``0'' instead, integrit will try to continue as much as possible, ignoring all non-fatal errors in the process.

  * rules

     Rules in the configuration file tell integrit how to treat various parts of the filesystem.  You can tell integrit to ignore /proc, not to do checksums on logfiles, not to descend into /home, to ignore the modification time on /etc/issue, etc.

     Whether or not integrit descends parts of the filetree, and whether or not it does checksums, comparison of access times, etc., are specified in a compact syntax (described below) on lines like these:

              !/usr/local/useless
              !/usr/mnt/nfs
              =/usr/share/teTeX
              /usr/local/var/log SIAM

     We'll get into the nitty gritty in the following sections.

Config Rule Prefixes
====================

When integrit is running it can do several things.  By specifying rules for integrit to follow, you can control its behavior.  Each rule has an optional prefix or prefixes, a filename (or directory name), and a set of checks that integrit should or should not do.

A prefix comes before the filename and tells integrit something

!

     An exclamation point means ``ignore''.

     It will cause integrit to pretend a file or directory isn't there.

              # ignore the useless directory and its subdirectories
              !/usr/local/useless

=

     An equal sign means ``don't descend''.  It will cause integrit to do checks on the file itself, but if it's a directory, integrit won't visit its subdirectories.

     This is useful for telling integrit not to bother with certain parts of a file tree.

              # don't bother with old_project's subdirectories,
              # but do perform normal checks on the directory itself
              =/usr/local/share/old_project

     You can cut down drastically on database size and integrit's runtime by ignoring parts of the filesystem that are not essential to the system, e.g., home directories.

     In general, integrit is much easier to use on a daily basis if it's just checking the most essential parts of a system.  Some sysadmins, however, have told me that they enjoy getting more in touch with their systems by having integrit monitor almost everything!

$

     A dollar sign prefix indicates a non-cascading rule that doesn't get inherited by subdirectories and files as regular rules do.

              # this redhat system updates /etc/issue on boot
              # so we ignore modification and change time on /etc,
              # but we still want to monitor mtime and ctime on
              # some files and directories under this /etc.

              $ /etc     MC

Config Rule Checksets
=====================

  * a set of switches

     A filename followed by a set of one-letter switches turns checks on and off, for example:

              # do check the access time, but don't do a checksum:
              /usr/local/secret/text.txt aS

     There are no spaces between the switches.

  * switch syntax

     Upper case turns off a given check. Lower case turns it on.

     When you turn off a check, e.g. by using S for ``no checksums'', then all subdirectories inherit that option: no checksums are done.

     You can always override switches that are inherited from parent directories.  There is also a special dollar-sign prefix (described above) you can use to override the normal cascading behavior.

     e.g., In the example below, all the stuff under /var/log won't have checksums done, except all the files under /var/log/archives:

              /var/log            S
              /var/log/archive    s

     Again, the upper case turns the check off, and the lower case turns it back on.

  * list of switches

     The default checks are these: checksum; inode; permissions; number of links; uid; gid; mtime; and ctime.  You can overrule the defaults by specifying all switches for the root directory in the configuration file.

     Here's a table of letters and the corresponding checks/options:

     s
          checksum

     i
          inode

     p
          permissions

     t
          file type

     d
          device type (if file is blk or chr special)

     l
          number of links

     u
          uid

     g
          gid

     z
          file size (redundant if checksums are on)

     a
          access time

     m
          modification time

     c
          time UN*X file information was changed

     r
          reset access time (option)

Human Readable Output
*********************

The human-readable format is intended for quick scanning on a viewer with a large number of columns (like an xterm with maximized width).

Other popular file integrity verification systems split the information between a list of files that have changed at the top of the report and a more detailed section showing the nature of the changes at the bottom of the report.  Instead, integrit provides all the information for each file as it learns it.

Besides saving on runtime memory usage, the big advantage of this approach is that the person reading the output never has to skip to the end of the report to learn the exact nature of a change.

In this output format, messages from integrit have a specific prefix showing what kind of message it is:

  * ``integrit: '' integrit is telling you something

  * ``changed: '' a file has changed somehow

  * ``missing: '' a file in the known database is no longer around  (You will only see missing files reported if you're running update and check at the same time.  Otherwise integrit won't know both necessary facts: the file existed in the past and isn't there now.)

  * ``new: '' a file not in the known database has appeared

The one-letter characters for options and checks (see table of checkset codes) is used in the human-readable output format for reporting corresponding changes.

For example, the switch for checking permissions is p.  If integrit notes that the file permissions have changed, in the output you will see this kind of line:

         changed: /etc/secret   p(640:666)

That means that the permissions (``p'') have changed from 640 to 666. In general, the syntax is as follows:

         changed: filename   x(known:current)

... where x is the one-letter symbol showing what's changed (see list of switches), "known" is the value from the known database, and "current" is the state of the file that integrit observed at runtime.

exception:

  * Symlinks have sym where the octal permissions (which would always be ``777'') would be.

You can skip the preamble in the human-readable report by lowering the verbosity level with the ``-q'' command-line option.

Exit Status
***********

Since version three, integrit's exit status indicates whether or not it found changes.

0

     When integrit returns zero to the process that started integrit, it means that no changes were detected.  (Unless you are doing a check, no changes will be detected.)

1

     An exit status of one means that changes were detected but no errors were encountered.  (An error is a failure condition that prevents integrit from doing its job.)

2

     Two signifies that an error occured, and integrit was not able to do its job.  When stop_on_err is ``0'' and a check is performed, an exit status of two means that some errors were encountered during the scan, but no changes could be found.

3

     Both errors and changes were found.

Auxiliary Tools
***************

The integrit source distribution comes with two standalone tools.  You do not need to be familiar with these tools in order to use integrit, but I personally find them to be very convenient once in a while.

The tools are i-viewdb and i-ls.

     [file i-viewdb.texi not included]
     [file i-ls.texi not included]

     [file faq.texi not included]

Resources
*********

To get the latest integrit, check the integrit homepage:

         http://integrit.sourceforge.net/

There are many resources at integrit's project page on sourceforge, including mailing lists and a web-interface for the source in CVS.

         http://sourceforge.net/projects/integrit

     [file copying.texi not included]