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

# 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

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

# 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

# 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

# Restrict WebUI access to LAN only
location / {
    allow 192.168.1.0/24;
    deny all;
    # ... proxy settings
}

SSH Hardening

# 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

# 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

# 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

# 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

# System updates (through VPN)
apt update && apt upgrade

# VPN Gateway updates
/usr/local/bin/vpn-update.sh

# Check for security advisories

Automatic Updates

# 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

   # Re-enable killswitch
   /usr/local/bin/vpn-killswitch.sh enable
   
   # Disconnect VPN
   wg-quick down wg0
   

2. Investigation

   # Check logs
   journalctl -u vpn-security-monitor -n 100
   
   # Verify firewall rules
   iptables -L -n -v
   

3. Recovery

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

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

# 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

# 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

# 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

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