Configuration — Basic

The configuration file for samhain is named samhainrc by default. Also by default, it is placed in /etc. (Name and location is configurable at compile time). The distribution package comes with a commented sample configuration file. The layout of the configuration file is described in more details in the section called General in the appendix called List of configuration file options.

Definitions

Events (e.g. unauthorized modifications of files monitored by samhain) will generate messages of some severity. These messages will be logged to all logging facilities, whose threshold is equal to, or lower than, the severity of the message.

Severity levels

The following severity levels are defined:

LevelSignificance
noneNot logged.
debugDebugging-level messages.
infoInformational message.
noticeNormal conditions.
warnWarning conditions.
markTimestamps.
errError conditions.
critCritical conditions.
alertProgram startup/normal exit, or fatal error, causing abnormal program termination.
inetIncoming messages from clients (server only).

Most events (e.g. timestamps, internal errors, program startup/exit) have fixed severities. The following events have configurable severities:

  • policy violations (for monitored files)

  • access errors for files

  • access errors for directories

  • obscure file names (with non-printable characters) and/or invalid UIDs/GIDs (no such user/group)

  • login/logout events (if samhain is configured to monitor them)

Severity levels for events (see the section called Severity levels>) are set in the EventSeverity and (for login/logout events) the Utmp sections of the configuration file.

In the configuration file, these can be set as follows:

  [EventSeverity]  
  #  
  # these are policies (see the section called Monitoring policies in the chapter called Configuration — samhain, the file monitor>) 
  # 
  SeverityReadOnly=crit 
  SeverityLogFiles=crit
  SeverityGrowingLogs=warn 
  SeverityIgnoreNone=crit 
  SeverityIgnoreAll=info 
  #  
  # these are access errors 
  # 
  SeverityFiles=err 
  SeverityDirs=err 
  #  
  # these are obscure file names 
  # and/or invalid UIDs/GIDs (no such user/group) 
  # 
  SeverityNames=info 
  #  
  # This is the section for login/logout monitoring 
  # 
  [Utmp]  
  SeverityLogin=notice
  SeverityLogout=notice 
  # multiple logins by same user 
  SeverityLoginMulti=err 

Classes

Events of related type are grouped into classes. For each logging facility, it is possible to restrict logging to a subset of these classes (see the section called Thresholds — Activating logging facilities>). The available classes are:

ClassSignificance
AUDSystem calls.
RUNNormal run messages (e.g. startup, exit, ...)
STAMPTimestamps and alike.
FILMessages related to file integrity checking.
TCPMessages from the client/server subsystem.
PANICFatal errors, leading to program termination.
ERRError messages (general).
ENETError messages (network).
EINPUTError messages (input, e.g. configuration file).

Logging facilities

samhain supports the following facilities for logging:

  • e-mailsamhain uses built-in SMTP code, rather than an external mailer program. E-mails are signed to prevent forging.

  • syslog — The system logging utility.

  • console — If running as daemon, /dev/console is used, otherwise stderr. /dev/console can be replaced by other devices, including a FIFO.

  • log file — Entries are signed to provide tamper-resistance.

  • log serversamhain uses TCP/IP with strong authentication and signed and encrypted messages.

  • externalsamhain can be configured to invoke external programs for logging and/or taking some action upon certain conditions.

  • SQL db — Currently samhain only supports mysql and postgresql.

Each of these logging facilities has to be activated by setting an appropriate threshold on the messages to be logged by this facility.

NoteNOTE
 

In addition, some of these facilities require proper settings in the configuration file (see next sections).

Thresholds — Activating logging facilities

Messages are only logged to a log facility if their severity is at least as high as the threshold of that facility. Thresholds can be specified individually for each facility. A threshold of none switches off the respective facility.

Thresholds are set in the Log section of the configuration file. For each threshold option FacilitySeverity there is also a corresponding option FacilityClass to limit that facility to messages within a given set of class. The argument must be a list of valid message classes, separated by space or comma.

System calls: certain system calls (execve, utime, unlink, dup (+ dup2), chdir, open, kill, exit (+ _exit), fork, setuid, setgid, pipe) can be logged (only to console and syslog). You can determine the set of system calls to log via the option LogCalls=call1, call2, .... By default, this is off (nothing is logged). The priority is notice, and the class is AUD.

Example:

  [Log]  
  #  
  # Threshold for E-mails (none = switched off)
  # 
  MailSeverity=none  
  #  
  # Threshold for log file 
  # 
  LogSeverity=err} 
  LogClass=RUN FIL STAMP 
  #  
  # Threshold for console 
  # 
  PrintSeverity=info
  #  
  # Threshold for syslog (none = switched off)
  # 
  SyslogSeverity=none 
  #  
  # Threshold for forwarding to the log server
  # 
  ExportSeverity=crit 
  #  
  # Threshold for invoking an external program
  # 
  ExternalSeverity=crit
  #  
  # Threshold for logging to a SQL database
  # 
  DatabaseSeverity=err
  #  
  # System calls to log
  # 
  LogCalls=open, kill