Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
SAMHAIN(8)			Samhain	manual			    SAMHAIN(8)

       samhain - check file integrity

       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 | --fore-
       ground] [--forever] [-r DEPTH,--recursion=DEPTH]	[log-options]

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

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

       samhain [-a  |  --full-detail]  [--delimited]  [--binary]  [--list-fil-
       ter=file] -d file| --list-database=file

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

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

       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

       yule  [-q | --qualified]	[ --chroot=chrootdir] [-D | --daemon | --fore-
       ground] [log-options]

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

       yule [-G	| --gen-password]

       [-s  threshold  |  --set-syslog-severity=threshold]  [-l	 threshold   |
       --set-log-severity=threshold]   [-m   threshold	 |   --set-mail-sever-
       ity=threshold] [-e  threshold  |	 --set-export-severity=threshold]  [-p
       threshold  |  --set-print-severity=threshold] [-x threshold | --set-ex-
       ternal-severity=threshold]   [	--set-prelude-severity=threshold]    [
       --set-database-severity=threshold]  [  --enable-trace]  [  --trace-log-

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

       samhain	is a file integrity / intrusion	detection system both for sin-
       gle 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 configura-
       tion file.

       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	signa-
       ture database.

	      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.

	      Run  as  daemon.	File  checks are performed as specified	by the
	      timing options in	the configuration file.	Updates	are saved  af-
	      ter each file check.

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

	      If not running as	daemon,	do not exit after  finishing  the  up-
	      date,  but  loop	forever, and perform checks with corresponding
	      database updates according to the	timing options in the configu-
	      ration file.

	      Run update in interactive	mode.

	      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.

	      Run  as  daemon.	File  checks are performed as specified	by the
	      timing options in	the configuration file.

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

	      If not running as	daemon,	do not exit after finishing the	check,
	      but loop forever,	and perform checks according to	the timing op-
	      tions 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

       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.

       samhain	[-a  |	--full-detail]	[--delimited]  -d  file|  --list-data-

       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.

	      List  all	 informations for each file, in	a comma-separated for-
	      mat.  Must precede the -d	option.

	      List data	in the binary format of	the database, thus writing an-
	      other database.  Must precede the	-d option.

	      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  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.

       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-gen-
       erated 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 ob-
	      fuscated logfile,	if samhain is compiled with  the  stealth  op-

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

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

       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	corre-
       sponding	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  op-

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

       See the section "SECURITY" below.

       yule  [-q | --qualified]	[ --chroot=chrootdir] [-D | --daemon | --fore-
       ground] [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

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

	      Run in the foreground.

       yule [-G	| --gen-password]

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

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

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

       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 thresh-
	      old  will	 be  logged.  Time stamps have the priority warn, sys-
	      tem-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 the threshold	for logging events to the Prelude IDS.

	      Set the threshold	for logging events to the MySQL/PostgreSQL/Or-
	      acle database.

	      Switch on/off maximum verbosity for console output.

	      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.


	      Terminate	after processing all pending requests from clients.

	      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.

	      Force  a	file check (only client/standalone, and	only in	daemon

       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
       samhain will check the signature, if compiled with support for that.

       At  startup samhain will	compute	the checksum of	the database, and ver-
       ify 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.

       Each entry in the log file has the format Severity :  [Timestamp]  Mes-
       sage,  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 ...

       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/re-
       sponse  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 com-
       piled-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 hexadec-
       imal  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	 veri-
       fier,  and  outputs  a default configuration file entry to register the
       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	quali-
       fied) hostname of the machine on	which the client will run.  Don't for-
       get 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.

       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 un-
       compressed 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

       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  exe-
       cutable(s)  to unsuspicious names, and choosing (at compile time) like-
       wise unsuspicious names for config  file,  database,  and  log  (+lock)

       For security reasons, samhain will not write log	or data	files in a di-
       rectory,	remove the lock	file, or read the configuration	file,  if  any
       element in the path is owned or writeable by an untrusted user (includ-
       ing 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 distri-
       bution),	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 partic-
       ular 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  de-
       scribed here.

       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. Do-
       ing some	random things (performing rain dances, spilling	coffee,	 hunt-
       ing  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  do-
       main in the configuration file.

       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.



       Rainer Wichmann (

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

       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.

				 26 June 2015			    SAMHAIN(8)


Want to link to this manual page? Use this URL:

home | help