mini-HOWTO: Receive mail alerts on SSH login

[timeBandit]

This guide illustrates one way to configure an SSH daemon to send email alerts on any successful login. All session types are reported: shell interactive, single-command and subsystem (sftp).

There are many tools and techniques one can use to keep abreast of connection activity on an unattended server (TCP wrappers, swatch, etc.). I devised this simple technique instead, in part because it required no packages beyond what I already had installed. On my systems, I use it to send an SMS alert to my mobile phone, the moment anyone logs in--just in case it isn't me. (If it isn't, I have a fighting chance to kick off the intruder and shut down the machine.)

Prerequisites/Assumptions
I assume you have the following packages installed and operating:

• OpenSSH (net-misc/openssh).
• The mailx client (mail-client/mailx), to send mail from shell scripts and the command line.
• An MTA (mail transfer agent) for mailx to use, such as Postfix or Sendmail.
• Optional: X Window System. Not required, but you need to be aware of it when configuring SSH.

If not, plenty of resources exist to help you, including these excellent forums. Setting up SSH and mail services is beyond the scope of this guide, which only covers connecting the two.

How It Works
SSH runs the script in /etc/ssh/sshrc, if it exists, after loading a user's environment but before starting their shell or command. This file provides for site-wide initializations needed "before the user's home directory becomes accessible" (man 8 sshd). Here, I use it to send mail with the details of the login.

What To Do
1. Become/login as root.
2. Create /etc/ssh/sshrc as follows. If the file already exists, don't overwrite it--simply add the commands following the "Send a brief alert ..." comment, at an appropriate point.

Code: Select all

# Set XAuthority using protocol and X cookie from stdin
# (example from man 8 sshd)
# You should omit this section if X (and hence xauth) is not installed.
#
if read proto cookie && [ -n "$DISPLAY" ]; then
	if [ `echo $DISPLAY | cut -c1-10` = 'localhost:' ]; then
		# X11UseLocalhost=yes
		echo add unix:`echo $DISPLAY |
		cut -c11-` $proto $cookie
	else
		# X11UseLocalhost=no
		echo add $DISPLAY $proto $cookie
	fi | xauth -q -
fi

# Send a brief alert with connection details
#
when=`/usr/bin/date`
where=`echo $SSH_CONNECTION|cut -f1 -d' '|cut -f4 -d:`
if [ -z "$SSH_TTY" ] ; then
	what="Connect by $USER"
else
	what="Login by $USER on $SSH_TTY"
fi

mailto=""
cc_to=""
bcc_to=""
while read address mode
do
        if [ -z "$address" -o "${address:0:1}" = "#" ] ; then continue; fi
        if [ "x$mode" = "xcc" -o "x$mode" = "xCC" ] ; then
                cc_to=${cc_to:+${cc_to},}$address
        elif [ "x$mode" = "xbcc" -o "x$mode" = "xBCC" ] ; then
                bcc_to=${bcc_to:+${bcc_to},}$address
        else
                mailto=${mailto:+${mailto},}$address
        fi
done </etc/ssh/notify

mailto=${mailto:-operator}
cc_to=${cc_to:+"-c $cc_to"}
bcc_to=${bcc_to:+"-b $bcc_to"}
mail ${cc_to} ${bcc_to} -s "SSH Alert" ${mailto} >&2 <<-EOM
	${what} from ${where} at ${when}
EOM

This file must be readable by all users (chmod 644 /etc/ssh/sshrc) since it is executed with the connecting user's privileges. It is not necessary, nor recommended, to set execute permission on the file. Recipient addresses for alerts reside in another file for ease of maintenance.

The above is bash syntax, and assumes /bin/sh is equivalent to /bin/bash on your system (SSH executes this file using /bin/sh). If that is not the case, I am afraid you are on your own--but please feel free to contribute an equivalent for another shell! For details on the bash tricks used, refer to "Parameter Expansion" in the bash manual page.

3. Create the recipient list file, /etc/ssh/notify. This also must be world-readable (chmod 644 /etc/ssh/notify). Replace the examples with the address(es) you want to notify when a client logs in.

Code: Select all

# Recipient list for SSH login alerts
#
# Format:
#	address[,address] [cc|bcc]
#
# Multiple addresses may be on separate lines or separated by commas.
# The "cc" and "bcc" options mark address(es) as "Cc:" or "Bcc:" recipients,
# respectively.
#
# Blank lines and lines with # in column 1 are ignored.
#
2015551212@sms.some-mobile.com
root@localhost,myself@work.com bcc

When any recipients are SMS addresses, you may want to avoid the CC option in favor of BCC. Blind-copy recipients do not appear in the message sent to the primary recipient(s), which helps keep the message short--important for SMS.

That's it. It is not necessary to restart sshd.

Testing
Login to the machine via SSH using any means you like (ssh, PuTTY, sftp, etc.). Within a few moments, the recipients listed in /etc/ssh/notify should receive a message similar to the following:

Code: Select all

To: 2015551212@sms.some-mobile.com
Subject: SSH Alert
Date: Wed, 19 Oct 2005 09:46:34 -0400 (EDT)
From: bandit@localhost.localdomain (Bandit)
 
Login by bandit on /dev/pts/0 from 192.168.1.2 at Wed Oct 19 09:46:34 EDT 2005

Note that SMS messages may not arrive for several minutes, depending on your provider's network and your own MTA setup. If this were an actual intrusion, you'd know who to pursue and where they came in--with luck, in time to slam the door on the nasty little bugger.

Troubleshooting
Things to check if you don't get any alerts:

1. Ensure /etc/ssh/sshrc and /etc/ssh/notify are world-readable: chmod 644 /etc/ssh/sshrc /etc/ssh/notify
2. Make sure mail is working: echo hello? | mail -s Test you@your.domain (replace you@your.domain with one of your real, working email addresses). If you don't receive the test message, troubleshoot the mail server and client setup.
3. Double-check the addresses in /etc/ssh/notify. In particular, note that addresses can be given one per line, or in comma-separated lists, or both--but whitespace-separated lists will not work. That is:

Code: Select all

GOOD: you@localhost,me@myhost
  OR: you@localhost
      me@myhost

BAD: you@localhost me@myhost

In the BAD example, any addresses after the first space would be silently ignored. The script does no address checks of any kind, so beware of typing mistakes.
4. Review your MTA logs for bounce reports or other complaints.

[nlindblad]

Thanks, just what I've been looking for!

[dpc]

I don't have SSH_CONNECTION set for some reason, so I modified the script to use SSH_CLIENT.

Code: Select all

where=`echo $SSH_CLIENT | cut -f1 -d' '`

Thanks for this useful script!