football/README.md

# Football - Minimal Debian Secure Access System

Fully self-contained, stripped-down, and locked-down Debian image intended for deployment onto physical access-only systems (Dell Laptop) called football-(x). Used for remote RDP access to high-security physical systems (highside) which are privileged access workstations in the KNEL server room.

## Overview

Football is a minimal Debian system designed for secure remote access to privileged infrastructure. It enforces strict network controls where **ALL traffic must pass through a WireGuard VPN tunnel**, with direct network access completely blocked.

**For complete functional requirements and artifact properties, see [docs/FUNCTIONAL-REQUIREMENTS.md](docs/FUNCTIONAL-REQUIREMENTS.md)**

## Architecture

### Security Model

- **Zero remote access**: No SSH, telnet, or any inbound services
- **WireGuard-only networking**: All traffic routed through mandatory VPN tunnel
- **Secure Boot enforced**: Kernel and bootloader signatures verified
- **Minimal attack surface**: Only IceWM and Remmina installed
- **Local console only**: No remote administration capabilities

### Network Configuration

```
Physical Interface (eth0)
├─ DHCP: Allowed (for IP acquisition)
└─ WireGuard: ONLY allowed connection to configured endpoint
    └─ Endpoint: WG_ENDPOINT_IP:WG_ENDPOINT_PORT (configurable)

WireGuard Interface (wg0)
└─ ALL outbound traffic
    └─ VPN endpoint → PAW (Privileged Access Workstation)
```

### Firewall Rules

- **INPUT**: DROP (except lo, WireGuard keepalive, and DHCP)
- **OUTPUT**: DROP on eth0 (except to WireGuard endpoint)
- **FORWARD**: DROP
- **OUTPUT on wg0**: ACCEPT (all VPN traffic)

## Quick Start

### Prerequisites

```bash
# Only requirement: Docker
# Docker handles all build tools and dependencies
docker --version
```

### Build ISO

```bash
# Build the Football installer ISO
./scripts/build-iso.sh
```

This creates:
- `output/football-installer.iso` - Bootable ISO with embedded preseed configuration

### Test ISO

```bash
# Test ISO by booting a VM
./scripts/test-iso.sh
```

This boots a 2GB RAM VM from the ISO, allowing you to test the installer before deploying.

### Deploy

#### Virtual Machine

The VM from `test-iso.sh` is ready for installation. Installer will:
- Auto-answer all questions except:
  - Username creation
  - User password (min 12 chars, mixed case, numbers, special chars)
  - Root password (min 12 chars, mixed case, numbers, special chars)
  - Target disk selection

#### Physical System

1. Write ISO to USB or disk:
   ```bash
   sudo dd if=output/football-installer.iso of=/dev/sdX bs=4M status=progress
   ```

2. Boot system from USB
3. Installer will use embedded preseed to automate installation
4. Provide only:
   - Username/password for user account
   - Root password
   - Target disk

3. Change default user password (`changeme`)

## Directory Structure

```
football/
├── build.sh                      # Main build script
├── config/
│   ├── packages.list            # Minimal package list
│   ├── harden.sh                # System hardening script
│   ├── secureboot.sh            # Secure Boot configuration
│   └── setup-wireguard.sh       # WireGuard setup script
├── chroot-overlay/              # Files copied to built system
│   ├── etc/
│   │   ├── systemd/system/     # Systemd services
│   │   ├── wireguard/           # WireGuard config templates
│   │   └── network/interfaces  # Network configuration
│   └── home/user/              # User configuration
│       ├── .bashrc
│       ├── .xinitrc
│       ├── .icewm/preferences
│       └── Desktop/README.txt
└── output/                     # Generated images (not in git)
```

## Security Features

### Hardening Measures

1. **Network Isolation**
   - All inbound traffic blocked
   - Only WireGuard traffic allowed on physical interface
   - Mandatory VPN tunnel for all outbound traffic

2. **Service Restrictions**
   - SSH server disabled and masked
   - All remote access services removed
   - Bluetooth disabled
   - Unnecessary kernel modules disabled

3. **Secure Boot**
   - GRUB locked with password protection
   - Kernel lockdown mode enabled
   - Signed bootloader (shim-signed)
   - EFI variables write-protected

4. **Application Whitelisting**
   - Only IceWM and Remmina installed
   - No development tools
   - Minimal command-line utilities

5. **System Hardening**
   - AppArmor enforcing
   - Fail2Ban enabled
   - Auditd logging
   - Core dumps disabled
   - Strict umask (077)

### Firewall Rules (Detailed)

```bash
# IPv4 Rules
iptables -P INPUT DROP
iptables -P FORWARD DROP
iptables -P OUTPUT DROP

# Allow loopback
iptables -A INPUT -i lo -j ACCEPT
iptables -A OUTPUT -o lo -j ACCEPT

# Allow WireGuard to endpoint on eth0
iptables -A OUTPUT -o eth0 -d $WG_ENDPOINT_IP \
  -p udp --dport $WG_ENDPOINT_PORT -j ACCEPT
iptables -A INPUT -i eth0 -s $WG_ENDPOINT_IP \
  -p udp --sport $WG_ENDPOINT_PORT -j ACCEPT

# Allow DHCP on eth0
iptables -A OUTPUT -o eth0 -p udp --dport 67 -j ACCEPT
iptables -A INPUT -i eth0 -p udp --sport 67 -j ACCEPT

# Allow ALL traffic on WireGuard interface
iptables -A INPUT -i wg0 -j ACCEPT
iptables -A OUTPUT -o wg0 -j ACCEPT
```

## Usage

### Default User

- **Username**: `user`
- **Password**: `changeme` (CHANGE IMMEDIATELY!)

### Automatic Startup

1. Login triggers automatic IceWM start
2. Remmina launches automatically
3. WireGuard tunnel establishes automatically
4. Use Remmina to connect to PAW

### Remmina Configuration

Create Remmina profiles in:
- Path: `/home/user/.local/share/remmina/`
- Protocol: RDP or VNC (as needed)
- Server: PAW internal IP via WireGuard

### System Administration

**Local console access only:**

```bash
# Check WireGuard status
sudo wg show

# View firewall rules
sudo iptables -L -n -v

# Check logs
sudo journalctl -u wg-quick@wg0
sudo journalctl -u block-remote-access
```

## Troubleshooting

### WireGuard Connection Fails

1. Verify endpoint IP and port
2. Check firewall rules allow WireGuard
3. Verify keys are correctly configured
4. Check WireGuard server logs

### Network Blocked

1. Confirm WireGuard interface is up: `ip link show wg0`
2. Check firewall: `sudo iptables -L -n -v`
3. Verify WireGuard config: `sudo wg show`

### Secure Boot Issues

1. Ensure UEFI is enabled
2. Verify Microsoft UEFI CA is installed
3. Check Secure Boot status: `mokutil --sb-state`

### System Won't Boot

1. Verify UEFI boot mode (not legacy BIOS)
2. Check GRUB installation
3. Review kernel logs from boot

## Advanced Configuration

### Customizing the Build

Edit `config/packages.list` to add/remove packages
Modify `chroot-overlay/` to customize system files

### Changing Image Size

Edit `build.sh`:
```bash
DISK_SIZE_MB=8192  # Change to desired size in MB
```

### Multiple Deployment Profiles

Create different `build.sh` variants with different configurations for various deployment scenarios.

## Security Considerations

### Before Deployment

1. ✅ Generate unique WireGuard keys per deployment
2. ✅ Change default password
3. ✅ Verify Secure Boot configuration
4. ✅ Test WireGuard connection
5. ✅ Verify firewall rules
6. ✅ Configure PAW connection in Remmina

### During Operation

1. ✅ Monitor WireGuard connection
2. ✅ Review audit logs regularly
3. ✅ Keep system updated (manual, controlled updates)
4. ✅ Physical security of device

### Incident Response

If compromise suspected:
1. Isolate system physically
2. Preserve logs and memory dump
3. Contact security team
4. Destroy/rebuild system from scratch

## Compliance

This system is designed to support:
- NIST SP 800-171 controls
- NIST SP 800-53 Moderate
- CIS Benchmarks for Debian 13 (Trixie)
- CMMC Level 3 controls
- FedRAMP Moderate controls
- Zero Trust network architecture principles
- Privileged Access Management (PAM) best practices

## License

See LICENSE file.

## Support

For issues or questions:
- Contact: Infrastructure Security Team
- Location: KNEL server room

---

**WARNING**: This is a security-focused build system. Unauthorized modifications or deployments may compromise infrastructure security.