hoborg/homelab
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: Add comprehensive security hardening guide

Browse Source 
- Document critical security vulnerabilities found
- Provide step-by-step hardening procedures
- Include SSL certificate recovery from git history
- Add SSH hardening with Mosh compatibility
- Document VPN setup with WireGuard
- Create implementation checklists and status tracking
This commit is contained in:
Arpad Krejczinger
2025-09-12 19:21:47 +02:00
parent 6980c36ae9
commit 3d2201bc40
1 changed files with 448 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

448
docs/security-hardening.md Normal file
View File

@@ -0,0 +1,448 @@
# Homelab Security Hardening Guide
## Overview
This document tracks the security hardening process for the homelab infrastructure. Based on security audit findings, we've identified critical vulnerabilities that need immediate attention.
## Critical Security Issues (IMMEDIATE ACTION REQUIRED)
### 🚨 Port Exposure Vulnerabilities
- **qBittorrent**: Currently binding to `0.0.0.0:6881` (exposed to all interfaces)
- **Gitea**: Currently binding to `0.0.0.0:3000` and `0.0.0.0:2223`
- **Portainer**: Docker management interface exposed on port 9000
**Status**: 🔴 NOT ADDRESSED
**Priority**: CRITICAL
**Impact**: Services accessible from internet without authentication
### 🚨 Missing Intrusion Prevention
- **fail2ban**: Not installed or running
- **Firewall**: UFW/iptables not properly configured
**Status**: 🔴 NOT ADDRESSED
**Priority**: CRITICAL
**Impact**: No protection against brute force attacks
### 🚨 SSL/TLS Missing
- **HTTPS**: SSL certificates were previously configured but may have been lost
- **Let's Encrypt**: Configuration exists in git history but needs restoration
- **Git History**: Found SSL config in commit `2cd1d87` with Let's Encrypt certificates
**Status**: 🟡 PARTIALLY ADDRESSED (config exists, needs deployment)
**Priority**: CRITICAL
**Impact**: All traffic unencrypted, vulnerable to MITM attacks
**Recovery Steps:**
```bash
# Restore SSL configuration from git
git show 2cd1d87:config/nginx/homelab.conf > config/nginx/homelab-ssl.conf
# Install certbot and get certificates
sudo pacman -S certbot certbot-nginx
sudo certbot --nginx -d ak-homelab.duckdns.org
# Deploy SSL-enabled nginx config
sudo cp config/nginx/homelab-ssl.conf /etc/nginx/sites-available/homelab
sudo nginx -t && sudo systemctl reload nginx
```
## Security Scripts Available
### ✅ Container Hardening (`scripts/harden-containers.sh`)
- Docker daemon configuration hardening
- Resource limits and security profiles
- Custom seccomp profiles
- Container security monitoring scripts
**Status**: 🟡 READY TO DEPLOY
**Next Step**: Run script and deploy hardened templates
### ✅ Credential Security (`scripts/secure-credentials.sh`)
- Secure credential storage in `/opt/homelab/secrets/`
- Docker secrets implementation
- Password generation utilities
- Access audit tools
**Status**: 🟡 READY TO DEPLOY
**Next Step**: Run script and migrate existing credentials
### ✅ Security Audit (`scripts/security-audit.sh`)
- Comprehensive system security assessment
- Credential exposure detection
- Service analysis and user audit
- Log analysis capabilities
**Status**: 🟡 READY TO USE
**Next Step**: Run initial audit to establish baseline
### ✅ Fail2ban Setup (`scripts/setup-fail2ban.sh`)
- SSH protection (port 2222)
- Nginx rate limiting and bot protection
- Custom filters for homelab services
- Attack analysis and monitoring tools
**Status**: 🟡 READY TO DEPLOY
**Next Step**: Install and configure fail2ban
### ✅ SSL Security (`scripts/ssl-security-audit.sh`)
- SSL/TLS configuration hardening
- Certificate monitoring and renewal
- Security headers implementation
- SSL testing and validation tools
**Status**: 🟡 READY TO DEPLOY
**Next Step**: Set up Let's Encrypt certificates first
## Implementation Plan
### Phase 1: Critical Security Fixes (Do NOW)
#### 1. Fix Port Exposure
```bash
# Bind services to localhost only
sudo docker update --publish-add "127.0.0.1:8080:8080" qbittorrent
sudo docker update --publish-rm "0.0.0.0:8080:8080" qbittorrent
sudo docker update --publish-add "127.0.0.1:3000:3000" gitea
sudo docker update --publish-rm "0.0.0.0:3000:3000" gitea
sudo docker update --publish-add "127.0.0.1:2223:22" gitea
sudo docker update --publish-rm "0.0.0.0:2223:22" gitea
```
#### 2. Install Fail2ban
```bash
sudo -A ./scripts/setup-fail2ban.sh
```
#### 3. Configure Basic Firewall
```bash
sudo ufw enable
sudo ufw allow 2222/tcp # SSH
sudo ufw allow 80/tcp # HTTP (temporary)
sudo ufw allow 443/tcp # HTTPS
sudo ufw allow 60000:61000/udp # Mosh UDP ports
sudo ufw --force reload
```
#### 4. SSH Hardening with Mosh Support
```bash
# Install Mosh for mobile SSH
sudo pacman -S mosh
# Edit /etc/ssh/sshd_config
sudo nano /etc/ssh/sshd_config
# Add these security settings:
# Port 2222 (already done)
# PermitRootLogin no
# PasswordAuthentication no # DISABLE AFTER KEY SETUP
# PubkeyAuthentication yes
# AllowUsers hoborg
# ClientAliveInterval 300
# ClientAliveCountMax 2
# MaxAuthTries 3
# Test SSH key authentication first
ssh-copy-id -i ~/.ssh/id_ed25519.pub hoborg@ak-homelab.duckdns.org -p 2222
# Then disable password authentication
# PasswordAuthentication no
# Restart SSH
sudo systemctl restart sshd
# Test Mosh connectivity
mosh hoborg@ak-homelab.duckdns.org --ssh="ssh -p 2222"
```
#### 4. Set Up SSL Certificates
```bash
sudo pacman -S certbot certbot-nginx
sudo certbot --nginx -d ak-homelab.duckdns.org
```
### Phase 2: Container Security
#### 1. Harden Docker Configuration
```bash
sudo -A ./scripts/harden-containers.sh
```
#### 2. Deploy Hardened Container Templates
```bash
sudo -A /opt/docker/monitoring/deploy-hardened-containers.sh
```
#### 3. Secure Credentials
```bash
sudo -A ./scripts/secure-credentials.sh
/opt/homelab/secrets/generate-passwords.sh
```
### Phase 3: SSH Hardening
#### 1. Set Up SSH Security Keys
- Generate SSH keys on management devices
- Add public keys to `~/.ssh/authorized_keys`
- Test key-based authentication
#### 2. Disable Password Authentication
```bash
# Edit /etc/ssh/sshd_config
PasswordAuthentication no
ChallengeResponseAuthentication no
UsePAM no
# Ensure Mosh compatibility
# Mosh uses UDP ports 60000-61000
sudo ufw allow 60000:61000/udp
# Restart SSH
sudo systemctl restart sshd
```
#### 3. Test Mosh Connectivity
```bash
# Install mosh if not present
sudo pacman -S mosh
# Test connection
mosh user@ak-homelab.duckdns.org --ssh="ssh -p 2222"
```
### Phase 4: Monitoring & Alerting
#### 1. Set Up System Monitoring
```bash
sudo -A ./scripts/setup-netdata.sh
sudo -A ./scripts/setup-glances.sh
```
#### 2. Configure SSL Monitoring
```bash
sudo -A ./scripts/ssl-security-audit.sh
sudo systemctl enable ssl-monitor.timer
```
#### 3. Set Up Regular Security Audits
```bash
# Add to cron for weekly audits
echo "0 2 * * 1 sudo -A /home/hoborg/homelab/scripts/security-audit.sh" | sudo tee -a /etc/cron.d/homelab-security
```
### Phase 5: VPN Setup (WireGuard)
#### 1. Install WireGuard
```bash
sudo pacman -S wireguard-tools
```
#### 2. Generate Server Keys
```bash
# Generate server keys
wg genkey | tee server_private.key | wg pubkey > server_public.key
# Generate client keys (on client device)
wg genkey | tee client_private.key | wg pubkey > client_public.key
```
#### 3. Server Configuration (/etc/wireguard/wg0.conf)
```ini
[Interface]
PrivateKey = <SERVER_PRIVATE_KEY>
Address = 10.0.0.1/24
ListenPort = 51820
PostUp = iptables -A FORWARD -i %i -j ACCEPT; iptables -A FORWARD -o %i -j ACCEPT; iptables -t nat -A POSTROUTING -o enp4s0 -j MASQUERADE
PostDown = iptables -D FORWARD -i %i -j ACCEPT; iptables -D FORWARD -o %i -j ACCEPT; iptables -t nat -D POSTROUTING -o enp4s0 -j MASQUERADE
[Peer]
PublicKey = <CLIENT_PUBLIC_KEY>
AllowedIPs = 10.0.0.2/32
```
#### 4. Client Configuration
```ini
[Interface]
PrivateKey = <CLIENT_PRIVATE_KEY>
Address = 10.0.0.2/24
DNS = 1.1.1.1
[Peer]
PublicKey = <SERVER_PUBLIC_KEY>
Endpoint = ak-homelab.duckdns.org:51820
AllowedIPs = 0.0.0.0/0
PersistentKeepalive = 25
```
#### 5. Enable VPN Service
```bash
sudo systemctl enable wg-quick@wg0
sudo systemctl start wg-quick@wg0
# Update firewall
sudo ufw allow 51820/udp
sudo ufw reload
```
#### 6. Router Port Forwarding
- Forward UDP port 51820 to homelab server
- Update DuckDNS to include VPN endpoint
#### 7. Test VPN Connectivity
```bash
# On client: Check VPN status
wg show
# Test homelab access through VPN
ssh hoborg@10.0.0.1 -p 2222
curl https://ak-homelab.duckdns.org
```
## Security Checklist
### Network Security
- [ ] Ports bound to localhost only
- [ ] Firewall configured and enabled
- [ ] Fail2ban installed and running
- [ ] VPN server configured
- [ ] SSH hardened (keys only, custom port)
### SSL/TLS Security
- [ ] Let's Encrypt certificates installed
- [ ] SSL configuration hardened
- [ ] HSTS headers configured
- [ ] Certificate monitoring active
- [ ] Perfect Forward Secrecy enabled
### Container Security
- [ ] Docker daemon hardened
- [ ] Containers run as non-root users
- [ ] Resource limits applied
- [ ] Security profiles enabled
- [ ] No privileged containers
### Credential Security
- [ ] Credentials moved to secure location
- [ ] Docker secrets implemented
- [ ] Strong passwords generated
- [ ] Access logging enabled
### Monitoring & Alerting
- [ ] System monitoring active (Netdata/Glances)
- [ ] Security event monitoring
- [ ] Log analysis configured
- [ ] Automated alerts set up
## Testing Procedures
### Security Testing
1. **Port Scanning**: `nmap -sV ak-homelab.duckdns.org`
2. **SSL Testing**: `sslscan ak-homelab.duckdns.org`
3. **Container Security**: `/opt/docker/monitoring/container-security-check.sh`
4. **Fail2ban Status**: `fail2ban-client status`
### Functionality Testing
1. **SSH Access**: Test key-based and password authentication
2. **Mosh Connectivity**: Test mobile SSH sessions
3. **VPN Access**: Test remote connectivity
4. **Service Access**: Verify all services work through Nginx proxy
5. **SSL Redirect**: Ensure HTTP redirects to HTTPS
## Emergency Procedures
### Security Incident Response
1. **Isolate**: Disconnect affected systems from network
2. **Assess**: Run security audit to identify compromise
3. **Contain**: Block malicious IPs, change credentials
4. **Recover**: Restore from clean backups
5. **Learn**: Update procedures based on incident
### Backup Security
- [ ] Encrypt backups
- [ ] Store offsite securely
- [ ] Test restoration procedures
- [ ] Include configuration backups
## Previous AI Agent Recommendations
### From CLAUDE.md (Voice Assistant Setup)
- ✅ Voice server configured for Claude Code
- ✅ Piper TTS integration working
- ✅ Mosh compatibility considerations noted
### From Git History Analysis
- **SSL Configuration**: Found complete Let's Encrypt setup in commit `2cd1d87`
- **WebDAV Support**: Advanced nginx configuration with security headers
- **Service Architecture**: Well-documented reverse proxy setup
### From network-security.md
- ✅ SSH port changed to 2222
- ✅ Router port forwarding updated
- ✅ Mosh configured (ISP UDP blocking noted)
- ✅ WireGuard VPN documentation complete
- ✅ fail2ban configuration documented
- ✅ UFW firewall setup documented
## Current Status Assessment
### ✅ Completed Items
- SSH port hardening (2222)
- Router port forwarding updates
- Voice assistant integration
- Network security documentation
- VPN setup documentation
### 🔴 Critical Issues (Immediate Action Required)
- Port exposure vulnerabilities
- Missing fail2ban installation
- SSL certificate restoration needed
- SSH password authentication still enabled
### 🟡 Partially Complete
- SSL configuration exists in git (needs deployment)
- Security scripts created (need execution)
- VPN documentation complete (needs implementation)
## Next Steps Priority
1. **IMMEDIATE**: Fix port exposure and install fail2ban
2. **HIGH**: Restore SSL certificates from git history
3. **MEDIUM**: Execute security hardening scripts
4. **MEDIUM**: Set up SSH key authentication and disable passwords
5. **LOW**: Implement WireGuard VPN
6. **LOW**: Set up monitoring and alerting
## References
### Security Resources
- [Docker Security Best Practices](https://docs.docker.com/develop/dev-best-practices/security/)
- [OWASP Docker Security Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/Docker_Security_Cheat_Sheet.html)
- [Mozilla SSL Configuration Generator](https://ssl-config.mozilla.org/)
- [WireGuard Documentation](https://www.wireguard.com/)
- [Let's Encrypt Certbot](https://certbot.eff.org/)
### Tools Used
- fail2ban: Intrusion prevention
- UFW: Firewall management
- certbot: SSL certificate management
- Docker: Container security features
- Netdata/Glances: System monitoring
## Status Updates
### 2025-09-12: Initial Assessment
- Identified critical port exposure vulnerabilities
- Found missing fail2ban and SSL certificates
- Created comprehensive hardening plan
- Documented all security scripts and their purposes
### Next Update: [Date]
- [Progress made]
- [Issues resolved]
- [Next steps]
---
**Last Updated**: 2025-09-12
**Security Status**: 🔴 CRITICAL - Immediate action required
**SSL Recovery**: Configuration found in git history (commit 2cd1d87)
**VPN Ready**: Complete WireGuard setup documentation available
**SSH Status**: Port hardened, password auth needs disabling