resist-vpn-infra/README_v2.md

# Secure VPN Server - Ansible Collection v2.0

**CIS Ubuntu 24.04 Level 1 Compliant** | Production-Ready | Two-Tier Architecture

Complete Ansible collection for deploying secure, hardened VPN servers with comprehensive user management, CIS benchmark compliance, and multi-server architecture support.

## What's New in v2.0

### 🔐 CIS Compliance
- **CIS Ubuntu 24.04 Level 1** benchmark compliance
- AppArmor mandatory access control
- Comprehensive audit logging (4.1.x)
- Enhanced network hardening (3.x)
- Password policies and PAM configuration (5.4.x, 5.5.x)

### 👥 SSH User Management
- **Automated user creation** with sudo access
- **SSH key generation** on control node
- **Root SSH restrictions** (disabled by default)
- **Password policies** (CIS compliant)
- User management playbooks (add/remove users)

### 🏗️ Two-Tier Architecture Support
- **ValleyForge** (admin control plane) manages infrastructure
- **VPN endpoints** (VPN1/VPN2/VPN3) serve end users
- **Firewall lockdown** to management sources only
- **Scalable** to hundreds of users across multiple servers

## Features

### Security Hardening (CIS Level 1)
- ✅ SSH hardening with strong ciphers (CIS 5.2.x)
- ✅ Root login disabled, admin users with sudo
- ✅ AppArmor enforcing mode (CIS 1.3.x)
- ✅ Comprehensive audit rules (CIS 4.1.x)
- ✅ Password complexity and expiration (CIS 5.4.x, 5.5.x)
- ✅ Account lockout policies (CIS 5.5.2)
- ✅ Kernel hardening via sysctl (CIS 3.x)
- ✅ Uncommon protocols disabled (CIS 3.3.x)
- ✅ Core dumps restricted (CIS 1.5.1)
- ✅ Automatic security updates
- ✅ Fail2ban intrusion prevention

### User Management
- ✅ Create admin users with SSH keys
- ✅ Automatic SSH key pair generation
- ✅ Sudo configuration (password/nopassword)
- ✅ Root account restrictions
- ✅ Add/remove user playbooks
- ✅ Password policy enforcement

### VPN Server
- ✅ WireGuard VPN with modern cryptography
- ✅ Per-user key generation
- ✅ QR codes for mobile devices
- ✅ Forward secrecy
- ✅ DNS encryption

### Firewall
- ✅ UFW with default deny
- ✅ Management access restricted to authorized sources
- ✅ VPN-only mode for infrastructure protection
- ✅ Rate limiting on SSH
- ✅ Two-tier architecture support

## Architecture

### Two-Tier VPN Infrastructure

```
┌─────────────────────────────────────────┐
│  ValleyForge (Admin Control Plane)      │
│  - WireGuard admin VPN (10.100.0.0/24)  │
│  - Ansible control node                 │
│  - GitHub Actions runner                │
│  - 2-5 admin users                      │
└──────────────┬──────────────────────────┘
               │ SSH (from ValleyForge IP only)
               ↓
┌──────────────────────────────────────────┐
│  VPN Endpoints (User Data Plane)         │
│  ┌────────────────────────────────────┐  │
│  │ VPN1 (10.200.0.0/24) - 50-70 users │  │
│  │ VPN2 (10.201.0.0/24) - 50-70 users │  │
│  │ VPN3 (10.202.0.0/24) - 50-70 users │  │
│  └────────────────────────────────────┘  │
└──────────────┬──────────────────────────┘
               │ User VPN (public access)
               ↓
        End Users (200+)
               ↓
    Collaboration Infrastructure
    (Mattermost, Nextcloud, Jitsi)
```

## Quick Start

### 1. Install Collection

```bash
tar xzf secure_vpn_server_v2.0.tar.gz
cd secure_vpn_server

# Install dependencies
pip3 install -r requirements.txt
ansible-galaxy collection install -r requirements.yml
```

### 2. Configure Inventory

```bash
# Edit inventory
nano inventory/hosts.yml
```

Set your servers:
```yaml
vpn_servers:
  hosts:
    vpn1:
      ansible_host: 203.0.113.10
    vpn2:
      ansible_host: 203.0.113.11
    vpn3:
      ansible_host: 203.0.113.12
```

### 3. Configure Variables

```bash
nano inventory/group_vars/vpn_servers.yml
```

**CRITICAL - Set ValleyForge IP**:
```yaml
valleyforge_public_ip: "185.112.147.205"  # Your actual IP!

admin_users:
  - username: alice
    comment: "Alice - Admin"
    groups: ["sudo"]
    generate_keys: true
```

### 4. Deploy

```bash
# Validate configuration
ansible-playbook -i inventory/hosts.yml playbooks/validate.yml

# Deploy everything
ansible-playbook -i inventory/hosts.yml playbooks/site.yml

# Or deploy to single server
ansible-playbook -i inventory/hosts.yml playbooks/site.yml --limit vpn1
```

### 5. Retrieve SSH Keys

```bash
# SSH keys are generated on control node
ls -la ssh-keys/vpn1/

# Copy to your machine
cp ssh-keys/vpn1/alice_id_ed25519 ~/.ssh/
chmod 600 ~/.ssh/alice_id_ed25519

# Test SSH
ssh -i ~/.ssh/alice_id_ed25519 alice@vpn1
```

## Playbooks

### Main Playbooks

| Playbook | Purpose | Usage |
|----------|---------|-------|
| `site.yml` | Complete deployment | Full server setup |
| `hardening.yml` | Security hardening only | Apply CIS controls |
| `users.yml` | User management only | Create admin users |
| `wireguard.yml` | VPN setup only | Deploy WireGuard |
| `firewall.yml` | Firewall config only | Configure UFW |
| `validate.yml` | Configuration validation | Pre-deployment check |

### User Management Playbooks

| Playbook | Purpose | Usage |
|----------|---------|-------|
| `add_user.yml` | Add single admin user | Interactive user creation |
| `remove_user.yml` | Remove admin user | Interactive user removal |

### Examples

```bash
# Full deployment
ansible-playbook -i inventory/hosts.yml playbooks/site.yml

# Add new admin user
ansible-playbook -i inventory/hosts.yml playbooks/add_user.yml

# Apply hardening to existing servers
ansible-playbook -i inventory/hosts.yml playbooks/hardening.yml

# Update firewall rules
ansible-playbook -i inventory/hosts.yml playbooks/firewall.yml
```

## Roles

### 1. system_hardening
**CIS Level 1 compliant system hardening**

Features:
- SSH hardening (strong ciphers, key-only auth)
- Sysctl kernel parameters (network, security)
- AppArmor mandatory access control
- Comprehensive audit logging
- Fail2ban intrusion prevention
- Automatic security updates
- Uncommon protocols disabled
- Core dumps restricted
- Security banners

### 2. ssh_users
**SSH user management with key generation**

Features:
- Create admin users with sudo access
- Generate SSH key pairs automatically
- Configure authorized_keys
- Password policy enforcement
- Sudo configuration (CIS 5.3.x)
- Root account restrictions

### 3. wireguard_server
**WireGuard VPN server deployment**

Features:
- WireGuard installation and configuration
- Per-user key generation
- Client config generation (desktop + mobile)
- QR codes for mobile devices
- Forward secrecy
- DNS encryption

### 4. secure_firewall
**UFW firewall with VPN-only mode**

Features:
- Default deny incoming
- Management access restricted to authorized sources
- User VPN publicly accessible
- Rate limiting on SSH
- Two-tier architecture support

## CIS Compliance

This collection implements **CIS Ubuntu 24.04 Level 1** controls:

| CIS Section | Controls | Status |
|-------------|----------|--------|
| 1.3.x | AppArmor | ✅ Implemented |
| 1.4.x | Warning Banners | ✅ Implemented |
| 1.5.x | Process Hardening | ✅ Implemented |
| 3.1.x | Network Parameters (Host) | ✅ Implemented |
| 3.2.x | Network Parameters (All) | ✅ Implemented |
| 3.3.x | Uncommon Protocols | ✅ Implemented |
| 3.4.x | Firewall Configuration | ✅ Implemented |
| 4.1.x | Audit Configuration | ✅ Implemented |
| 5.2.x | SSH Configuration | ✅ Implemented |
| 5.3.x | Sudo Configuration | ✅ Implemented |
| 5.4.x | User Accounts | ✅ Implemented |
| 5.5.x | PAM Configuration | ✅ Implemented |

### CIS Audit

Run CIS audit after deployment:
```bash
ssh alice@vpn1
sudo lynis audit system
```

## Security Features

### SSH Hardening
- Key-only authentication (passwords disabled)
- Root login disabled
- Strong ciphers (ChaCha20, AES-GCM)
- Strong MACs (SHA2-512/256 ETM)
- Strong KEX (Curve25519)
- Rate limiting (fail2ban)
- Verbose logging

### Network Hardening
- SYN cookies enabled
- IP forwarding controlled
- ICMP redirects disabled
- Source routing disabled
- Reverse path filtering
- Martian packet logging
- IPv6 disabled (optional)

### Access Control
- AppArmor enforcing
- Sudo logging
- Password complexity requirements
- Account lockout (5 failed attempts)
- Password expiration (365 days)
- Inactive account locking (30 days)

### Audit Logging
- Comprehensive audit rules (CIS 4.1.6-17)
- Time changes logged
- User/group changes logged
- Network changes logged
- Permission changes logged
- File access attempts logged
- File deletions logged
- Sudo usage logged
- Kernel module changes logged

## Configuration

### Admin Users

```yaml
admin_users:
  - username: alice
    comment: "Alice - Infrastructure Admin"
    groups: ["sudo", "adm"]
    generate_keys: true  # Auto-generate SSH keys
    shell: /bin/bash
    state: present
```

### Management Access

```yaml
# Allow management from ValleyForge only
management_allowed_sources:
  - "185.112.147.205"  # ValleyForge public IP
  - "10.100.0.0/24"    # ValleyForge admin VPN (optional)
```

### VPN Configuration

```yaml
# Per-host in host_vars/vpn1.yml
wg_network: "10.200.0.0/24"
wg_server_ip: "10.200.0.1"
wg_port: 51820

wg_peers:
  - name: user1
  - name: user2
  # ... 50-70 users per endpoint
```

## Files Generated

### On VPS Servers

```
/etc/wireguard/
├── wg0.conf                    # Server config
└── keys/                       # Server + user keys

/root/wireguard-client-configs/
├── user1.conf                  # Desktop configs
├── user1_qr.txt                # Mobile QR codes
└── README.md

/root/
├── deployment-summary.txt      # Deployment info
└── firewall-config.txt         # Firewall rules

/var/log/
├── sudo.log                    # Sudo usage
└── audit/audit.log             # Audit events
```

### On Control Node (ValleyForge)

```
ssh-keys/
└── vpn1/
    ├── alice_id_ed25519        # Private key
    ├── alice_id_ed25519.pub    # Public key
    ├── bob_id_ed25519
    ├── bob_id_ed25519.pub
    └── README.md               # Usage instructions
```

## Troubleshooting

### SSH Access Issues

```bash
# Test SSH with verbose output
ssh -vvv -i ~/.ssh/alice_id_ed25519 alice@vpn1

# Check SSH logs on server
sudo journalctl -u sshd -f

# Verify user exists
sudo getent passwd alice

# Check sudo access
sudo -l
```

### Firewall Issues

```bash
# Check UFW status
sudo ufw status verbose

# Check if management IP is allowed
sudo ufw status numbered

# Temporarily disable firewall (DANGEROUS!)
sudo ufw disable
```

### VPN Issues

```bash
# Check WireGuard status
sudo wg show

# Check WireGuard logs
sudo journalctl -u wg-quick@wg0 -f

# Restart WireGuard
sudo systemctl restart wg-quick@wg0
```

## Best Practices

### User Management
1. **Always create admin users** before disabling root SSH
2. **Test SSH access** with new users before disconnecting
3. **Keep private keys secure** - never commit to git
4. **Rotate SSH keys** every 90 days
5. **Remove users** when they leave the team

### Security
1. **Run validation playbook** before deployment
2. **Review audit logs** regularly
3. **Keep systems updated** (automatic updates enabled)
4. **Monitor fail2ban** for attack attempts
5. **Rotate VPN keys** for compromised users

### Operations
1. **Use version control** for inventory and variables
2. **Document changes** in git commits
3. **Test on single server** before deploying to all
4. **Keep backups** of SSH keys and configs
5. **Monitor resource usage** (CPU, RAM, bandwidth)

## Support

### Documentation
- `docs/TWO_TIER_DEPLOYMENT.md` - Two-tier architecture guide
- `docs/USAGE.md` - Detailed usage guide
- `CIS_REQUIREMENTS.md` - CIS compliance details

### Validation
```bash
ansible-playbook -i inventory/hosts.yml playbooks/validate.yml
```

### Audit
```bash
# CIS audit with Lynis
ssh alice@vpn1
sudo lynis audit system

# Check audit logs
sudo ausearch -ts recent
```

## License

MIT

## Version

2.0.0 - CIS Compliant with User Management

## Changelog

See `CHANGELOG.md` for version history.