New branch

docs/SECURITY.md

@@ -0,0 +1,404 @@
+# Security Documentation
+
+## Overview
+
+The VPN Gateway implements multiple layers of security to ensure zero-leak protection and maintain privacy.
+
+## Core Security Features
+
+### 1. Permanent Killswitch
+
+The killswitch is the primary security mechanism that prevents any traffic leaks.
+
+#### Implementation
+
+- **Firewall Rules**: Default DROP policy for all chains
+- **Boot Protection**: Activates before network initialization
+- **Cannot be Disabled**: No UI or API endpoint to disable
+- **Continuous Monitoring**: Verified every 10 seconds
+
+#### Technical Details
+
+```bash
+# Default policies
+iptables -P INPUT DROP
+iptables -P FORWARD DROP
+iptables -P OUTPUT DROP
+
+# Only allowed traffic:
+# - Loopback (system operations)
+# - LAN subnet (WebUI access)
+# - Established connections
+# - VPN tunnel (when active)
+```
+
+### 2. DNS Leak Protection
+
+#### Mechanisms
+
+1. **Forced VPN DNS**: All DNS queries routed through VPN
+2. **System DNS Override**: /etc/resolv.conf locked
+3. **IPv6 Disabled**: Prevents IPv6 DNS leaks
+4. **DNS Filtering**: Only root can make DNS queries for VPN connection
+
+#### Configuration
+
+```bash
+# DNS through VPN only
+iptables -A OUTPUT -p udp --dport 53 -m owner --uid-owner root -j ACCEPT
+iptables -A OUTPUT -p tcp --dport 53 -m owner --uid-owner root -j ACCEPT
+
+# Block all other DNS
+iptables -A OUTPUT -p udp --dport 53 -j DROP
+iptables -A OUTPUT -p tcp --dport 53 -j DROP
+```
+
+### 3. IPv6 Protection
+
+Complete IPv6 blocking to prevent leaks:
+
+```bash
+# IPv6 firewall
+ip6tables -P INPUT DROP
+ip6tables -P FORWARD DROP
+ip6tables -P OUTPUT DROP
+
+# Kernel level
+sysctl -w net.ipv6.conf.all.disable_ipv6=1
+sysctl -w net.ipv6.conf.default.disable_ipv6=1
+```
+
+### 4. Security Monitor
+
+Continuous monitoring daemon that:
+- Verifies killswitch every 10 seconds
+- Detects potential leaks
+- Auto-recovers from failures
+- Logs security events
+
+## Threat Model
+
+### Protected Against
+
+✅ **IP Leaks**
+- Killswitch blocks all non-VPN traffic
+- No traffic possible without active tunnel
+
+✅ **DNS Leaks**
+- All DNS through VPN
+- System DNS locked
+- IPv6 DNS blocked
+
+✅ **WebRTC Leaks**
+- Blocked at firewall level
+- No direct peer connections
+
+✅ **IPv6 Leaks**
+- IPv6 completely disabled
+- Both firewall and kernel level
+
+✅ **Connection Drops**
+- Killswitch remains active
+- No traffic during reconnection
+- Auto-recovery available
+
+✅ **Malicious Applications**
+- Cannot bypass firewall rules
+- All traffic subject to killswitch
+
+### Not Protected Against
+
+❌ **Compromised Container**
+- If attacker gains root access
+- Can modify firewall rules
+
+❌ **Host System Compromise**
+- Container isolation breach
+- Hypervisor vulnerabilities
+
+❌ **Traffic Analysis**
+- VPN traffic patterns visible
+- Timing correlation attacks
+
+❌ **VPN Provider Compromise**
+- Malicious VPN server
+- Provider logging (choose carefully)
+
+## Security Best Practices
+
+### 1. Installation Security
+
+```bash
+# Verify installer integrity
+sha256sum install.sh
+# Compare with published hash
+
+# Review script before execution
+less install.sh
+
+# Run with specific version
+curl -sSL https://raw.githubusercontent.com/yourusername/vpn-gateway/v1.0.0/install.sh | bash
+```
+
+### 2. Access Control
+
+#### WebUI Protection
+
+```nginx
+# Restrict WebUI access to LAN only
+location / {
+    allow 192.168.1.0/24;
+    deny all;
+    # ... proxy settings
+}
+```
+
+#### SSH Hardening
+
+```bash
+# Disable password authentication
+PasswordAuthentication no
+
+# Key-only access
+PubkeyAuthentication yes
+
+# Restrict to specific IPs
+AllowUsers root@192.168.1.0/24
+```
+
+### 3. Key Management
+
+#### WireGuard Keys
+
+```bash
+# Generate new keys periodically
+wg genkey | tee privatekey | wg pubkey > publickey
+
+# Secure storage
+chmod 600 /etc/wireguard/*.key
+
+# Never share private keys
+# Unique keys per gateway
+```
+
+#### Rotation Schedule
+
+- **Private Keys**: Every 3-6 months
+- **Preshared Keys**: Every 1-3 months
+- **API Keys**: Every 30 days
+
+### 4. Monitoring
+
+#### Security Logs
+
+```bash
+# Monitor security events
+journalctl -u vpn-security-monitor -f
+
+# Check for failures
+grep "ALERT\|ERROR" /var/log/vpn-security-monitor.log
+
+# Audit firewall drops
+iptables -L -n -v | grep DROP
+```
+
+#### Leak Testing
+
+```bash
+# Regular leak tests
+curl https://ipleak.net/json/
+curl https://am.i.mullvad.net/json
+
+# DNS leak test
+nslookup example.com
+dig example.com
+```
+
+### 5. Updates
+
+#### Security Updates
+
+```bash
+# System updates (through VPN)
+apt update && apt upgrade
+
+# VPN Gateway updates
+/usr/local/bin/vpn-update.sh
+
+# Check for security advisories
+```
+
+#### Automatic Updates
+
+```bash
+# Enable unattended upgrades
+apt install unattended-upgrades
+dpkg-reconfigure -plow unattended-upgrades
+```
+
+## Incident Response
+
+### 1. Leak Detected
+
+If a leak is detected:
+
+1. **Immediate Action**
+   ```bash
+   # Re-enable killswitch
+   /usr/local/bin/vpn-killswitch.sh enable
+   
+   # Disconnect VPN
+   wg-quick down wg0
+   ```
+
+2. **Investigation**
+   ```bash
+   # Check logs
+   journalctl -u vpn-security-monitor -n 100
+   
+   # Verify firewall rules
+   iptables -L -n -v
+   ```
+
+3. **Recovery**
+   ```bash
+   # Restart security services
+   systemctl restart vpn-killswitch
+   systemctl restart vpn-security-monitor
+   ```
+
+### 2. Suspicious Activity
+
+Signs of compromise:
+- Unexpected firewall rule changes
+- Unknown processes with network access
+- Unusual CPU/memory usage
+- Modified system files
+
+Response:
+```bash
+# Check processes
+netstat -tulpn
+ps aux | grep -v grep | grep wg
+
+# Check file integrity
+debsums -c
+find /etc -type f -mtime -1
+
+# Review auth logs
+grep "Failed\|Invalid" /var/log/auth.log
+```
+
+### 3. Emergency Shutdown
+
+If immediate isolation needed:
+
+```bash
+# Block ALL network traffic
+iptables -P INPUT DROP
+iptables -P OUTPUT DROP
+iptables -P FORWARD DROP
+iptables -F
+
+# Stop services
+systemctl stop vpn-webui
+systemctl stop wg-quick@wg0
+
+# Preserve evidence
+tar czf /tmp/evidence-$(date +%s).tar.gz \
+  /var/log \
+  /etc/wireguard \
+  /opt/vpn-gateway/logs
+```
+
+## Security Hardening
+
+### 1. Container Hardening
+
+```bash
+# Limit capabilities
+lxc config set <container> security.nesting false
+lxc config set <container> security.privileged false
+
+# Resource limits
+lxc config set <container> limits.memory 512MB
+lxc config set <container> limits.cpu 1
+```
+
+### 2. Network Hardening
+
+```bash
+# Rate limiting
+iptables -A INPUT -p tcp --dport 5000 \
+  -m conntrack --ctstate NEW \
+  -m limit --limit 10/min --limit-burst 5 \
+  -j ACCEPT
+
+# SYN flood protection
+echo 1 > /proc/sys/net/ipv4/tcp_syncookies
+echo 2048 > /proc/sys/net/ipv4/tcp_max_syn_backlog
+```
+
+### 3. Application Hardening
+
+```python
+# Flask security headers
+from flask import Flask
+from flask_talisman import Talisman
+
+app = Flask(__name__)
+Talisman(app, 
+    force_https=False,  # Handle at reverse proxy
+    strict_transport_security=True,
+    content_security_policy={
+        'default-src': "'self'"
+    }
+)
+```
+
+## Compliance
+
+### GDPR Compliance
+
+- No personal data logging
+- User control over data
+- Right to deletion
+- Transparent processing
+
+### Security Standards
+
+- CIS Benchmarks compliance
+- NIST framework alignment
+- Zero-trust architecture
+- Defense in depth
+
+## Security Checklist
+
+### Daily
+- [ ] Check service status
+- [ ] Review security logs
+- [ ] Verify killswitch active
+
+### Weekly
+- [ ] Run leak tests
+- [ ] Check for updates
+- [ ] Review firewall rules
+
+### Monthly
+- [ ] Rotate keys
+- [ ] Audit access logs
+- [ ] Update documentation
+
+### Quarterly
+- [ ] Security assessment
+- [ ] Penetration testing
+- [ ] Disaster recovery test
+
+## Contact
+
+For security issues:
+- **Email**: security@yourdomain.com
+- **PGP Key**: [Public key]
+- **Response Time**: < 24 hours for critical issues
+
+Please report security vulnerabilities responsibly.