samhain file integrity scanner | online documentation

Setting up a client/server samhain system

This document aims to explain how to set up a client/server samhain system, where the client (samhain) runs on one machine to be monitored, and sends reports via TCP/IP to a remote server (yule).

Please note: the server (yule) does not perform any filesystem and/or kernel checks. If you want to perform such checks on the log server host, you need to run a samhain client on this host as well.

Client and server are distict applications, and must be built separately. By default, installation names and paths (e.g. the configuration file) are different. Do not blame us if you abuse './configure' options to cause name clashes, if you install both on the same host.

Introduction

Samhain can be compiled for remote logging to a central server via a secure (AES-encrypted, signed, and authenticated) TCP/IP connection.

In addition, both the client configuration file and the file signature database can be stored on the server. The client will then pull them from the server upon startup.

This requires three basic steps:

compile and install server and client,
establish trust between client and server, and
enable remote logging in the client's configuration file.

Compiling

The server - yule

Note: the server can be started with root privileges (e.g. to use a privileged port < 1024), but it will always drop root privileges irrevocably before accepting any connections, and run as a non-root user. This user can be specified explicitely with the configure option --enable-identity=USER. The default is the first existing user out of the list yule, daemon, nobody.


bash$ ./configure --enable-network=server
bash$ make
bash$ make install

The client - samhain

If you just want remote logging:
./configure --enable-network=client --with-logserver=server.example.com
If you want configuration and database files on the server:
./configure --enable-network=client --with-logserver=server.example.com \ --with-config-file=REQ_FROM_SERVER/etc/samhainrc \ --with-data-file=REQ_FROM_SERVER/var/lib/samhain/samhain_file

The path after the keyword REQ_FROM_SERVER has the following meaning:

for the configuration file:
- if initializing, and the connection to the server fails, samhain will fall back on the local file (if given);
- if in check mode, it is ignored. Samhain will abort if the connection to the server fails.
Thus, the local path allows you to initialize the database from a local configuration file before the client is known to the server.
for the database file:
- if initializing, the database is written to the local file;
- if in check mode, the local path is ignored. Samhain will abort if the connection to the server fails.
Thus, init (or update) always requires a local file that must be uploaded to the server thereafter. Note that if you use the Beltane web-based frontend, database updates can be performed on the server without ever running an update on the client.

Establishing trust between client and server

By default, samhain uses the SRP (Secure Remote Password) protocol, with a password that is embedded in the client binary, and a corresponding verifier that is in the server configuration file.

Embedding the password in the client, and register it with the server

To embed the password in the binary, there is a dummy password compiled in as placeholder, and a utility samhain_setpwd is provided that

takes a password as input,
searches the original binary for the correct place (i.e. the placeholder), and
writes a copy of the original binary, with the placeholder replaced by the password. The original is left untouched. The copy cannot be changed to another password anymore.

For convenience, the server has functions to

generate a random password in the correct format:
sh$ yule -G
and generate a corresponding entry for the server configuration file:
sh$ yule -P PASSWORD.
The generated entry has a string 'HOSTNAME' that you should replace with the fully qualified name of the client. This entry must then be placed in the [Clients] section of the yule configuration file (e.g. /etc/yulerc).
Finally, you need to tell yule to reload the configuration (send SIGHUP, or use /etc/init.d/yule reload).

Example


rainer$ ./samhain_setpwd

Usage: samhain_setpwd <filename> <suffix> <new_password>

   This program is a utility that will:
    - search in the binary executable <filename> for samhain's
      compiled-in default password,
    - change it to <new_password>,
    - and output the modified binary to <filename>.<suffix>

   To allow for non-printable chars, <new_password> must be
   a 16-digit hexadecimal number (only 0-9,A-F allowed in input),
   thus corresponding   to an 8-byte password.

   Example: 'samhain_setpwd samhain new 4142434445464748'
   takes the file 'samhain', sets the password to 'ABCDEFGH'
   ('A' = 41 hex, 'B' = 42 hex, ...) and outputs the result
   to 'samhain.new'.

rainer$ yule -G
5B5CDF18CE8D66A3

rainer$ ./samhain_setpwd samhain new 5B5CDF18CE8D66A3
INFO   old password found
INFO   replaced:  f7c312aaaa12c3f7  by:  5b5cdf18ce8d66a3
INFO   finished

rainer$ scp ./samhain.new root@client.example.com:/usr/local/sbin/samhain
samhain              100% |********************************|   592 KB    00:00

rainer$ yule -P 5B5CDF18CE8D66A3
Client=HOSTNAME@8A542F99C3514499@744C3A3EE8323470D9DAD42E2485BD0B138F6B4116E964\
A9991A0B0D221E1AADE5800968804B99B494C39E7B9DD5710D18F1E6703D1DB6D6393295E05DF6A\
6AA8D10BB4A21D7D9DC4901D444500D4EA358C1B44A3E3D44ACEC645F938F790A11AB0D03586143\
977E2BCE3A2D689445AC89134B409E68F34B0DE8BD8242ADD7C0

rainer$ yule -P 5B5CDF18CE8D66A3 | sed s%HOSTNAME%client.example.com% >> /etc/yulerc

rainer$ tail -2 /etc/yulerc
[Clients]
Client=client.example.com@8A542F99C3514499@744C3A3EE8323470D9DAD42E2485BD0B138F
6B4116E964A9991A0B0D221E1AADE5800968804B99B494C39E7B9DD5710D18F1E6703D1DB6D6393
295E05DF6A6AA8D10BB4A21D7D9DC4901D444500D4EA358C1B44A3E3D44ACEC645F938F790A11AB
0D03586143977E2BCE3A2D689445AC89134B409E68F34B0DE8BD8242ADD7C0

rainer$ /etc/init.d/yule reload

Note 1: the verifier Client=client.example.com@..... must be in the [Clients] section of the server configuration file. It is convenient if this is the last section in the config file, because then you can just concatenate the output of yule -P PASSWORD to the configuration file. This allows for better automatisation with a simple script.

Note 2: samhain comes with a deploy system that handles the deployment of clients, including password embedding and server configuration, in a semi-automatic way. This deploy system is tested and used in a production system of more than 50 machines, and described in detail in Chapt. 10 of the MANUAL.

Enabling remote logging

Samhain has multiple independent logging facilities (such as a local logfile, syslog, e-mail, TCP/IP, etc.) that can be used in parallel. You therefore have to specify in the client's configuration file, which logging facility you want to use.

Selecting logging facilities is done by setting appropriate thresholds in the [Log] section of the configuration file: each message with a priority exceeding the threshold will be logged via the respective facility. Setting the threshold to none will disable a facility. For details, refer to Chapt. 4 in the MANUAL.

Example

To enable remote logging to the server for all messages of priority error or higher, use the following directive in the client configuration file:


[Log]
ExportSeverity=err

Databases and config files on the server

The client does not tell the server the path to the requested file - it just requests a config or a database file. It's entirely the responsibility of the server to locate the correct file and send it.

The server has a data directory, which by default would be /var/lib/yule, but depends on your compile options.

Config files and baseline databases for clients must be located in this directory, and they must be named as follows:

Configuration files: rc.client.mydomain.tld or simply rc (this can be used as a catchall file).

Database files: file.client.mydomain.tld or simply file (this can be used as a catchall file).