homelab/docs/ssh-honeypot-setup.md

SSH Honeypot Setup

Overview

The SSH honeypot is a deception service that listens on port 22 (the default SSH port) to detect and log unauthorized access attempts. The real SSH service runs on port 2222 for legitimate access.

Architecture

• Honeypot: Port 22 - Fake SSH service for logging attacks
• Real SSH: Port 2222 - Actual SSH access for administrators
• Gitea SSH: Port 2223 - Git repository access

Configuration Files

Service Configuration

File: config/systemd/ssh-honeypot.service Deploy to: /etc/systemd/system/ssh-honeypot.service

The systemd service uses ncat to listen on port 22 and execute a response script for each connection attempt.

Response Script

File: config/honeypot/response.sh Deploy to: /opt/honeypot/response.sh

The script logs each connection attempt and sends a fake SSH banner to make attackers believe they've reached a real SSH service.

Installation

# 1. Deploy service file
sudo cp config/systemd/ssh-honeypot.service /etc/systemd/system/

# 2. Create honeypot directory and deploy script
sudo mkdir -p /opt/honeypot
sudo cp config/honeypot/response.sh /opt/honeypot/
sudo chmod +x /opt/honeypot/response.sh

# 3. Create log file
sudo touch /var/log/honeypot.log
sudo chmod 644 /var/log/honeypot.log

# 4. Create honeypot group (if needed)
sudo groupadd honeypot || true

# 5. Enable and start service
sudo systemctl daemon-reload
sudo systemctl enable ssh-honeypot.service
sudo systemctl start ssh-honeypot.service

Verification

# Check service status
sudo systemctl status ssh-honeypot.service

# Verify port 22 is listening
ss -tlnp | grep :22

# Test connection
telnet localhost 22

# Check logs
tail -f /var/log/honeypot.log

Log Format

Each connection attempt is logged with:

• Timestamp
• Source IP address
• Connection event

Example log entry:

Thu Sep 12 20:18:32 CEST 2025: SSH honeypot connection from 192.168.1.100

Security Considerations

Benefits

• Early Detection: Identifies reconnaissance and attack attempts
• Threat Intelligence: Captures attacker IP addresses and timing
• Deception: Misleads attackers away from real services

Limitations

• Internal Only: Only logs connections from within the network
• Basic Logging: Simple timestamp and IP logging only
• No Interaction: Closes connection after sending banner

Monitoring

Real-time Monitoring

# Monitor honeypot logs
tail -f /var/log/honeypot.log

# Monitor service logs
journalctl -u ssh-honeypot.service -f

# Check connection counts
grep "honeypot connection" /var/log/honeypot.log | wc -l

Log Analysis

# Show unique attacking IPs
grep "honeypot connection" /var/log/honeypot.log | \
  awk '{print $NF}' | sort | uniq -c | sort -nr

# Show attack frequency by hour
grep "honeypot connection" /var/log/honeypot.log | \
  awk '{print $4}' | cut -d: -f1 | sort | uniq -c

# Recent attacks (last 24 hours)  
grep "$(date +%Y-%m-%d)" /var/log/honeypot.log

Integration with Real SSH

SSH Configuration

Ensure your real SSH service (/etc/ssh/sshd_config) is configured to listen on port 2222:

Port 2222
PermitRootLogin no
PasswordAuthentication no
PubkeyAuthentication yes

Router/Firewall Rules

• Port 22: No external forwarding (honeypot is internal only)
• Port 2222: Forward to 192.168.0.100:2222 for legitimate SSH access
• Port 2223: Forward to 192.168.0.100:2223 for Gitea SSH access

Troubleshooting

Service Won't Start

# Check if port 22 is already in use
ss -tlnp | grep :22

# Check service logs
journalctl -u ssh-honeypot.service -n 20

# Verify permissions
ls -la /opt/honeypot/response.sh
ls -la /var/log/honeypot.log

No Logs Generated

# Test script manually
sudo /opt/honeypot/response.sh

# Check log file permissions
ls -la /var/log/honeypot.log

# Verify ncat can access script
sudo -u honeypot /opt/honeypot/response.sh

Permission Errors

# Fix log permissions
sudo chmod 644 /var/log/honeypot.log

# Fix script permissions  
sudo chmod +x /opt/honeypot/response.sh

# Run as root if needed (remove Group=honeypot from service file)
sudo systemctl edit ssh-honeypot.service

Maintenance

Log Rotation

Consider setting up logrotate for /var/log/honeypot.log:

# /etc/logrotate.d/honeypot
/var/log/honeypot.log {
    weekly
    rotate 4
    compress
    delaycompress
    missingok
    notifempty
}

Regular Tasks

• Monitor logs weekly for attack patterns
• Archive old logs monthly
• Review and update response script as needed
• Verify service is running after system updates