$Id: README,v 1.3 2003/03/19 19:26:40 jay Exp $
Gatekeeper v0.92
Jerry Bolton, Jr.
creel@rootaction.net

Gatekeeper is a system integrity checker.  Like most system integrity 
checkers, it takes a while to run and needs some configuration to 
be most effective.  Here's a list of key features:

  o automatically rotates fingerprints, thereby giving reports only 
    on what has changed since the last time the report was run
  o automatically stores past reports
  o is capable of understanding virtually any file in the filesystem,
    with the exception of some files in /proc
  o Gatekeeper checks files for changes.  It also checks for unowned 
    files (no uid, no gid) and setuid/setgid files.  
  o The Keymaster sentinel script can track multiple machines 
    without complicated configuration.  Just add another cron entry.

What sets Gatekeeper apart from other integrity checkers?

  o Gatekeeper can successfully fingerprint all types of UNIX filesystem
    entries in a sane manner.  In other words, it won't try to generate
    a checksum from the contents of your tape drive, instead it will watch
    permissions and major/minor device number changes.
  o Gatekeeper is efficient.  
  o Gatekeeper requires only the installation of two configuration files
    and two cron entries.
  o Gatekeeper is free (GPL)

How do I use Gatekeeper?

  0) Gatekeeper has only been tested on Linux and OpenBSD.
  1) Install gatekeeper.sh in /sbin on the system to watch.  Call this
     system the Subject.
  2) Install keymaster.sh in /sbin on the system which collects 
     integrity fingerprints.  Call this system the Sentinel.
  3) Ensure both scripts are mode 755 owned by root.
  4) On the Sentinel, create a new directory for storing fingerprints,
     (I suggest /var/local/integrity)
  5) On the Subject, install /etc/gatekeeper.cf (see below) 
  6) On the Sentinel, install /etc/keymaster.cf (see below)
  7) Run 'time /sbin/gatekeeper.sh' on the target.
  8) enter the command '/sbin/gatekeeper.sh' in your crontab, to run
     "as often as you like."  Do this on the Subject.
  9) enter the command '/sbin/keymaster.sh target user password' in 
     your Sentinel's crontab.  Use the time discovered in step 7 
     to delay this from the run of gatekeeper.  See below if your
     system runs a web server but not an ftp server.
 10) On the Sentinel, run "/sbin/keymaster.sh target user password"
     now.

Note that I recommend creating a noninteractive user account for the 
purpose of retreiving the fingerprints.  Note also that it is best
if the hostname specified to keymaster is the unqualified hostname,
i.e. foo not foo.bar.com.

If your Subject does not run an ftp server, you can invoke keymaster
as below to use wget instead.  

    /sbin/keymaster.sh -w hostname

Note that this requires wget be installed on the Sentinel, and you will
need to create a wrapper script on the Subject which runs gatekeeper,
then copies the files to DocumentRoot/integrity/ and optionally compresses
them with gzip.

Creating gatekeeper.cf:

NOTE: Both CF files require that option names (i.e. "SUM:") be at the
beginning of their lines.

Gatekeeper.cf has only two purposes.  It defines which command is used 
for generating checksums, and which filesystem entries will be ignored.
If you have the horsepower, I recommend using the "md5sum" command, 
which is the default if not specified.

If you wish, specify "SUM:   sum_command" on a line anywhere in the
gatekeeper.cf file.  You can use '#' to make comments.  

There is one other option:  "SPOOL: mail_spool_path" where mail_spool_path
is the path to your mail spool directory.  The default if not specified
is /var/spool/mail.

All other lines are assumed to be (regex) patterns to EXCLUDE.  Gatekeeper
will start from / and descend the entire filesystem.  Creative use
of regex can be used, for example, to watch the permissions on user
directories without watching the files in those directories.  For example:

     ^/home/user/

Will exclude the files of "user" but will not exclude the directory
"/home/user" itself.  This is because gatekeeper uses find(1) to 
generate its initial list.

To exclude a specific file, use:

     ^/path/morepath/file$

Remember to escape periods with a backslash, i.e.:  '/etc/sendmail\.cf'
You can exclude files which appear in multiple directories, for example:

     /\.profile$

Will exclude every users .profile file.  Get creative.  Have fun :) 
One warning:  It is best to ignore /proc altogether because some of
these "files" don't have an end, and gatekeeper can get hung fingerprinting
such files.

Creating keymaster.cf

NOTE: Both CF files require that option names (i.e. "SUM:") be at the
beginning of their lines.

The directory you created in step 4 should be specified, as well 
as the subject of the report e-mail and the e-mail recipients. 
The format is:

   DIRECTORY: /var/local/integrity
   SUBJ: [%h] gatekeeper checks
   MAIL: user@foobar.com

Note that %h is replaced automatically with the name of the host
that is being checked.

That's it :) 




