A comprehensive guide to setting up automated SSH connection monitoring with Telegram notifications for enhanced server security.
π¨ The Problem
As a system administrator, you need to know immediately when someone connects to your server via SSH. Whether it's a legitimate user or a potential security threat, real-time awareness is crucial for maintaining server security.
Traditional approaches like checking logs manually or using basic monitoring tools often fall short because they:
- β Don't provide real-time alerts
- β Lack user identification details
- β Miss parallel connection attempts
- β Don't distinguish between different connection types
π‘ The Solution: SSH Alert
SSH Alert is a robust, open-source solution that provides:
- π Maximum user identification - IP address, key fingerprint, user comments
- π± Real-time Telegram notifications - Instant alerts with detailed information
- π‘οΈ Smart rate limiting - Prevents notification spam during parallel sessions
- βοΈ Flexible configuration - Separate settings for different connection types
- π Automatic retry logic - Handles network failures gracefully
- π Comprehensive logging - Detailed logs with optional JSON format
π Quick Start
Installation
# Clone and install
git clone https://github.com/B4DCATs/ssh-login-alert
cd ssh-login-alert
sudo ./install.sh
Basic Configuration
Edit /etc/ssh-alert/config.conf
:
# Telegram Configuration
TELEGRAM_BOT_TOKEN="your_bot_token_here"
TELEGRAM_CHAT_ID="your_chat_id_here"
# Server Information
SERVER_NAME="production-server"
SERVER_DOMAIN="example.com"
# Notification Settings
NOTIFY_INTERACTIVE_SESSIONS=true
NOTIFY_TUNNELS=false
DISABLE_NOTIFICATION_SOUND_FOR_TUNNELS=true
# Rate Limiting (seconds)
RATE_LIMIT_PER_IP=300
RATE_LIMIT_PER_KEY=60
π§ Advanced Features
1. Enhanced User Identification
Configure authorized_keys
for maximum user identification:
# Add user identification to SSH keys
environment="SSH_USER=alice@company.com" ssh-rsa AAAAB3NzaC1yc2E... alice@laptop
2. CI/CD Pipeline Exclusions
Exclude automated connections from notifications:
# Add exclusions for automated systems
sudo ./manage-exclusions.sh add "pipeline@ci"
sudo ./manage-exclusions.sh add "deploy@automation"
sudo ./manage-exclusions.sh add "monitoring@system"
3. Smart Notification Types
SSH Alert distinguishes between connection types:
- Interactive Shell - Full terminal access (with sound notification)
- SSH Tunnel - Port forwarding (silent notification)
- Command Execution - Remote command execution (configurable)
4. Comprehensive Logging
# View real-time logs
sudo tail -f /var/log/ssh-alert.log
# Enable JSON logging for monitoring systems
echo 'JSON_LOGGING=true' | sudo tee -a /etc/ssh-alert/config.conf
π± Setting Up Telegram Bot
Step 1: Create Bot
- Message @BotFather on Telegram
- Send
/newbot
- Follow the instructions to create your bot
- Save the bot token
Step 2: Get Chat ID
- Add your bot to a chat or send it a message
- Visit:
https://api.telegram.org/bot<YOUR_BOT_TOKEN>/getUpdates
- Find your
chat.id
in the response
π‘οΈ Security Best Practices
1. Secure Configuration
# Restrict access to configuration
sudo chmod 600 /etc/ssh-alert/config.conf
sudo chown root:root /etc/ssh-alert/config.conf
2. Firewall Configuration
# Allow SSH only from trusted networks
sudo ufw allow from 192.168.1.0/24 to any port 22
sudo ufw deny 22
3. SSH Hardening
# Disable password authentication
sudo nano /etc/ssh/sshd_config
# Set: PasswordAuthentication no
sudo systemctl restart sshd
π Monitoring and Maintenance
System Health Checks
# Check system status
sudo systemctl status ssh-alert 2>/dev/null || echo "Service not installed"
# View active connections
sudo ss -tnp | grep sshd
# Check recent notifications
sudo grep "SSH alert sent" /var/log/ssh-alert.log | tail -5
Log Rotation
SSH Alert automatically configures log rotation:
# Check rotation status
sudo ./check-log-rotation.sh status
# Test rotation configuration
sudo ./check-log-rotation.sh test
# Force rotation
sudo ./check-log-rotation.sh rotate
π Troubleshooting
Common Issues
1. Notifications not arriving:
# Check configuration
sudo grep -E "TELEGRAM_BOT_TOKEN|TELEGRAM_CHAT_ID" /etc/ssh-alert/config.conf
# Check logs
sudo tail -f /var/log/ssh-alert.log
2. Script not starting:
# Check permissions
ls -la /opt/ssh-alert/ssh-alert-enhanced.sh
# Check syntax
bash -n /opt/ssh-alert/ssh-alert-enhanced.sh
3. Python errors:
# Check Python version
python3 --version
# Test parser
python3 /opt/ssh-alert/key-parser.py get-info
π Example Notification
Here's what you'll receive in Telegram:
π SSH Login Alert:
Host IP: 203.0.113.1 / 192.168.1.100
Host: production-server.example.com
Person: alice@company.com
IP: 198.51.100.50
Type: Interactive shell
Key: SHA256:abcd1234...
Time: 2024-01-15 14:30:25 UTC
π― Use Cases
1. Production Server Monitoring
- Real-time alerts for all SSH connections
- Distinguish between legitimate users and potential threats
- Track connection patterns and anomalies
2. Development Environment
- Monitor team access to shared development servers
- Track deployment activities
- Ensure compliance with access policies
3. Security Incident Response
- Immediate notification of unauthorized access attempts
- Detailed connection information for forensic analysis
- Integration with existing security monitoring systems
π Updates and Maintenance
Automatic Updates
# Update from repository
git pull origin main
sudo ./install.sh
Manual Updates
# Create backup
sudo cp -r /opt/ssh-alert /opt/ssh-alert.backup
sudo cp /etc/ssh-alert/config.conf /etc/ssh-alert/config.conf.backup
# Update files
sudo cp ssh-alert-enhanced.sh /opt/ssh-alert/
sudo cp key-parser.py /opt/ssh-alert/
ποΈ Uninstallation
# Complete removal
sudo /opt/ssh-alert/uninstall.sh
π€ Contributing
We welcome contributions! The project is open source and actively maintained.
- Fork the repository
- Create a feature branch
- Make your changes
- Submit a pull request
π Resources
- GitHub Repository: https://github.com/B4DCATs/ssh-login-alert
- Documentation: Complete setup guide in README
- Issues: Report bugs or request features
- License: MIT
π Conclusion
SSH Alert provides a robust, easy-to-use solution for SSH connection monitoring. With its real-time Telegram notifications, flexible configuration, and comprehensive logging, it's an essential tool for any system administrator concerned with server security.
The combination of detailed user identification, smart rate limiting, and support for automated systems makes it suitable for both small teams and large enterprise environments.
Ready to enhance your server security? Give SSH Alert a try and never miss an SSH connection again!
Have you implemented SSH monitoring in your infrastructure? Share your experiences and tips in the comments below! π
Top comments (0)