# 🛡️ 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.*