Provided by: samhain_3.1.0-5ubuntu1_amd64 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 (©) 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)