bionic (8) samhain.8.gz

Provided by: samhain_4.1.4-2build1_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]

       samhain [ -p threshold ] { --verify-database=database }

       samhain [ -p threshold ] { --create-database=file-list }

   LISTING THE DATABASE
       samhain [-a | --full-detail] [--delimited] [--binary] [--list-filter=file] -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.

       [-i|--interactive]
              Run update in interactive mode.

       [--listfile=PATH]
              Run the update with a list of 'good' filepaths given in file (one path per line).

       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.

       samhain [ -p threshold ] --verify-database=database

       Check  the  filesystem  against the database given as argument, and exit with an appropriate exit status.
       The configuration file will not be read.

       samhain [ -p threshold ] --create-database=file-list

       Initialize a database from the given file list.  The configuration file will not be read. The policy used
       will  be  ReadOnly.   File content will be stored for a file if its path in the list is preceded with a +
       sign.

   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.

       [--binary]
              List  data  in the binary format of the database, thus writing another database.  Must precede the
              -d option.

       [--list-filter=file]
              Filter the output of the database listing by a list of files given in a text file.  Together  with
              --binary this allows to write a partial database. 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.

                                                  26 June 2015                                        SAMHAIN(8)