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

```bash
# 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

```bash
# 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
```bash
# 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
```bash
# 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:

```bash
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
```bash
# 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
```bash
# 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
```bash
# 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`:

```bash
# /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