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.