Vish/homelab-optimized
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Sanitized mirror from private repository - 2026-03-18 10:31:50 UTC
Some checks failed
Documentation / Build Docusaurus (push) Failing after 21m3s
Details
Documentation / Deploy to GitHub Pages (push) Has been skipped
Details

Browse Source
This commit is contained in:
Gitea Mirror Bot
2026-03-18 10:31:50 +00:00
commit 8e49624d78
1221 changed files with 304405 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

340
docs/infrastructure/security.md Normal file
View File

@@ -0,0 +1,340 @@
# 🛡️ Security Model
**🔴 Advanced Guide**
This document outlines the security architecture protecting the homelab infrastructure, including network security, authentication, secrets management, and data protection.
---
## 🏗️ Security Architecture Overview
```
┌─────────────────────────────────────────────────────────────────────────────┐
│ SECURITY LAYERS │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ LAYER 1: PERIMETER │
│ ┌────────────────────────────────────────────────────────────────────┐ │
│ │ Internet ──► Router Firewall ──► Only 80/443 exposed │ │
│ │ │ │ │
│ │ Cloudflare (DDoS, WAF, SSL) │ │
│ └────────────────────────────────────────────────────────────────────┘ │
│ │
│ LAYER 2: NETWORK │
│ ┌────────────────────────────────────────────────────────────────────┐ │
│ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ │
│ │ │ Main │ │ IoT │ │ Guest │ (WiFi isolation) │ │
│ │ │ Network │ │ WiFi │ │ Network │ │ │
│ │ └──────────┘ └──────────┘ └──────────┘ │ │
│ └────────────────────────────────────────────────────────────────────┘ │
│ │
│ LAYER 3: ACCESS │
│ ┌────────────────────────────────────────────────────────────────────┐ │
│ │ Tailscale VPN ──► Secure remote access to all services │ │
│ │ Nginx Proxy Manager ──► Reverse proxy with SSL termination │ │
│ │ Individual service authentication │ │
│ └────────────────────────────────────────────────────────────────────┘ │
│ │
│ LAYER 4: APPLICATION │
│ ┌────────────────────────────────────────────────────────────────────┐ │
│ │ Vaultwarden ──► Password management │ │
│ │ .env files ──► Application secrets │ │
│ │ Docker isolation ──► Container separation │ │
│ └────────────────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
```
---
## 🔥 Network Security
### **Perimeter Defense**
#### Router Firewall
| Rule | Direction | Ports | Purpose |
|------|-----------|-------|---------|
| Allow HTTP | Inbound | 80 | Redirect to HTTPS |
| Allow HTTPS | Inbound | 443 | Reverse proxy access |
| Block All | Inbound | * | Default deny |
| Allow All | Outbound | * | Default allow |
#### Cloudflare Protection
- **DDoS Protection**: Always-on Layer 3/4/7 protection
- **WAF Rules**: Web Application Firewall for common attacks
- **SSL/TLS**: Full (strict) encryption mode
- **Rate Limiting**: Configured for sensitive endpoints
- **Bot Protection**: Managed challenge for suspicious traffic
### **Network Segmentation**
| Network | Type | Purpose | Isolation |
|---------|------|---------|-----------|
| **Main Network** | Wired/WiFi | Trusted devices, servers | Full access |
| **IoT WiFi** | WiFi only | Smart home devices | Internet only, no LAN access |
| **Guest Network** | WiFi only | Visitors | Internet only, isolated |
> **Note**: Full VLAN segmentation is planned but not yet implemented. Currently using WiFi-based isolation for IoT devices.
### **Tailscale VPN Overlay**
All internal services are accessible via Tailscale mesh VPN:
```
┌─────────────────────────────────────────────┐
│ TAILSCALE MESH NETWORK │
├─────────────────────────────────────────────┤
│ │
│ ┌─────────┐ ┌─────────┐ ┌─────────┐ │
│ │Atlantis │◄──►│ Calypso │◄──►│ Homelab │ │
│ │ NAS │ │ NAS │ │ VM │ │
│ └─────────┘ └─────────┘ └─────────┘ │
│ ▲ ▲ ▲ │
│ │ │ │ │
│ ▼ ▼ ▼ │
│ ┌─────────┐ ┌─────────┐ ┌─────────┐ │
│ │ Mobile │ │ Laptop │ │ Edge │ │
│ │ Devices │ │ MSI │ │ Devices │ │
│ └─────────┘ └─────────┘ └─────────┘ │
│ │
│ Benefits: │
│ • End-to-end encryption (WireGuard) │
│ • Zero-trust network access │
│ • No port forwarding required │
│ • Works behind NAT/firewalls │
└─────────────────────────────────────────────┘
```
---
## 🔐 Authentication & Access Control
### **Authentication Strategy**
| Method | Services | Notes |
|--------|----------|-------|
| **Individual Logins** | All services | Each service has its own authentication |
| **Vaultwarden** | Password storage | Bitwarden-compatible, self-hosted |
| **Tailscale ACLs** | Network access | Controls which devices can reach which services |
### **Service Authentication Matrix**
| Service Category | Auth Method | 2FA Support | Notes |
|-----------------|-------------|-------------|-------|
| **Plex** | Plex account | Yes | Cloud-linked auth |
| **Portainer** | Local admin | Yes (TOTP) | Container management |
| **Grafana** | Local accounts | Yes (TOTP) | Monitoring dashboards |
| **Vaultwarden** | Master password | Yes (required) | FIDO2/TOTP supported |
| **Nginx Proxy Manager** | Local admin | No | Internal access only |
| **Git (Gitea)** | Local accounts | Yes (TOTP) | Code repositories |
| **Immich** | Local accounts | No | Photo management |
### **Access Levels**
```
ADMIN (You)
├── Full access to all services
├── Portainer management
├── Infrastructure SSH access
└── Backup management
FAMILY
├── Media services (Plex, Jellyfin)
├── Photo sharing (Immich)
└── Limited service access
GUESTS
├── Guest WiFi only
└── No internal service access
```
---
## 🗝️ Secrets Management
### **Password Management**
- **Vaultwarden**: Self-hosted Bitwarden server
- **Location**: Atlantis NAS
- **Access**: `vault.vish.gg` via Tailscale
- **Backup**: Included in NAS backup rotation
### **Application Secrets**
| Secret Type | Storage Method | Location |
|-------------|---------------|----------|
| **Database passwords** | `.env` files | Per-stack directories |
| **API keys** | `.env` files | Per-stack directories |
| **SSL certificates** | File system | Nginx Proxy Manager |
| **SSH keys** | File system | `~/.ssh/` on each host |
| **Portainer env vars** | Portainer UI | Stored in Portainer |
### **Environment File Security**
```bash
# .env files are:
# ✅ Git-ignored (not committed to repos)
# ✅ Readable only by root/docker
# ✅ Backed up with NAS backups
# ⚠️ Not encrypted at rest (TODO)
# Best practices:
chmod 600 .env
chown root:docker .env
```
### **Future Improvements** (TODO)
- [ ] Implement HashiCorp Vault or similar
- [ ] Docker secrets for sensitive data
- [ ] Encrypted .env files
- [ ] Automated secret rotation
---
## 🔒 SSL/TLS Configuration
### **Certificate Strategy**
| Domain/Service | Certificate Type | Provider | Auto-Renewal |
|---------------|-----------------|----------|--------------|
| `*.vish.gg` | Wildcard | Cloudflare (via NPM) | Yes |
| Internal services | Let's Encrypt | ACME DNS challenge | Yes |
| Self-signed | Local CA | Manual | No |
### **Nginx Proxy Manager**
Primary reverse proxy handling SSL termination:
```
Internet ──► Cloudflare ──► Router:443 ──► NPM ──► Internal Services
│
├── plex.vish.gg ──► Atlantis:32400
├── grafana.vish.gg ──► Homelab:3000
├── git.vish.gg ──► Calypso:3000
└── ... (other services)
```
### **SSL Configuration**
- **Protocol**: TLS 1.2+ only
- **Ciphers**: Modern cipher suite
- **HSTS**: Enabled for public services
- **Certificate transparency**: Enabled via Cloudflare
---
## 💾 Backup Security
### **Backup Locations**
| Location | Type | Encryption | Purpose |
|----------|------|------------|---------|
| **Atlantis** | Primary | At-rest (Synology) | Local fast recovery |
| **Calypso** | Secondary | At-rest (Synology) | Local redundancy |
| **Backblaze B2** | Offsite | In-transit + at-rest | Disaster recovery |
### **Backup Encryption**
- **Synology Hyper Backup**: AES-256 encryption option
- **Backblaze B2**: Server-side encryption enabled
- **Transit**: All backups use TLS in transit
### **3-2-1 Backup Status**
```
┌─────────────────────────────────────────────┐
│ 3-2-1 BACKUP RULE │
├─────────────────────────────────────────────┤
│ │
│ 3 Copies: │
│ ├── 1. Original data (Atlantis) ✅ │
│ ├── 2. Local backup (Calypso) ✅ │
│ └── 3. Offsite backup (Backblaze) ✅ │
│ │
│ 2 Media Types: │
│ ├── NAS storage (Synology) ✅ │
│ └── Cloud storage (Backblaze B2) ✅ │
│ │
│ 1 Offsite: │
│ └── Backblaze B2 (cloud) ✅ │
│ │
│ STATUS: ✅ Compliant │
└─────────────────────────────────────────────┘
```
---
## 🕵️ Monitoring & Intrusion Detection
### **Active Monitoring**
| Tool | Purpose | Alerts |
|------|---------|--------|
| **Uptime Kuma** | Service availability | ntfy, Signal |
| **Prometheus** | Metrics collection | Alertmanager |
| **Grafana** | Visualization | Dashboard alerts |
| **WatchYourLAN** | Network device discovery | New device alerts |
### **Log Management**
- **Dozzle**: Real-time Docker log viewer
- **Synology Log Center**: NAS system logs
- **Promtail/Loki**: Centralized logging (planned)
### **Security Alerts**
- Failed SSH attempts (via fail2ban where deployed)
- New devices on network (WatchYourLAN)
- Service downtime (Uptime Kuma)
- Backup failures (Hyper Backup notifications)
---
## 🚨 Incident Response
### **Compromise Response Plan**
1. **Isolate**: Disconnect affected system from network
2. **Assess**: Determine scope of compromise
3. **Contain**: Block attacker access, change credentials
4. **Eradicate**: Remove malware, patch vulnerabilities
5. **Recover**: Restore from known-good backup
6. **Review**: Document incident, improve defenses
### **Emergency Access**
- **Physical access**: Always available for NAS/servers
- **Tailscale**: Works even if DNS is compromised
- **Out-of-band**: Console access via IPMI/iLO where available
---
## 📋 Security Checklist
### **Regular Tasks**
- [ ] Weekly: Review Uptime Kuma alerts
- [ ] Monthly: Check for service updates
- [ ] Monthly: Review Cloudflare analytics
- [ ] Quarterly: Rotate critical passwords
- [ ] Quarterly: Test backup restoration
### **Annual Review**
- [ ] Audit all service accounts
- [ ] Review firewall rules
- [ ] Update SSL certificates (if manual)
- [ ] Security assessment of new services
- [ ] Update this documentation
---
## 🔮 Future Security Improvements
| Priority | Improvement | Status |
|----------|-------------|--------|
| High | VLAN segmentation | Planned |
| High | Centralized auth (Authentik/Authelia) | Planned |
| Medium | HashiCorp Vault for secrets | Planned |
| Medium | Automated security scanning | Planned |
| Low | IDS/IPS (Suricata/Snort) | Considering |
---
## 📚 Related Documentation
- **[Network Architecture](networking.md)**: Detailed network setup
- **[Storage Systems](storage.md)**: Backup and storage configuration
- **[Host Infrastructure](hosts.md)**: Server and NAS documentation
---
*Security is an ongoing process. This documentation is updated as the infrastructure evolves.*