Provided by: samhain_3.1.0-7build1_amd64 
EMAIL
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.
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)