Provided by: samhain_2.6.2-2_i386 bug

NAME

       samhain - check file integrity

SYNOPSIS

   INITIALIZING, UPDATING, AND CHECKING
       samhain   {  -t  init|--set-checksum-test=init  }  [--init2stdout]  [-r
       DEPTH|--recursion=DEPTH] [log-options]

       samhain { -t  update|--set-checksum-test=update  }  [-D  |  --daemon  |
       --foreground] [--forever] [-r DEPTH|--recursion=DEPTH] [log-options]

       samhain  {  -t  check|--set-checksum-test=check  }  [-D  |  --daemon  |
       --foreground] [--forever] [-r DEPTH,--recursion=DEPTH] [log-options]

   LISTING THE DATABASE
       samhain    [-a    |    --full-detail]    [--delimited]     -d     file|
       --list-database=file

   VERIFYING AN AUDIT TRAIL
       samhain [-j | --just-list] -L logfile| --verify-log=logfile

       samhain -M mailbox| --verify-mail=mailbox

   MISCELLANEOUS
       samhain --server-port=portnumber

       samhain -H string | --hash-string=string

       samhain -c | --copyright

       samhain -v | --version

       samhain -h | --help

       samhain -V key@/path/to/executable | --add-key=key@/path/to/executable

   SERVER STARTUP
       yule  [-q  |  --qualified]  [  --chroot=chrootdir]  [-D  |  --daemon  |
       --foreground] [log-options]

   SERVER MISCELLANEOUS
       yule [-P password | --password=password]

       yule [-G | --gen-password]

   LOG OPTIONS
       [-s  threshold  |  --set-syslog-severity=threshold]  [-l  threshold   |
       --set-log-severity=threshold]          [-m          threshold         |
       --set-mail-severity=threshold]         [-e         threshold          |
       --set-export-severity=threshold]         [-p         threshold        |
       --set-print-severity=threshold]         [-x         threshold         |
       --set-external-severity=threshold]  [ --set-prelude-severity=threshold]
       [    --set-database-severity=threshold]     [     --enable-trace]     [
       --trace-logfile=tracefile]

WARNING

       The  information  in  this  man  page  is  not  always up to date.  The
       authoritative documentation is the user manual.

DESCRIPTION

       samhain is a file integrity  /  intrusion  detection  system  both  for
       single  hosts  and  networks.   It consists of a monitoring application
       (samhain) running on individual hosts, and (optionally) a  central  log
       server  (yule).   Currently,  samhain  can  monitor  the  integrity  of
       files/directories, and (optionally)  also  check  for  kernel  rootkits
       (Linux  and FreeBSD only), search the disk for SUID/SGID, and watch for
       login/logout events.

       samhain/yule can log by email, to a tamper-resistant, signed log  file,
       to  syslog,  to the Prelude IDS, to a MySQL/PostgreSQL/Oracle database,
       and/or to stdout (/dev/console if run as daemon).  samhain/yule can run
       as  a  daemon,  and  can use a time server instead of the host's system
       clock. Most of the functionality is defined  by  a  configuration  file
       that is read at startup.

       Most  options  of these usually would be set in the configuration file.
       Options  given  on  the  command  line  will  override  those  in   the
       configuration file.

   OPTIONS FOR INITIALIZING, UPDATING, AND CHECKING
       samhain -t init, --set-checksum-test=init [options]

       Initialize the database of file signatures. The path to the database is
       compiled in, and initializing will append to the  respective  file  (or
       create  it,  if  it does not exist).  It is ok to append to e.g. a JPEG
       image, but it is an  error  to  append  to  an  already  existing  file
       signature database.

       [--init2stdout]
              Write the database to stdout.

       [-r DEPTH|--recursion=DEPTH]
              Set the (global) recursion depth.

       samhain -t update, --set-checksum-test=update [options]

       Update  the  database  of  file signatures. The path to the database is
       compiled in, and updating will overwrite the  database,  starting  from
       the  start  of the database (which may not be identical to the start of
       the file - see above).

       [-r DEPTH|--recursion=DEPTH]
              Set the (global) recursion depth.

       [-D|--daemon]
              Run as daemon. File checks are performed  as  specified  by  the
              timing  options  in  the  configuration  file. Updates are saved
              after each file check.

       [--foreground]
              Run in the foreground. This will cause samhain to exit after the
              update, unless the option --forever is used.

       [--forever]
              If  not  running  as  daemon,  do  not  exit after finishing the
              update, but loop forever, and perform checks with  corresponding
              database   updates  according  to  the  timing  options  in  the
              configuration file.

       samhain -t check, --set-checksum-test=check [options]

       Check the filesystem against the database of file signatures.  The path
       to the database is compiled in.

       [-r DEPTH|--recursion=DEPTH]
              Set the (global) recursion depth.

       [-D|--daemon]
              Run  as  daemon.  File  checks are performed as specified by the
              timing options in the configuration file.

       [--foreground]
              Run in the foreground. This will cause samhain to exit after the
              file check, unless the option --forever is used.

       [--forever]
              If not running as daemon, do not exit after finishing the check,
              but loop forever, and perform checks  according  to  the  timing
              options in the configuration file.

   OPTIONS FOR LISTING THE DATABASE
       samhain     [-a     |    --full-detail]    [--delimited]    -d    file|
       --list-database=file

       List the entries in the file signature database in a ls -l like format.

       [-a | --full-detail]
              List all informations for each file, not only  those  you  would
              get with ls -l. Must precede the -d option.

       [--delimited]
              List  all  informations  for  each  file,  in  a comma-separated
              format.  Must precede the -d option.

       [--list-file=file]
              List the literal content of the given  file  as  stored  in  the
              database.   Content is not stored by default, must be enabled in
              the runtime configuration file. Must precede the -d option.

   OPTIONS TO VERIFY AN AUDIT TRAIL
       These options will only work, if the executable used for verifying  the
       audit  trail  is compiled with the same --enable-base=... option as the
       executable of the reporting process.

       samhain [-j | --just-list] -L logfile| --verify-log=logfile

       Verify  the  integrity  of  a  signed  logfile.  The  signing  key   is
       auto-generated on startup, and sent by email.  samhain will ask for the
       key. Instead of entering the key, you can also enter the  path  to  the
       mailbox holding the respective email message.

       [-j | --just-list]
              Just  list  the logfile, do not verify it. This option must come
              first.  It is mainly intended for  listing  the  content  of  an
              obfuscated  logfile,  if  samhain  is  compiled with the stealth
              option.

              samhain -M mailbox| --verify-mail=mailbox

              Verify the integrity of the  email  reports  from  samhain.  All
              reports must be in the same file.

   MISCELLANEOUS OPTIONS
       samhain --server-port=portnumber

       Choose the port on the server host to which the client will connect.

       samhain -H string | --hash-string=string

       Compute  the TIGER192 checksum of a string. If the string starts with a
       '/',  it  is  considered  as  a  pathname,  and  the  checksum  of  the
       corresponding file will be computed.

       samhain -c | --copyright

       Print the copyright statement.

       samhain -v | --version

       Show version and compiled-in options.

       samhain -h | --help

       Print   supported   command  line  options  (depending  on  compilation
       options).

       samhain -V key@/path/to/executable | --add-key=key@/path/to/executable

       See the section "SECURITY" below.

   SERVER STARTUP OPTIONS
       yule  [-q  |  --qualified]  [  --chroot=chrootdir]  [-D  |  --daemon  |
       --foreground] [log-options]

       Start  the  server,  which  is  named yule by default. If the server is
       started with superuser privileges, it will drop them after startup.

       [-q | --qualified]
              Log client hostnames with fully qualified path. The  default  is
              to log only the leftmost domain label (i.e. the hostname).

       [      --chroot=chrootdir]   Chroot   to  the  listed  directory  after
              startup.

       [-D | --daemon]
              Run as daemon.

       [--foreground]
              Run in the foreground.

   MISCELLANEOUS SERVER OPTIONS
       yule [-G | --gen-password]

       Generate a random 8-byte password  and  print  it  out  in  hexadecimal
       notation.

       yule [-P password | --password=password]

       Use the given password and generate an entry suitable for the [Clients]
       section of the configuration file.

   LOGGING OPTIONS
       Depending on the compilation options, some logging facilities  may  not
       be available in your executable.

       -s threshold, --set-syslog-severity=threshold
              Set  the  threshold for logging events via syslogd(8).  Possible
              values are debug, info, notice, warn, mark,  err,  crit,  alert,
              and  none.   By  default,  everything  equal  to  and  above the
              threshold will be logged.  Time stamps have the  priority  warn,
              system-level   errors  have  the  priority  err,  and  important
              start-up messages the priority alert.  The signature key for the
              log file will never be logged to syslog or the log file itself.

       -l threshold, --set-log-severity=threshold
              Set the threshold for logging events to the log file.

       -m threshold, --set-mail-severity=threshold
              Set the threshold for logging events via e-mail.

       -e threshold, --set-export-severity=threshold
              Set the threshold for forwarding events via TCP to a log server.

       -x threshold, --set-extern-severity=threshold
              Set  the threshold for calling external logging programs/scripts
              (if any are defined in the configuration file).

       -p threshold, --set-print-severity=threshold
              Set the threshold for logging events to stdout.  If samhain runs
              as a daemon, this is redirected to /dev/console.

       --set-prelude-severity=threshold
              Set the threshold for logging events to the Prelude IDS.

       --set-database-severity=threshold
              Set    the    threshold    for    logging    events    to    the
              MySQL/PostgreSQL/Oracle database.

SIGNALS

       SIGUSR1
              Switch on/off maximum verbosity for console output.

       SIGUSR2
              Suspend/continue the process, and (on suspend) send a message to
              the  server.  This  message has the same priority as timestamps.
              This signal allows to run samhain -t init -e none on the  client
              to  regenerate  the database, with download of the configuration
              file from the server, while the daemon  is  suspended  (normally
              you  would get errors because of concurrent access to the server
              by two processes from the same host).

       SIGHUP Reread the configuration file.

       SIGTERM
              Terminate.

       SIGQUIT
              Terminate after processing all pending requests from clients.

       SIGABRT
              Unlock the log file, pause  for  three  seconds,  then  proceed,
              eventually  re-locking  the  log file and starting a fresh audit
              trail on next access.

       SIGTTOU
              Force a file check (only client/standalone, and only  in  daemon
              mode).

DATABASE

       The database (default name samhain_file) is a binary file, which can be
       created or updated using the -t init or the -t update option.   If  you
       use  -t  init, you need to remove the old database first, otherwise the
       new version will be appended to the old one.  The file  may  be  (clear
       text) signed by PGP/GnuPG.
       It  is  recommended  to  use  GnuPG with the options gpg -a --clearsign
       --not-dash-escaped
       samhain will check the signature, if compiled with support for that.

       At startup samhain will compute  the  checksum  of  the  database,  and
       verify  it for each further access. This checksum is not stored on disk
       (i.e. is lost after program termination), as there is no secure way  to
       store it.

LOG FILE

       Each  entry  in  the  log  file  has  the format Severity : [Timestamp]
       Message, where the timestamp may be obtained from a time server  rather
       than  from  the system clock, if samhain has been compiled with support
       for this.  Each entry is followed by a signature, which is computed  as
       Hash(Entry  Key_N),  and  Key_N is computed as Hash(Key_N-1), i.e. only
       knowledge of the first signature key in this chain allows to verify the
       integrity of the log file. This first key is autogenerated and e-mailed
       to the designated recipient.

       The default name of the log file is samhain_log.  To  prevent  multiple
       instances of samhain from writing to the same log file, the log file is
       locked by creating a lock file, which is normally  deleted  at  program
       termination.   The  default  name of the lock file is samhain.lock.  If
       samhain is terminated abnormally, i.e. with kill -9, a stale lock  file
       might  remain,  but  usually samhain will be able to recognize that and
       remove the stale lock file on the next startup.

EMAIL

       E-mails are sent (using built-in SMTP code) to one recipient only.  The
       subject line contains timestamp and hostname, which are repeated in the
       message body.  The body of the mail contains a line  with  a  signature
       similar  to  that in the log file, computed from the message and a key.
       The key is iterated by a hash chain, and the initial key is revealed in
       the  first  email sent.  Obviously, you have to believe that this first
       e-mail is authentical ...

CLIENT/SERVER USAGE

       To monitor several machines, and  collecting  data  by  a  central  log
       server, samhain may be compiled as a client/server application. The log
       server (yule) will accept connection requests from  registered  clients
       only.   With   each   client,   the  server  will  first  engage  in  a
       challenge/response  protocol  for  authentication  of  the  client  and
       establishing a session key.

       This protocol requires on the client side a password, and on the server
       side a verifier that is computed from the password.

       To register a client, simply do the following:
       First, with the included  utility  program  samhain_setpwd  re-set  the
       compiled-in default password of the client executable to your preferred
       value (with no option, a short usage help is printed).   To  allow  for
       non-printable  chars,  the  new  value  must  be  given  as  a 16-digit
       hexadecimal string (only 0123456789ABCDEF in string), corresponding  to
       an 8-byte password.
       Second, after re-setting the password in the client executable, you can
       use the server's convenience function yule -P password that  will  take
       as  input  the  (16-digit  hex)  password,  compute  the  corresponding
       verifier, and outputs a default configuration file  entry  to  register
       the client.
       Third,  in  the  configuration file for the server, under the [Clients]
       section,  enter  the  suggested  registration   entry   of   the   form
       Client=hostname@salt@verifier,   where  hostname  must  be  the  (fully
       qualified) hostname of the machine on which the client will run.  Don't
       forget to reload the server configuration thereafter.

       If  a  connection attempt is made, the server will lookup the entry for
       the connecting host, and use the corresponding value for  the  verifier
       to  engage  in the session key exchange. Failure to verify the client's
       response(s) will result in aborting the connection.

STEALTH

       samhain may be compiled with support for a stealth mode  of  operation,
       meaning  that  the  program can be run without any obvious trace of its
       presence on disk. The supplied facilities are simple -  they  are  more
       sophisticated than just running the program under a different name, and
       might thwart efforts using 'standard' Unix commands, but they will  not
       resist a search using dedicated utilities.

       In  this  mode,  the runtime executable will hold no printable strings,
       and the configuration file is expected to be  a  postscript  file  with
       uncompressed  image  data, wherein the configuration data are hidden by
       steganography.  To create such a file from an existing image,  you  may
       use  e.g.   the program convert(1), which is part of the ImageMagick(1)
       package, such as: convert +compress ima.jpg ima.ps.

       To hide/extract the configuration data within/from the postscript file,
       a  utility program samhain_stealth is provided.  Use it without options
       to get help.

       Database and log file may be e.g. existing image files, to  which  data
       are appended, xor'ed with some constant to mask them as binary data.

       The   user  is  responsible  by  herself  for  re-naming  the  compiled
       executable(s) to unsuspicious names, and  choosing  (at  compile  time)
       likewise  unsuspicious names for config file, database, and log (+lock)
       file.

SECURITY

       For security reasons, samhain will not write log or  data  files  in  a
       directory, remove the lock file, or read the configuration file, if any
       element in the  path  is  owned  or  writeable  by  an  untrusted  user
       (including group-writeable files with untrusted users in the group, and
       world-writeable files).
       root and the effective user are always trusted. You can add more  users
       in the configuration file.

       Using  a  numerical  host  address in the e-mail address is more secure
       than using the hostname (does not require DNS lookup).

       If you use  a  precompiled  samhain  executable  (e.g.  from  a  binary
       distribution),  in principle a prospective intruder could easily obtain
       a copy of the executable and analyze it in advance.  This  will  enable
       her/him to generate fake audit trails and/or generate a trojan for this
       particular binary distribution.
       For this reason, it is possible for the user to add more  key  material
       into the binary executable. This is done with the command:

       samhain --add-key=key@/path/to/executable

       This  will  read  the  file /path/to/executable, add the key key, which
       should not contain a '@' (because it has a special meaning,  separating
       key  from  path), overwrite any key previously set by this command, and
       write the new binary to the location /path/to/executable.out (i.e. with
       .out  appended). You should then copy the new binary to the location of
       the old one (i.e. overwrite the old one).

       Note that using a precompiled samhain executable from a binary  package
       distribution  is  not  recommended  unless  you  add in key material as
       described here.

NOTES

       For initializing the key(s), /dev/random is used, if available. This is
       a  device supplying cryptographically strong (non-deterministic) random
       noise. Because it is slow, samhain might appear  to  hang  at  startup.
       Doing  some  random  things  (performing  rain dances, spilling coffee,
       hunting  the  mouse)  might  speed  up  things.  If  you  do  not  have
       /dev/random,  lots  of  statistics  from vmstat(8) and the like will be
       pooled and mixed by a hash function.

       Some hosts might check whether the sender of the mail  is  valid.   Use
       only login names for the sender.
       For  sending  mails,  you  may  need to set a relay host for the sender
       domain in the configuration file.

BUGS

       Whoever has the original signature key may change the log file and send
       fake e-mails. The signature keys are e-mailed at program startup with a
       one-time pad encryption.  This should be safe against  an  eavesdropper
       on the network, but not against someone with read access to the binary,
       if she has caught the e-mail.

FILES

       /etc/samhainrc
       /usr/local/man/man8/samhain.8
       /usr/local/man/man5/samhainrc.5
       /var/log/samhain_log
       /var/lib/samhain/samhain_file
       /var/lib/samhain/samhain.html
       /var/run/samhain.pid

SEE ALSO

       samhainrc(5)

AUTHOR

       Rainer Wichmann (http://la-samhna.de)

BUG REPORTS

       If  you  find  a  bug  in  samhain,  please  send  electronic  mail  to
       support@la-samhna.de.   Please  include  your  operating system and its
       revision, the version of samhain, what C compiler you used  to  compile
       it,  your  'configure'  options,  and  any  information  that  you deem
       helpful.

COPYING PERMISSIONS

       Copyright ((C)) 1999, 2004 Rainer Wichmann

       Permission is granted to make and distribute verbatim  copies  of  this
       manual  page  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  page  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.

                                07 August 2004                      SAMHAIN(8)