SAMHAIN(8)

💖 SAMHAIN(8) 💖 — the Samhain manual, but make it iconic

okay bestie, sit down, hydrate, because we're doing the SAMHAIN(8) page and it's a whole journey. this is the Samhain manual, and it's about checking your file integrity like the paranoid queen you were always meant to be. let's go 🦋

---

🌸 NAME 🌸

samhain — check file integrity 💅

no cap, that's the whole vibe. it checks whether your files are still your files and not, like, someone else's chaos. ✨

---

🎀 SYNOPSIS 🎀

okay so this is the part where it looks scary, but it's just the group chat of every possible way to run this thing. breathe. we're going through all of them, no skipping, because I love you and I want you to have the receipts. 🫶

✨ INITIALIZING, UPDATING, AND CHECKING ✨

the three moods of samhain, honestly — birth, growth, and vibe check:

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]

yes bestie, that third one really does say DEPTH,--recursion=DEPTH with a comma. I'm not fixing it. it's canon. 💀

and then the database besties:

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

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

🦋 LISTING THE DATABASE 🦋

when you just wanna look at the database, respectfully:

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

💜 VERIFYING AN AUDIT TRAIL 💜

for checking the receipts of what went down:

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

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

⭐ MISCELLANEOUS ⭐

the little grab-bag section, iconic behaviour honestly:

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 👑

plot twist, there's a second program and it's called yule, and she's the server:

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

🌈 SERVER MISCELLANEOUS 🌈

and yule has her own little extras:

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

yule [-G | --gen-password]

🎀 LOG OPTIONS 🎀

the log options, a.k.a. the "how loud do you want me to be" knobs. every single one, present and accounted for:

[-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 ⚠️

okay this one matters, so listen up bestie:

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

fr fr — this page is the vibe, the user manual is the truth. don't come for me if the man page is serving slightly outdated info, I'm just the messenger. 😭

---

and that's only part one, babes — there's so much more coming, so don't go anywhere 💅✨

💖 DESCRIPTION 💖

okay so bestie, samhain is a file integrity / intrusion detection system, and it works both for a single host and for whole networks. it's got two parts: a monitoring application (samhain) that runs on each individual host, plus — if you want it — a central log server called yule. right now it can monitor the integrity of files/directories, and (optionally) it can also check for kernel rootkits (Linux and FreeBSD only, no cap), search the disk for SUID/SGID, and watch for login/logout events. it's giving very much "i see everything" energy. 👀✨

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 (which is /dev/console if it's run as a daemon). it can run as a daemon, and it can use a time server instead of the host's system clock. most of the functionality is defined by a configuration file that gets 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. periodt.

🌸 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's totally ok to append to, like, 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, bestie, this is important). 🫶

• -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. it literally never stops. iconic. 🔥
• -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. no matching build, no vibe, no verification. 😭

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. so convenient bestie. 💌

• -j, --just-list — just list the logfile, do not verify it. this option must come first. it's 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. so responsible of it. ✨

• -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 you 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). big brain move, fr fr. 🧠
• 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. so don't come for it later, bestie, it's gone. 🫶

📜 LOG FILE 📜

okay bestie, every single entry in the log file looks like this, no exceptions:

Severity : [Timestamp] Message

and the timestamp? it can totally come from a time server instead of your system clock, if samhain was compiled with support for that. slay.

then — and this is the iconic part — each entry is followed by a signature, computed as Hash(Entry Key_N), and Key_N is computed as Hash(Key_N-1). it's giving hash chain royalty. so basically, only if you know the first signature key in this chain can you verify the integrity of the log file. that first key is autogenerated and e-mailed to the designated recipient. periodt. 🔐

the default name of the log file is samhain_log. and to stop multiple instances of samhain from writing to the same log file (chaos, we don't do that), the log file is locked by creating a lock file, which is normally deleted when the program terminates. default name of the lock file is samhain.lock.

if samhain gets 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. it heals itself, main character energy fr.

---

📧 EMAIL 📧

e-mails are sent (using built-in SMTP code, we don't need no external anything) to one recipient only. the subject line contains the timestamp and hostname, which are repeated in the message body. yes, twice. consistency queen 💅

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 ... 👀 like, that's on you bestie.

---

🤝 CLIENT/SERVER USAGE 🤝

so you wanna monitor several machines and collect data with 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. very spy-movie of them ✨

this protocol requires a password on the client side, and a verifier on the server side that is computed from the password.

to register a client, simply do the following:

1. 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.
2. 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.
3. 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. bye felicia 💀

---

🥷 STEALTH 🥷

samhain may be compiled with support for a stealth mode of operation, meaning 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. no cap, manage your expectations.

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

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. yes, that's on you. own it, bestie.

---

🔒 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). it's strict. it's picky. it's protecting you. 🫶

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). noted. 📝

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. 😭 scary!!

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. not me giving you actual chaos-based entropy advice but here we are.

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. so like... don't let that happen bestie 😬

---

📂 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. the more deets the better, we love a thorough bug report 💖

---

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

---

and that's the whole page bestie, we made it 🎀 this was the SAMHAIN(8) manual page, dated 26 June 2015 — go forth and audit your filesystem, you absolute icon 👑✨