Email notifications for successful SSH logins and repeated authentication failures on Linux servers. Built with the Python standard library, the systemd journal, and TLS-enabled SMTP. No third-party Python packages required.
- Checks the latest 50 SSH service records at a configurable interval (15 seconds by default).
- Reports successful logins with username, source IP, authentication method, and timestamp in your preferred timezone.
- Configurable failure threshold, time window, and per-IP notification cooldown (defaults: 5 indicators within 10 minutes, 10-minute cooldown).
- Persists the journal cursor and email queue in SQLite. Failed deliveries are retried after 60 seconds.
- Establishes a baseline on first startup without emailing historical events.
- Configurable SMTP server, TLS mode, sender address/name, and multiple recipients.
- Validate your configuration without sending email using
--check-config. - English by default, with Turkish available. Language and timezone are independent.
- Suppresses raw journal messages, SMTP credentials, and exception details in application output.
Check the installed program using its full path (works from any directory):
python3 /usr/local/lib/ssh-email-alerts/ssh_email_alerts.py --versionCheck for a newer stable GitHub release:
python3 /usr/local/lib/ssh-email-alerts/ssh_email_alerts.py --check-updateIf you are inside the cloned project directory, you can instead use:
python3 ssh_email_alerts.py --version
python3 ssh_email_alerts.py --check-updatessh_email_alerts.py is the Python filename; these commands require python3. Checking the cloned file shows that checkout's version, which may differ from the installed program. The repository name ssh-email-alerts uses hyphens. A short command such as ssh-email-alerts --version works only if a wrapper or alias has been installed separately; the standard installation below does not create one. Custom installations may use different paths.
The update check requires internet access but no SMTP configuration. It prints the installed and latest version, with a release link when an update is available. A failed check exits with status 1. It never sends email, downloads a new version, or changes your installation. The running service does not check for updates automatically.
For GitHub release notifications, choose Watch → Custom → Releases on the repository page. Read the release notes before updating.
Run these commands from your existing project clone on the Linux server:
git pull --ff-only
python3 ssh_email_alerts.py --version
sudo install -m 644 ssh_email_alerts.py /usr/local/lib/ssh-email-alerts/ssh_email_alerts.py
sudo python3 /usr/local/lib/ssh-email-alerts/ssh_email_alerts.py --check-config
sudo systemctl restart ssh-email-alerts.service
sudo systemctl is-active ssh-email-alerts.serviceKeep your existing /etc/ssh-email-alerts/config.env and /var/lib/ssh-email-alerts state directory. Do not repeat the example configuration copy during an upgrade. The commands above use the default installation paths and service name; adjust them if you installed elsewhere. git pull follows the development branch; for a specific release, use git fetch --tags and git checkout v1.0.0 instead of git pull.
English example emails with sender and recipient details redacted.
This test preview uses an example username and IP address; it does not represent a real login event.
The --test-email command sends a test message to verify your SMTP configuration.
Python 3.9 or later, Linux with systemd, SSH records under ssh.service or sshd.service, an SMTP account, and system timezone data (usually the tzdata package).
The supplied service runs as root to read the system journal and applies systemd hardening settings.
Run these steps in the terminal of the Linux server you want to monitor, not on your Mac or Windows computer. If you manage the server remotely, connect to it first using your usual SSH connection. You need Git, Python 3.9 or later, and permission to run sudo commands.
These instructions are for a first installation. If you already run an SSH alert service, check your existing setup before starting another instance. Repeating the configuration-copy step below overwrites the existing configuration file.
git clone https://github.com/daedricc/ssh-email-alerts.git
cd ssh-email-alertsgit clone downloads the project into a new ssh-email-alerts folder. cd enters that folder. Run the remaining steps from this directory so the source files can be found. If Git is missing, install it using your Linux distribution's package manager first.
sudo install -d -m 755 /usr/local/lib/ssh-email-alerts
sudo install -m 644 ssh_email_alerts.py /usr/local/lib/ssh-email-alerts/ssh_email_alerts.py
sudo install -d -m 700 /etc/ssh-email-alerts
sudo install -m 600 .env.example /etc/ssh-email-alerts/config.envThese commands create the program and configuration folders, then copy the program and example settings into them. sudo runs a command with administrator privileges; it may ask for your Linux account password. The configuration folder and file are restricted to the administrator because they will contain SMTP credentials.
sudoedit /etc/ssh-email-alerts/config.envThis opens the configuration in your system's text editor. Replace the sample SMTP host, port, username, password, sender address, and recipient with your own settings. Set SENDER_NAME to the name you want recipients to see, choose LANGUAGE=en or LANGUAGE=tr, and set TIMEZONE to an IANA timezone such as UTC or Europe/Istanbul. Save the file and close the editor before continuing. See the configuration table below for every setting.
The sample uses Resend: use your API key as SMTP_PASSWORD, resend as SMTP_USER, and a sender on your verified domain. Other SMTP providers are supported with their own settings.
The configuration uses simple KEY=value lines. Shell commands, variable expansion, and multiline values are not supported. Keep the real configuration private; never commit it to GitHub.
sudo install -m 644 systemd/ssh-email-alerts.service /etc/systemd/system/ssh-email-alerts.service
sudo systemctl daemon-reloadThe service file tells Linux how to run the program in the background. daemon-reload tells systemd to read the new service definition; it does not start the program yet.
sudo python3 /usr/local/lib/ssh-email-alerts/ssh_email_alerts.py --check-config
sudo python3 /usr/local/lib/ssh-email-alerts/ssh_email_alerts.py --test-email--check-config checks local syntax, required fields, email address format, language, timezone, TLS mode, and numeric ranges. It does not connect to SMTP, validate credentials with your provider, or create a state database.
Check the test-email command's result and your recipient inbox, including the spam folder. SMTP acceptance means the mail server accepted the message; it does not guarantee inbox delivery. If the test fails, review your configuration and SMTP provider settings before proceeding. The program suppresses credentials and detailed exceptions in its output.
sudo systemctl enable --now ssh-email-alerts.service
sudo systemctl is-active ssh-email-alerts.serviceenable --now starts the service immediately and enables automatic startup when the server boots. The status command should print active. On its first check, the service establishes a baseline without emailing historical logins. New SSH login events will then be monitored.
To inspect the latest service messages:
sudo journalctl -u ssh-email-alerts.service -n 50 --no-pagerEach installation has its own configuration file. The example contains placeholders only.
| Setting | Purpose | Example / default |
|---|---|---|
SMTP_HOST |
SMTP server hostname | smtp.example.com; default smtp.resend.com |
SMTP_PORT |
SMTP server port | 465 (default) or 587 |
SMTP_SECURITY |
TLS connection mode | auto (default), ssl, starttls |
SMTP_USER |
SMTP username | YOUR_SMTP_USER |
SMTP_PASSWORD |
SMTP password or provider app password | YOUR_SMTP_PASSWORD |
EMAIL_FROM |
Sender email address | alerts@example.com |
SENDER_NAME |
Optional sender display name | SSH Alerts |
EMAIL_TO |
One or more comma-separated recipients | you@example.com,team@example.com |
LANGUAGE |
Email and runtime message language | en (default) or tr |
TIMEZONE |
IANA timezone for login timestamps | UTC (default), Europe/Istanbul |
POLL_INTERVAL |
Seconds between checks | 15 |
FAILURE_WINDOW |
Seconds in the failure counting window | 600 |
FAILURE_THRESHOLD |
Failure indicators required to trigger an alert | 5 |
ALERT_COOLDOWN |
Seconds before the same IP can trigger another alert | 600 |
SMTP_SECURITY=auto uses implicit TLS on port 465 and mandatory STARTTLS on other ports. Set ssl or starttls explicitly for a custom port. Certificate verification is always enabled. Use a sender address your SMTP provider permits.
For example:
SMTP_HOST=smtp.example.com
SMTP_PORT=587
SMTP_SECURITY=starttls
SMTP_USER=YOUR_SMTP_USER
SMTP_PASSWORD=YOUR_SMTP_PASSWORD
EMAIL_FROM=alerts@example.com
SENDER_NAME=SSH Alerts
EMAIL_TO=you@example.com
LANGUAGE=en
TIMEZONE=Europe/BerlinNumeric settings must be whole numbers from 1 to 86400. For example, FAILURE_THRESHOLD=3 and FAILURE_WINDOW=300 trigger an alert after three indicators from one IP in five minutes. ALERT_COOLDOWN is independent of the counting window.
For Turkish messages and Istanbul time, set LANGUAGE=tr and TIMEZONE=Europe/Istanbul. Timezones apply daylight-saving rules automatically where applicable. Unsupported languages, invalid timezones, invalid ports, and unsupported TLS modes are rejected.
Configuration is reread during checks and email delivery. Queued messages retain the language and timestamps used when they were created. CLI help is in English.
sudo systemctl is-active ssh-email-alerts.service
sudo journalctl -u ssh-email-alerts.service -n 50 --no-pager
python3 ssh_email_alerts.py --help--config PATH: configuration file, default/etc/ssh-email-alerts/config.env. TheSSH_ALERT_CONFIGenvironment variable is also supported.--state-dir PATH: persistent state directory, default/var/lib/ssh-email-alerts.--check-config: validate local settings without sending email or creating state.--once: perform one check and delivery attempt; exit with status 1 on journal or delivery failure.--test-email: send a test message and exit.
python3 -m unittest discover -s tests -vUnit tests cover parsing, queue behavior, configuration validation, languages, timezones, thresholds, and cooldowns. Process-level sandbox tests create temporary files, a synthetic journalctl executable, and an SMTP server listening only on loopback. They exercise real TLS/STARTTLS connections, sender headers, multiple recipients, temporary rejection and retry, persistent state across restarts, and certificate rejection. No external SMTP account or real SSH journal is used.
The sandbox needs openssl and permission to bind a local socket. Its ephemeral certificate is trusted only inside test child processes; production certificate verification is unchanged. These tests do not verify the service under a real Linux systemd installation. See the verification report for scope and results.
This tool sends notifications; it does not block IPs. One connection can produce multiple failure indicators, so the threshold is not a count of unique connections.
Only the newest 50 journal records are read per check. High traffic or a long interruption can cause intermediate events to be skipped; a log-volume alert is queued when a check reaches this limit. If journal records are removed or the cursor becomes invalid, the service reports a check failure; automatic cursor recovery is not implemented.
SMTP acceptance does not guarantee inbox delivery. A process interruption after SMTP acceptance may cause a duplicate message. If any recipient is rejected, the message remains queued and is retried for all recipients; recipients who already accepted it may receive duplicates. The queue can grow during extended SMTP outages. Pending messages are still attempted when journal reads fail. An attacker with root access can alter the service and logs.
No license has been selected yet. This repository currently grants no explicit open-source license.

