Getting started
Five minutes from nothing to alerts. You need Linux, Python 3.9+ and PyYAML.
1. Try it without touching your server
Replay the sample log against a throwaway database. Nothing is sent anywhere in replay mode.
pip install sshsentrycurl -sO https://raw.githubusercontent.com/sshsentry/sshsentry/main/sample-auth.logsshsentry --db /tmp/sshsentry-try.db --replay sample-auth.log --digest-now # prints alerts, sends nothing
Or skip Python entirely and use the in-browser demo.
2. Install on a server
Either from PyPI:
$
sudo pip install sshsentryor as a single file from the repo:
sudo mkdir -p /opt/sshsentry /etc/sshsentry /var/lib/sshsentrysudo cp sshsentry.py /opt/sshsentry/sudo cp sshsentry.yaml /etc/sshsentry/sshsentry.yamlsudo apt install python3-yaml # or: sudo dnf install python3-pyyaml / pip install pyyaml
On Debian/Ubuntu with "externally managed" Python, prefer the distro package python3-yaml or a venv.
3. Run it
sudo python3 /opt/sshsentry/sshsentry.py # follow /var/log/auth.log or /var/log/securesudo python3 /opt/sshsentry/sshsentry.py --once # process new lines, then exit (for timers/cron)
Run as root so it can read the auth log and every user's authorized_keys. The first run is quiet: it records a baseline.
4. Keep it running with systemd
[Unit]Description=sshsentry SSH intrusion detectionAfter=network-online.target [Service]ExecStart=/usr/bin/python3 /opt/sshsentry/sshsentry.py -c /etc/sshsentry/sshsentry.yamlEnvironmentFile=-/etc/sshsentry/envRestart=on-failureRestartSec=10 [Install]WantedBy=multi-user.target
sudo systemctl daemon-reload && sudo systemctl enable --now sshsentryjournalctl -u sshsentry -f # alerts appear here
5. Optional: country checks
Create a free MaxMind account, download GeoLite2-Country to /usr/share/GeoIP/GeoLite2-Country.mmdb (or set geoip.database), and pip install geoip2. If either is missing, sshsentry prints one note and skips country checks.
Next: tune thresholds and turn on email or Slack in Configuration.