mvpg/docs/SECURITY.md

# 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.