E-mail

Samhain
Prev | Chapter 4. Configuration of logging facilities | Next

# 4.4. E-mail

Items that can/must be configured are:

Recipients address

  SetMailAddress=`username@hostname`

  Up to eight addresses are possible, each one at most 63 characters long, each on a seperate line in the configuration file.

  | Tip
  | it is recommended to use numerical IP addresses instead of host names (to avoid DNS lookups).

Relay host / Mail exchanger

  SetMailRelay=`mail.some_domain.com`

  You may need this option because some sites don't allow outbound e-mail connections from any arbitrary host. If the recipient is offsite, and your site uses a mail relay host to route outbound e-mails, you need to specify the relay host.

Maximum interval

  SetMailTime=`86400`

  You may want to set a maximum interval between any two consecutive e-mails, to be sure that samhain is still 'alive'.

Maximum pending

  SetMailNum=`10`

  Messages can be queued to send several messages in one e-mail. You may want to set the the maximum number of messages to queue. (Note: messages of highest priority (alert) are always sent immediately. At most 128 messages can be queued.

Multiple recipients

  MailSingle=`yes/no`

  If there are multiple recipients, whether to send a single mail with the recipient list, or send multiple mails. If all recipients are on same domain, a single mail may suffice, otherwise it depends on whether the mail server supports forwarding (for security, most don't).

Subject line

  MailSubject=`string`

  Here, string may contain the placeholders %T, %H, %S, and/or %M that will get replaced by the time, hostname, message severity and message text, respectively. The default subject line is equivalent to "%T %H". This option may be useful if you want to send emails to an email-to-sms gateway.

Sender

  SetMailSender=`string`

  Here, string is the address that is inserted in the From: field. If a name without domain is given (i.e. without '@xyz.tld'), the FQDN of the local host will be added automatically.

AND Filter

  SetMailFilterAnd=`list`

  If used, then ALL strings in list must occur in a message, otherwise it will not be sent by email. As whitespace (blank or tab) is a valid separator in a list, strings with whitespace must be enclosed in single or double quotes. If a string begins with a double quote, enclose it in single quotes (and vice versa).

OR Filter

  SetMailFilterOr=`list`

  If used, then AT LEAST ONE of the strings in list must occur in a message, otherwise it will not be sent by email. As whitespace (blank or tab) is a valid separator in a list, strings with whitespace must be enclosed in single or double quotes. If a string begins with a double quote, enclose it in single quotes (and vice versa).

OR Filter

  SetMailFilterNot=`list`

  If used, then NONE of the strings in list can occur in a message, otherwise it will not be sent by email. As whitespace (blank or tab) is a valid separator in a list, strings with whitespace must be enclosed in single or double quotes. If a string begins with a double quote, enclose it in single quotes (and vice versa).

Example:

      [Misc]
      #
      # E-mail receipient (offsite in this case). Up to eight addresses,
      # each one at most 63 characters long.
      #
      SetMailAddress=username@host.some_domain.com
      #
      # Need a relay host for outgoing mail.
      #
      SetMailRelay=relay.mydomain.com
      #
      # Number of pending mails.
      #
      SetMailNum=10
      #
      # Maximum time between e-mails.
      # Want a message every day, just to be sure that the
      # program still runs.
      #
      SetMailTime=86400
      #
      # Do not send messages about added files, and startup messages
      #
      SetMailFilterNot = 'POLICY ADDED', START
      #
      # To all recipients in a single mail.
      MailSingle=yes

## 4.4.1. E-mail reports and their integrity

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 Section 4.2>), 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 (Section 11.2>).

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 Section 11.2>). If you use a pre-compiled executable from some binary distribution, be sure to read Section 11.2> carefully.

Prev | Home | Next
Activating logging facilities and filtering messages | Up | Log file