Samhain | ||
---|---|---|
<<< Previous | Configuration — Basic | Next >>> |
This section discusses some details of the logging facilities offered by samhain Configuring logging facilities (if required) is explained above. Activating logging facilities (by setting an appropriate threshold) is explained in the Section called Thresholds — Activating logging facilities> .
Up to two console devices are supported, both of which may also be named pipes. If running as daemon, samhain will use /dev/console for output, otherwise stdout. On Linux, _PATH_CONSOLE will be used instead of /dev/console, if it is defined in the file /usr/include/paths.h.
You can override this at compile time, or in the configuration file with the SetConsole=device option. Up to two console devices are supported, both of which may also be named pipes (use the SetConsole option twice to set both devices).
samhain will translate its own severities into syslog priorities as follows:
Severity | Syslog priority |
---|---|
debug | LOG_DEBUG |
info | LOG_INFO |
notice | LOG_NOTICE |
warn | LOG_WARNING |
mark | LOG_ERR |
err | LOG_ERR |
crit | LOG_CRIT |
alert | LOG_ALERT |
Messages larger than 960 chars will be split into several messages. By default, samhain will use the identity 'samhain', the syslog facility LOG_AUTHPRIV, and will log its PID (process identification number) in addition to the message.
The syslog facility can be modified via the directive SyslogFacility=command>LOG_xxx in the Misc section of the configuration file.
The subject line contains timestamp and local hostname, which are repeated in the message body. samhain uses its own built-in SMTP code rather than the system mailer, because in case of temporary connection failures, the system mailer (e.g. sendmail) would queue the message on disk, where it may become visible to unauthorized persons.
During temporary connection failures, messages are stored in memory. The maximum number of stored messages is 128. samhain will re-try to mail every hour for at most 48 hours. In conformance with RFC 821, samhain will keep the responsibility for the message delivery until the recipient's mail server has confirmed receipt of the e-mail (except that, as noted above, after 48 hours it will assume a permanent connection failure, i.e. e-mailing will be switched off).
The body of the mail may consist of several messages that were pending on the internal queue (see the Section called Logging facilities>), followed by a signature that is computed from the message and a key. The key is initialized with a random number, and for each e-mail iterated by a hash chain.
The initial key is revealed in the first email sent (obviously, you have to believe that this first e-mail is authentic). This initial key is not transmitted in cleartext, but encrypted with a one-time pad (the Section called Integrity of the executable in the chapter called Security Design>).
The signature is followed by a unique identification string. This is used to identify seperate audit trails (here, a trail is a sequence of e-mails from the same run of samhain), and to enumerate individual e-mails within a trail.
The mail thus looks like:
-----BEGIN MESSAGE----- first message second message ... -----BEGIN SIGNATURE----- signature ID TRAIL_ID:hostname -----END MESSAGE----- |
![]() | Integrity verification |
---|---|
To verify the integrity of an e-mail audit trail, a convenience function is provided: samhain -M /mailbox/file/path The mailbox file may contain multiple and/or overlapping audit trails from different runs of samhain and/or different clients (hosts). |
![]() | CAVEATS |
---|---|
Verification will fail, if the compiled-in key of the verifying executable is different from the one that generated the message(s) (see the Section called Integrity of the executable in the chapter called Security Design>). If you use a pre-compiled executable from some binary distribution, be sure to read the Section called Integrity of the executable in the chapter called Security Design> carefully. |
The log file is named samhain_log by default, and placed into /var/log by default (name and location can be configured at compile time). If samhain has been compiled with the ./configure --enable-xml-log option, it will be written in XML format.
![]() | NOTE |
---|---|
If you have compiled for stealth (the chapter called Additional Features — Stealth>), you won't see much, because if obfuscated, then both a 'normal' and an XML logfile look, well ... obfuscated. Use samhain -jL /path/to/logfile to view the logfile. |
The log file is created if it does not exist, and locked by creating a lock file, which is also used as the PID file (i.e. it holds the PID of the process). By default, the lock/PID file is named samhain.pid and placed in /var/run (name and location can be configured at compile time). Upon normal program termination, the lock file is removed. Stale lock files are removed at startup if there is no process with that PID.
On the log server, it is possible to use separate log files for individual clients. This can be enabled with UseSeparateLogs=yes/no in the Misc section of the server configuration file. No locking will be performed for client files (only one instance of the server can listen on the TCP port, thus there will be no concurrent access).
The directory where the log and the lock/PID file are located must be writeable only by trusted users (see the Section called Trusted users and trusted paths in the chapter called Installation>). This requirement refers to the complete path, i.e. all directories therein. By default, only root and the effective user of the process are trusted.
Audit trails (sequences of messages from individual runs of samhain) in the log file start with a [SOF] marker. Each message is followed by a signature, that is formed by hashing the message with a key.
The first key is generated at random, and sent by e-mail, encrypted with a one-time pad as described in the previous section on e-mail. Further keys are generated by a hash chain (i.e. the key is hashed to generate the next key). Thus, only by knowing the initial key the integrity of the log file can be assured.
The mail with the key looks like:
-----BEGIN MESSAGE----- message -----BEGIN LOGKEY----- Key(48 chars)[timestamp] -----BEGIN SIGNATURE----- signature ID TRAIL_ID:hostname -----END MESSAGE----- |
![]() | Integrity verification |
---|---|
To verify the log file's integrity, a convenience function is provided: samhain -L /log/file/path When encountering the start of an audit trail, you will then be asked for the key (as sent to you by e-mail). You can then: (i) hit return to skip signature verification, (ii) enter the key (without the appended timestamp), or (iii) enter the path to a file that contains the key (e.g. the mail box). If you use option (iii), the path must be an absolute path (starting with a '/', not longer than 48 chars. For each audit trail, the file must contain a two-line block with the -----BEGIN LOGKEY----- line followed by the line (Key(48 chars)[timestamp]) from the mail. Additional lines before/after any such two-line block are ignored (in particular, if you collect all e-mails from samhain in a mailbox file, you can simply specify the path to that mailbox file). |
![]() | CAVEATS |
---|---|
Verification will fail, if the compiled-in key of the verifying executable is different from the one that generated the message(s) (see the Section called Integrity of the executable in the chapter called Security Design>). If you use a pre-compiled executable from some binary distribution, be sure to read the Section called Integrity of the executable in the chapter called Security Design> carefully. |
Configuring samhain for logging to the log server is explained in the Section called Logging facilities> (setting the IP address of the server) and the Section called Thresholds — Activating logging facilities (activating the facility by setting an appropriate threshold).
During temporary connection failures, messages are stored in a FIFO queue in memory. The maximum number of stored messages is 128. After a connection failure, samhain will make the next attempt only after a deadtime that starts with 1 sec and doubles after each unsuccessful attempt (max is 2048 sec). A re-connection attempt is actually only made for the next message after the deadtime -- you should send timestamps (i.e. set the threshold to mark) to ensure re-connection attempts for failed connections.
It is possible to specify two log servers in the client configuration file. The first one will be used by default (primary), and the second one as fallback in case of a connection failure with the primary log server.
![]() | REQUIREMENTS |
---|---|
This facility requires that you use have compiled with the --with-xml-log option to format log messages in XML (also for the client, even if you do SQL logging on the server), and of course with the --with-database=mysql or the --with-database=postgresql option. If you are using the MessageHeader directive in the configuration file for a user-defined message header, make sure that the log messages are still valid XML, and that all the default entities are still present. |
Currently mysql and postgresql are supported. If the header file 'mysql.h' ('libpq-fe.h') is not found during compilation ('mysql.h: No such file or directory'), you can use the option --with-cflags=-I/dir/where/mysql.h/is. If the library libmysqlclient.a (libpq.a) is not found ('/usr/bin/ld: cannot find -lmysqlclient'), you can use the option --with-libs=-L/dir/where/libmysqlclient.a/is.
![]() | NOTE |
---|---|
PostgreSQL may fail with --enable-static. This is a postgresql bug. |
By default, the database server is assumed to be on localhost, the db name is 'samhain', the db table is 'log', and inserting is possible for any user without password. To create the database/table with the required columns, the distribution includes the scripts 'samhain.mysql.init' and 'samhain.postgres.init'. E.g., for PostgreSQL you would setup the database like:
$ su postgres $ createdb samhain $ createuser samhain $ psql -d samhain < samhain.postgres.init $ exit |
… and for MySQL:
mysql -p -u root < samhain.mysql.init mysql -p -u root … edit grant tables mysqladmin -p -u root reload |
![]() | NOTE |
---|---|
The PostgreSQL init script will grant INSERT permission only to a user 'samhain'. Please take note that for PostgreSQL, inserting also requires SELECT and UPDATE permission for the sequence 'log_log_index_seq' (see bottom of init script). The MySQL init script will create the database, but not the user, and will not grant any permissions. |
As with all logging facilities, logging to the SQL database must be enabled in the configuration file:
[Log] DatabaseSeverity=warn |
In the Database section of the configuration file, you can modify the defaults via the following directives:
[Database] SetDBName=db_name SetDBTable=db_table SetDBHost=db_host SetDBUser=db_user SetDBPassword=db_password |
![]() | NOTE |
---|---|
For PostgreSQL, db_host must be a numerical IP address. |
When logging client messages, yule will wrap them into a server <log sev=''RCVT'' tstamp=… > … </log> message. The parser will then create a seperate database entry for this server timestamp. If you don't like this, you can use the option SetDBServerTstamp=false.
The table field 'log_ref' is NULL for client messages, 0 for server messages, and equal to 'log_index' of the client message for the aforementioned server timestamp of a client message.
There is a special (indexed) table field 'log_hash', which is the MD5 checksum of (the concatenation of) any fields registered with AddToDBHash=field. This might allow to find unique rows faster. There is no default set of fields over which the MD5 hash is computed, so by default the hash is equal for all rows.
![]() | TIP |
---|---|
For security, you may want to set up a user/password for insertion into the db. However, as the password is in cleartext in the config file (and the connection to the db server is not encrypted), for remote logging this facility is less secure than samhain's own client/server system (it is recommended to run the db server on the log host and have the log server, i.e. yule, log to the db). |
<<< Previous | Home | Next >>> |
Configuration of logging facilities | Up | Configuration — samhain, the file monitor |