Add comprehensive security documentation

- docs/ssh-honeypot-setup.md: Complete SSH honeypot installation and monitoring guide - docs/ssh-intrusion-monitoring.md: SSH attack detection and analysis procedures - docs/security-configurations.md: Updated catalog of all security configuration files - Includes installation procedures, monitoring commands, and troubleshooting guides
2025-09-12 20:38:49 +02:00
parent 8bbe8e0e28
commit ad9a3ab23e
3 changed files with 724 additions and 0 deletions
--- a/docs/ssh-honeypot-setup.md
+++ b/docs/ssh-honeypot-setup.md
@@ -0,0 +1,196 @@
+# 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