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/security-configurations.md
+++ b/docs/security-configurations.md
@@ -0,0 +1,240 @@
+# Security Configuration Files
+
+## Overview
+
+This document catalogs all security-related configuration files in the homelab repository and their deployment locations.
+
+## SSH Security Configurations
+
+### SSH Honeypot
+- **Config File**: `config/systemd/ssh-honeypot.service`
+- **Deploy To**: `/etc/systemd/system/ssh-honeypot.service`  
+- **Purpose**: Systemd service for SSH honeypot on port 22
+- **Dependencies**: `config/honeypot/response.sh`
+
+- **Config File**: `config/honeypot/response.sh`
+- **Deploy To**: `/opt/honeypot/response.sh`
+- **Purpose**: Response script for honeypot connections
+- **Log File**: `/var/log/honeypot.log`
+
+### SSH Service Hardening
+- **System File**: `/etc/ssh/sshd_config`
+- **Key Settings**:
+  - `Port 2222` (moved from default port 22)
+  - `PermitRootLogin no`
+  - `PasswordAuthentication no`  
+  - `PubkeyAuthentication yes`
+
+## Network Security
+
+### Nginx Security Headers
+- **Config File**: `config/nginx/homelab.conf`
+- **Deploy To**: `/etc/nginx/sites-available/homelab`
+- **Security Features**:
+  - SSL/TLS configuration
+  - Security headers (HSTS, CSP, etc.)
+  - Rate limiting
+  - Access controls
+
+### NetworkManager Security
+- **Config File**: `config/networkmanager/01-homelab.conf`
+- **Deploy To**: `/etc/NetworkManager/conf.d/01-homelab.conf`
+- **Purpose**: Static IP and interface security settings
+
+## Service-Specific Security
+
+### Gitea Security
+- **Config File**: `config/docker/gitea/docker-compose.yml`
+- **Security Features**:
+  - Custom SSH port (2223)
+  - Database isolation
+  - Volume permissions
+  - Network restrictions
+
+### Jellyfin Security  
+- **Config File**: `config/docker/jellyfin/docker-compose.yml`
+- **Security Features**:
+  - User/group restrictions
+  - Volume mount security
+  - Network isolation
+
+### qBittorrent Security
+- **Config File**: `config/docker/qbittorrent/docker-compose.yml`
+- **Security Features**:
+  - VPN integration capability
+  - Web UI access controls
+  - File permission restrictions
+
+## System Security Services
+
+### Copyparty File Server
+- **Config File**: `config/systemd/copyparty.service`
+- **Deploy To**: `/etc/systemd/system/copyparty.service`
+- **Config File**: `config/copyparty/copyparty.conf`
+- **Deploy To**: `~/.config/copyparty/copyparty.conf`
+- **Security Features**:
+  - WebDAV authentication
+  - Access controls
+  - Upload restrictions
+
+## Security Hardening Configurations
+
+### Fail2ban Intrusion Prevention
+- **Config File**: `config/fail2ban/jail.local`
+- **Deploy To**: `/etc/fail2ban/jail.local`
+- **Purpose**: Automated IP banning for SSH, web, and service attacks
+
+- **Config Files**: `config/fail2ban/filter.d/`
+- **Deploy To**: `/etc/fail2ban/filter.d/`
+- **Filters**:
+  - `sshd-ddos.conf` - SSH connection flooding protection
+  - `nginx-badbots.conf` - Web scanner and bot detection
+  - `gitea-auth.conf` - Gitea authentication failure detection
+
+### SSH Security Hardening
+- **Config File**: `config/ssh/sshd_config_hardening`
+- **Deploy To**: Append to `/etc/ssh/sshd_config`
+- **Purpose**: Enhanced SSH security settings
+
+- **Config File**: `config/ssh/banner`
+- **Deploy To**: `/etc/ssh/banner`
+- **Purpose**: Legal warning banner for SSH connections
+
+### Kernel Security Parameters
+- **Config File**: `config/sysctl/99-security.conf`
+- **Deploy To**: `/etc/sysctl.d/99-security.conf`
+- **Purpose**: Network and memory protection parameters
+
+### Docker Security Configuration
+- **Config File**: `config/docker/daemon.json`
+- **Deploy To**: `/etc/docker/daemon.json`
+- **Purpose**: Docker daemon security hardening
+
+### Service Rate Limiting
+- **Config File**: `config/systemd/nginx.service.d/rate-limit.conf`
+- **Deploy To**: `/etc/systemd/system/nginx.service.d/rate-limit.conf`
+- **Purpose**: Nginx resource limits and connection throttling
+
+## Monitoring and Logging
+
+### Service Monitoring
+- **Config File**: `config/systemd/glances-web.service`
+- **Deploy To**: `/etc/systemd/system/glances-web.service`
+- **Purpose**: System monitoring with web interface
+
+### System Logging
+- **Config File**: `config/systemd/01-server-logind.conf`
+- **Deploy To**: `/etc/systemd/logind.conf.d/01-server-logind.conf`
+- **Purpose**: Login and session security settings
+
+## Security Documentation
+
+### Setup Guides
+- `docs/ssh-honeypot-setup.md` - SSH honeypot installation and configuration
+- `docs/ssh-intrusion-monitoring.md` - Comprehensive SSH monitoring guide
+- `docs/qbittorrent-setup.md` - Secure torrent client setup
+
+### Security Procedures
+- `docs/security-configurations.md` - This file (configuration catalog)
+- Various service-specific security notes in configuration files
+
+## Deployment Security
+
+### File Permissions
+All configuration files include deployment commands with appropriate permissions:
+
+```bash
+# Service files
+sudo chmod 644 /etc/systemd/system/*.service
+
+# Scripts  
+sudo chmod +x /opt/honeypot/response.sh
+
+# Config files
+sudo chmod 644 /etc/nginx/sites-available/*
+sudo chmod 600 ~/.config/copyparty/copyparty.conf
+```
+
+### Service Security
+```bash
+# Enable services securely
+sudo systemctl daemon-reload
+sudo systemctl enable --now servicename.service
+
+# Verify service status
+sudo systemctl status servicename.service
+```
+
+## Security Validation
+
+### Configuration Testing
+```bash
+# Test nginx configuration
+sudo nginx -t
+
+# Verify SSH configuration
+sudo sshd -t
+
+# Check systemd service syntax
+sudo systemd-analyze verify /etc/systemd/system/servicename.service
+```
+
+### Security Scanning
+```bash
+# Check listening ports
+ss -tlnp
+
+# Verify service users and permissions  
+sudo systemctl show servicename.service
+
+# Check file permissions
+find config/ -type f -ls
+```
+
+## Security Updates
+
+### Regular Maintenance
+1. **Weekly**: Review honeypot logs, update fail2ban rules
+2. **Monthly**: Update service configurations, security patches
+3. **Quarterly**: Full security audit, penetration testing
+4. **Annually**: Certificate renewal, security policy review
+
+### Configuration Backup
+All configurations are version-controlled in git:
+```bash
+# Backup current configs
+git add config/ docs/
+git commit -m "Update security configurations"
+
+# Restore from backup
+git checkout HEAD -- config/
+```
+
+## Security Contacts and Escalation
+
+### Log Locations
+- **Security Incidents**: `/var/log/security.log`
+- **Authentication**: `/var/log/auth.log`
+- **Honeypot**: `/var/log/honeypot.log`
+- **Service Logs**: `journalctl -u servicename.service`
+
+### Incident Response
+1. Immediate containment (block IPs, disable services)
+2. Evidence preservation (copy logs, take snapshots)
+3. Impact assessment (check for compromise)
+4. Recovery procedures (restore from known-good configs)
+5. Post-incident review (update procedures and configurations)
+
+## Compliance and Standards
+
+### Security Frameworks
+- **Network Security**: Defense in depth with multiple layers
+- **Access Control**: Principle of least privilege
+- **Monitoring**: Comprehensive logging and alerting
+- **Incident Response**: Documented procedures and escalation
+
+### Audit Trail  
+- All configuration changes tracked in git
+- Service modifications logged via systemd
+- Security events captured in dedicated log files
+- Regular security reviews documented in commit messages
--- 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
--- a/docs/ssh-intrusion-monitoring.md
+++ b/docs/ssh-intrusion-monitoring.md
@@ -0,0 +1,288 @@
+# SSH Intrusion Monitoring Guide
+
+## Overview
+
+This guide covers comprehensive SSH intrusion detection and monitoring for the homelab environment, including both honeypot analysis and real SSH service monitoring.
+
+## Log Files and Locations
+
+### Primary Log Files
+- **Honeypot Logs**: `/var/log/honeypot.log` - Attack attempts on port 22
+- **SSH Authentication**: `/var/log/auth.log` - Real SSH attempts on port 2222
+- **System Security**: `/var/log/secure` or `/var/log/security.log` - General security events
+- **Service Logs**: `journalctl -u sshd.service` - SSH daemon logs
+
+### Service Status Monitoring
+```bash
+# Check honeypot service
+systemctl status ssh-honeypot.service
+
+# Check real SSH service  
+systemctl status sshd.service
+
+# Monitor both services
+systemctl status ssh-honeypot.service sshd.service
+```
+
+## Honeypot Monitoring
+
+### Real-time Monitoring
+```bash
+# Live honeypot attack monitoring
+tail -f /var/log/honeypot.log
+
+# Monitor with timestamps
+tail -f /var/log/honeypot.log | while read line; do echo "$(date '+%H:%M:%S') $line"; done
+```
+
+### Attack Analysis
+```bash
+# Count total attack attempts
+grep -c "honeypot connection" /var/log/honeypot.log
+
+# Show unique attacking IP addresses with attempt counts
+grep "honeypot connection" /var/log/honeypot.log | \
+  awk '{print $NF}' | sort | uniq -c | sort -nr
+
+# Attacks by hour of day
+grep "honeypot connection" /var/log/honeypot.log | \
+  awk '{print $4}' | cut -d: -f1 | sort | uniq -c | sort -k2 -n
+
+# Recent attacks (last 24 hours)
+grep "$(date '+%a %b %d')" /var/log/honeypot.log
+
+# Attacks from specific IP
+grep "192.168.1.100" /var/log/honeypot.log
+```
+
+### Geographic Analysis
+```bash
+# Get country information for attacking IPs (requires geoip)
+grep "honeypot connection" /var/log/honeypot.log | \
+  awk '{print $NF}' | sort -u | \
+  while read ip; do
+    echo -n "$ip: "
+    geoiplookup "$ip" 2>/dev/null | head -1 | cut -d: -f2
+  done
+```
+
+## Real SSH Monitoring
+
+### Authentication Monitoring
+```bash
+# Monitor real SSH authentication attempts
+tail -f /var/log/auth.log | grep sshd
+
+# Failed password attempts
+grep "Failed password" /var/log/auth.log | tail -10
+
+# Successful logins
+grep "Accepted password\|Accepted publickey" /var/log/auth.log | tail -10
+
+# Invalid users attempting login
+grep "Invalid user" /var/log/auth.log | tail -10
+```
+
+### Connection Analysis  
+```bash
+# Current SSH connections
+ss -tnp | grep :2222
+
+# Active SSH sessions
+who -u
+
+# Login history
+last -n 20
+
+# Failed login attempts by IP
+grep "Failed password" /var/log/auth.log | \
+  awk '{print $(NF-3)}' | sort | uniq -c | sort -nr
+```
+
+### Brute Force Detection
+```bash
+# Show IPs with multiple failed attempts
+grep "Failed password" /var/log/auth.log | \
+  awk '{print $(NF-3)}' | sort | uniq -c | \
+  awk '$1 > 5 {print $2 " (" $1 " attempts)"}'
+
+# Recent failed attempts (last hour)
+grep "$(date '+%b %d %H:')" /var/log/auth.log | \
+  grep "Failed password"
+
+# Successful logins after failed attempts (potential compromise)
+grep -A5 -B5 "Accepted" /var/log/auth.log | \
+  grep -E "Failed password|Accepted"
+```
+
+## Network-Level Monitoring
+
+### Port Scanning Detection
+```bash
+# Check for connection attempts to common ports
+ss -tlnp | grep -E ":(22|2222|2223|80|443|8080)"
+
+# Monitor connection attempts (requires netstat)
+netstat -tln | grep LISTEN | grep -E ":(22|2222|2223)"
+
+# Check iptables logs (if logging enabled)
+grep "DROP" /var/log/kern.log | tail -10
+```
+
+### Active Connection Monitoring
+```bash
+# Show all network connections
+ss -tuln
+
+# Monitor new connections
+watch -n 2 'ss -tn | grep :2222'
+
+# Check for unusual processes using network
+lsof -i :2222
+lsof -i :22
+```
+
+## Alerting and Notifications
+
+### Simple Alert Scripts
+Create monitoring scripts for common scenarios:
+
+```bash
+# Alert on honeypot activity
+#!/bin/bash
+# /usr/local/bin/honeypot-alert.sh
+LAST_CHECK="/tmp/honeypot-last-check"
+LOG_FILE="/var/log/honeypot.log"
+
+if [ ! -f "$LAST_CHECK" ]; then
+    touch "$LAST_CHECK"
+fi
+
+NEW_ATTACKS=$(find "$LOG_FILE" -newer "$LAST_CHECK" | wc -l)
+if [ "$NEW_ATTACKS" -gt 0 ]; then
+    echo "ALERT: $NEW_ATTACKS new honeypot attacks detected"
+    tail -n "$NEW_ATTACKS" "$LOG_FILE"
+fi
+
+touch "$LAST_CHECK"
+```
+
+### Fail2ban Integration
+Monitor fail2ban status for automatic IP blocking:
+
+```bash
+# Check fail2ban status
+sudo fail2ban-client status
+
+# Check SSH jail specifically  
+sudo fail2ban-client status sshd
+
+# Show banned IPs
+sudo fail2ban-client get sshd banip
+
+# Unban IP if needed
+sudo fail2ban-client set sshd unbanip 192.168.1.100
+```
+
+## Log Analysis Tools
+
+### Basic Analysis Commands
+```bash
+# Most common attacking IPs across both services
+(grep "honeypot connection" /var/log/honeypot.log | awk '{print $NF}'; \
+ grep "Failed password" /var/log/auth.log | awk '{print $(NF-3)}') | \
+ sort | uniq -c | sort -nr | head -10
+
+# Timeline of attacks (both honeypot and real SSH)
+(grep "honeypot connection" /var/log/honeypot.log | sed 's/honeypot/HONEYPOT/'; \
+ grep "Failed password" /var/log/auth.log | sed 's/Failed password/REAL_SSH/') | \
+ sort -k1,3
+```
+
+### Advanced Analysis
+```bash
+# Attack patterns by time of day
+grep -E "(honeypot connection|Failed password)" \
+  /var/log/honeypot.log /var/log/auth.log | \
+  awk '{print $4}' | cut -d: -f1 | sort | uniq -c | \
+  sort -k2 -n
+
+# Correlation between honeypot and real SSH attacks
+comm -12 \
+  <(grep "honeypot connection" /var/log/honeypot.log | awk '{print $NF}' | sort -u) \
+  <(grep "Failed password" /var/log/auth.log | awk '{print $(NF-3)}' | sort -u)
+```
+
+## Incident Response
+
+### Immediate Response
+```bash
+# Block suspicious IP immediately
+sudo iptables -A INPUT -s SUSPICIOUS_IP -j DROP
+
+# Check current connections from IP
+ss -tn | grep SUSPICIOUS_IP
+
+# Kill any active sessions from IP
+sudo pkill -f "sshd.*SUSPICIOUS_IP"
+```
+
+### Investigation Steps
+1. **Identify Attack Source**: Analyze logs to determine origin IP and attack pattern
+2. **Check Compromise**: Look for successful logins after failed attempts  
+3. **Assess Impact**: Check for file modifications, new users, or privilege escalation
+4. **Implement Blocks**: Add IP to fail2ban or firewall rules
+5. **Monitor**: Continue monitoring for related activity
+
+### Forensic Analysis
+```bash
+# Check for privilege escalation attempts
+grep -i "sudo\|su\|root" /var/log/auth.log | tail -20
+
+# Look for file access patterns
+find /var/log -name "*.log" -mtime -1 -exec grep "SUSPICIOUS_IP" {} \;
+
+# Check for new user accounts or modifications
+grep -E "(useradd|usermod|passwd)" /var/log/auth.log | tail -10
+```
+
+## Automated Monitoring Setup
+
+### Cron Jobs for Regular Monitoring
+```bash
+# Add to crontab (crontab -e)
+# Check for new attacks every 5 minutes
+*/5 * * * * /usr/local/bin/honeypot-alert.sh
+
+# Daily security report
+0 9 * * * /usr/local/bin/daily-security-report.sh
+
+# Weekly log cleanup
+0 2 * * 0 /usr/local/bin/cleanup-old-logs.sh
+```
+
+### System Integration
+- Configure rsyslog to separate security logs
+- Set up log rotation for security logs
+- Integrate with monitoring systems (Nagios, Zabbix, etc.)
+- Configure email alerts for critical events
+
+## Best Practices
+
+### Monitoring Frequency
+- **Real-time**: Honeypot attacks, SSH authentication failures
+- **Hourly**: Connection pattern analysis, unusual activity
+- **Daily**: Attack summary, trend analysis, IP reputation checks
+- **Weekly**: Comprehensive security review, log archiving
+
+### Log Retention
+- **Honeypot logs**: 30 days for analysis, 90 days archived
+- **SSH auth logs**: 90 days active, 1 year archived  
+- **Security logs**: 180 days active, 2 years archived
+- **Incident logs**: Permanent retention for forensic analysis
+
+### Performance Considerations
+- Monitor log file sizes and implement rotation
+- Use efficient grep/awk patterns for large log files
+- Consider log aggregation tools for high-volume environments
+- Archive old logs to prevent disk space issues