resist-vpn-infra/README.md at main

2026-01-26 21:22:41 -05:00

10 KiB

Raw Permalink Blame History

# Secure VPN Server - Ansible Collection Production-grade Ansible collection for deploying secure VPN infrastructure with two-tier architecture: admin control plane (ValleyForge) managing user VPN endpoints (VPN1/VPN2/VPN3). ## Architecture ### Two-Tier VPN Infrastructure

Tier 1: Admin Control Plane (ValleyForge)   • WireGuard admin VPN (10.100.0.0/24)   • Ansible control node   • GitHub Actions runner (future)   • 2-5 admin users  Tier 2: User Data Plane (VPN1/VPN2/VPN3)   • User-facing VPN endpoints   • 50-70 users per endpoint (200 total)   • Separate VPN networks (10.200.x.0/24)   • Gateway to collaboration tools

Management Flow: Admin → ValleyForge admin VPN → ValleyForge → Ansible → VPN1/VPN2/VPN3 User Flow: User → VPN1/VPN2/VPN3 → Collaboration Server

Features

System Hardening

SSH hardening (key-only auth, strong ciphers, rate limiting)
Kernel parameter hardening (sysctl)
Automatic security updates
Fail2ban intrusion prevention
Auditd logging
Minimal package installation

WireGuard VPN

Modern VPN with forward secrecy
Per-user key management
Automatic client config generation
QR codes for mobile devices
DNS encryption

Secure Firewall

Management access restricted to ValleyForge
User VPN port accessible from internet
SSH/management ports blocked from public
Rate limiting
Connection tracking

Quick Start

Prerequisites

ValleyForge deployed with WireGuard admin VPN
Ansible installed on ValleyForge
SSH access from ValleyForge to VPN endpoints
Ubuntu 24.04 on all servers

1. Configure Inventory

On ValleyForge:

cd /root/ansible/secure_vpn_server
nano inventory/hosts.yml

Set your VPN endpoint IPs:

vpn_servers:
  hosts:
    vpn1:
      ansible_host: 203.0.113.10  # Your VPN1 public IP
    vpn2:
      ansible_host: 203.0.113.11  # Your VPN2 public IP
    vpn3:
      ansible_host: 203.0.113.12  # Your VPN3 public IP
  
  vars:
    valleyforge_public_ip: "185.112.147.205"  # Your ValleyForge public IP

2. Configure Variables

nano inventory/group_vars/vpn_servers.yml

CRITICAL: Set management access sources:

# Allow management from ValleyForge
management_allowed_sources:
  - "185.112.147.205"  # Your ValleyForge public IP

# Configure users
wg_peers:
  - name: user1
  - name: user2
  - name: user3

3. Validate Configuration

ansible-playbook -i inventory/hosts.yml playbooks/validate.yml

4. Deploy

# Test deployment
ansible-playbook -i inventory/hosts.yml playbooks/site.yml --check

# Deploy to single endpoint (test)
ansible-playbook -i inventory/hosts.yml playbooks/site.yml --limit vpn1

# Deploy to all endpoints
ansible-playbook -i inventory/hosts.yml playbooks/site.yml

5. Retrieve Configs

scp -r root@203.0.113.10:/root/wireguard-client-configs/ /root/vpn1-configs/
scp -r root@203.0.113.11:/root/wireguard-client-configs/ /root/vpn2-configs/
scp -r root@203.0.113.12:/root/wireguard-client-configs/ /root/vpn3-configs/

Documentation

TWO_TIER_DEPLOYMENT.md - Complete two-tier architecture deployment guide
USAGE.md - Detailed usage guide
VALLEYFORGE_BOOTSTRAP.md - ValleyForge setup guide
TWO_TIER_VPN_ARCHITECTURE.md - Architecture overview

Firewall Configuration

Management Access

Restricted to ValleyForge only:

management_allowed_sources:
  - "185.112.147.205"  # ValleyForge public IP
  # - "10.100.0.0/24"  # Or ValleyForge admin VPN (if routing configured)

Management ports (SSH, HTTP, HTTPS, etc.):

✅ Accessible from ValleyForge
❌ Blocked from internet

User VPN port (51820):

✅ Accessible from internet

Access Matrix

Source	Destination	Port	Result
Internet	VPN1/2/3	51820 (user VPN)	✅ ALLOWED
ValleyForge	VPN1/2/3	22 (SSH)	✅ ALLOWED
Internet	VPN1/2/3	22 (SSH)	❌ BLOCKED
Internet	VPN1/2/3	80/443	❌ BLOCKED

Directory Structure

secure_vpn_server/
├── galaxy.yml                      # Collection metadata
├── README.md                       # This file
├── requirements.txt                # Python dependencies
├── requirements.yml                # Ansible collections
├── playbooks/
│   ├── site.yml                    # Full deployment
│   ├── hardening.yml               # Hardening only
│   ├── wireguard.yml               # WireGuard only
│   ├── firewall.yml                # Firewall only
│   └── validate.yml                # Configuration validation
├── roles/
│   ├── system_hardening/           # SSH, sysctl, fail2ban, auditd
│   ├── wireguard_server/           # WireGuard VPN
│   └── secure_firewall/            # UFW firewall + management access control
├── inventory/
│   ├── hosts.yml                   # Server inventory
│   ├── group_vars/
│   │   └── vpn_servers.yml         # VPN endpoint configuration
│   └── host_vars/
│       ├── vpn1.yml                # VPN1 specific config
│       ├── vpn2.yml                # VPN2 specific config
│       └── vpn3.yml                # VPN3 specific config
└── docs/
    ├── TWO_TIER_DEPLOYMENT.md      # Two-tier deployment guide
    └── USAGE.md                    # Detailed usage guide

Configuration Examples

Minimal Configuration

# inventory/group_vars/vpn_servers.yml

# REQUIRED: Management access sources
management_allowed_sources:
  - "185.112.147.205"  # ValleyForge public IP

# Users
wg_peers:
  - name: user1
  - name: user2

# VPN settings (defaults are fine)
wg_network: "10.200.0.0/24"  # Overridden per host
vpn_only_mode: true

Advanced Configuration

# System settings
system_timezone: "UTC"
ssh_port: 2222  # Custom SSH port

# WireGuard settings
wg_port: 51820

# Users with manual IPs
wg_peers:
  - name: alice
    ip: 10.200.0.10
  - name: bob
    ip: 10.200.0.11

# Management access
management_allowed_sources:
  - "185.112.147.205"  # ValleyForge public IP
  - "10.100.0.0/24"    # ValleyForge admin VPN (if routing configured)

# Additional management ports
management_ports:
  - port: 2222
    proto: tcp
    comment: "SSH"
  - port: 8080
    proto: tcp
    comment: "Outline Manager"

# Security features
fail2ban_enabled: true
auditd_enabled: true
unattended_upgrades_enabled: true
ssh_rate_limit: true

Usage

Deploy to All Endpoints

ansible-playbook -i inventory/hosts.yml playbooks/site.yml

Deploy to Single Endpoint

ansible-playbook -i inventory/hosts.yml playbooks/site.yml --limit vpn1

Deploy Specific Components

# Only hardening
ansible-playbook -i inventory/hosts.yml playbooks/hardening.yml

# Only WireGuard
ansible-playbook -i inventory/hosts.yml playbooks/wireguard.yml

# Only firewall
ansible-playbook -i inventory/hosts.yml playbooks/firewall.yml

Add Users

# Edit variables
nano inventory/group_vars/vpn_servers.yml

# Add user
wg_peers:
  - name: user1
  - name: user2
  - name: new_user3  # Add this

# Re-deploy WireGuard
ansible-playbook -i inventory/hosts.yml playbooks/wireguard.yml --limit vpn1

# Retrieve new config
scp root@vpn1-ip:/root/wireguard-client-configs/new_user3.conf /root/

Monitor Endpoints

# Check WireGuard status
ansible vpn_servers -i inventory/hosts.yml -m shell -a "wg show"

# Check firewall status
ansible vpn_servers -i inventory/hosts.yml -m shell -a "ufw status"

# Check services
ansible vpn_servers -i inventory/hosts.yml -m shell -a "systemctl status wg-quick@wg0"

Troubleshooting

Can't SSH from ValleyForge After Deployment

Use VPS console/VNC:

# Check firewall
sudo ufw status verbose

# Temporarily allow your IP
sudo ufw allow from YOUR_VALLEYFORGE_IP to any port 22

# Or disable firewall temporarily
sudo ufw disable

Wrong ValleyForge IP in Firewall

# On ValleyForge, update group_vars
nano inventory/group_vars/vpn_servers.yml

# Fix the IP
management_allowed_sources:
  - "CORRECT.IP.ADDRESS.HERE"

# Re-deploy firewall
ansible-playbook -i inventory/hosts.yml playbooks/firewall.yml

Validation Fails

# Check that management_allowed_sources is set
cat inventory/group_vars/vpn_servers.yml | grep management_allowed_sources

# Should show:
# management_allowed_sources:
#   - "185.112.147.205"

Security Best Practices

✅ What This Collection Does

SSH Hardening: Key-only auth, strong ciphers, rate limiting
Kernel Hardening: Secure sysctl parameters
Automatic Updates: Security patches applied automatically
Intrusion Prevention: Fail2ban blocks brute force
Audit Logging: Track security-relevant events
Management Access Control: Only from ValleyForge
Forward Secrecy: VPN traffic protected even if keys compromised

⚠️ Important Notes

Management Access: Once deployed, management ports are ONLY accessible from ValleyForge. Test SSH access before deploying!

ValleyForge IP: Ensure management_allowed_sources contains your actual ValleyForge IP.

Idempotent: Safe to re-run playbooks anytime.

Requirements

Control Machine: ValleyForge with Ansible 2.15+
Target Servers: Ubuntu 24.04 LTS (or 22.04)
SSH Access: Root or sudo user with SSH key authentication
Python: Python 3.8+ on target servers

Installation

On ValleyForge

# Install Ansible
pip3 install -r requirements.txt

# Install Ansible collections
ansible-galaxy collection install -r requirements.yml

Support

Documentation: See docs/ directory
Issues: GitHub issues
Security: Report security issues privately

License

MIT License

Version

1.1.0 - Two-Tier Architecture Support

Author

Security Infrastructure Team

10 KiB Raw Permalink Blame History