football/docs/FUNCTIONAL-REQUIREMENTS.md

# Football Secure Access System - Functional Requirements

## Document Information

- **System Name**: Football Secure Access System
- **Document Type**: Functional Requirements Specification
- **Version**: 1.0
- **Date**: 2025-01-20
- **Status**: Final (Production Ready)

---

## 1. Purpose

The Football Secure Access System is a minimal, hardened Debian 13 (trixie) system designed for secure remote access to Tier0 infrastructure. It provides secure, auditable access to privileged workstations (PAWs) while enforcing strict network isolation.

---

## 2. Functional Requirements

### 2.1 Core Functionality

**FR-1: Remote Access to Privileged Infrastructure**
- The system MUST provide remote desktop access (RDP) to Privileged Access Workstations (PAWs)
- Remote access MUST be secured via WireGuard VPN tunnel
- All remote access traffic MUST route through VPN (no direct network access)

**FR-2: Network Isolation**
- The system MUST block all direct network access on physical interfaces
- The system MUST only allow outbound traffic through WireGuard VPN interface
- The system MUST allow only one WireGuard endpoint connection
- The system MUST drop all inbound traffic (except keepalive and DHCP)

**FR-3: Minimal User Interface**
- The system MUST boot directly to graphical desktop environment
- The system MUST use IceWM as window manager (lightweight)
- The system MUST launch Remmina automatically on user login
- The system MUST provide only Remmina for remote access (no other remote tools)

**FR-4: Automated Installation**
- The system MUST be installable via bootable ISO
- The system MUST use preseed configuration to automate installation
- The system MUST require user to provide only:
  - Username for user account
  - Password for user account (min 12 chars, complexity requirements)
  - Root password (min 12 chars, complexity requirements)
  - Target disk/partition for installation
- The system MUST automatically configure all other installation settings

### 2.2 Security Requirements

**FR-5: Zero Remote Administration**
- The system MUST NOT allow SSH connections
- The system MUST NOT allow telnet or any other remote administration
- The system MUST disable all remote access services by default

**FR-6: System Hardening**
- The system MUST implement CIS Debian 13 Benchmark controls
- The system MUST enforce Secure Boot with signed bootloader
- The system MUST enable kernel lockdown mode
- The system MUST enforce AppArmor in enforce mode
- The system MUST enable auditd logging for security events
- The system MUST disable core dumps
- The system MUST set strict umask (077)

**FR-7: Integrity Verification**
- The system MUST implement AIDE (Advanced Intrusion Detection Environment)
- The system MUST run AIDE integrity checks periodically
- The system MUST alert on integrity violations

**FR-8: Firewall Configuration**
- The system MUST use nftables/iptables for firewall
- The system MUST implement default DROP policy for INPUT, OUTPUT, FORWARD chains
- The system MUST allow only specific traffic:
  - Loopback traffic
  - WireGuard keepalive packets to endpoint
  - WireGuard tunnel traffic (all VPN traffic)
  - DHCP on physical interface for IP acquisition

### 2.3 System Requirements

**FR-9: Boot Configuration**
- The system MUST support both UEFI and BIOS boot
- The system MUST boot into graphical mode by default
- The system MUST use GRUB2 as bootloader
- The system MUST protect GRUB with password (if configured)

**FR-10: Storage Configuration**
- The system MUST use LVM for logical volume management
- The system MUST support encrypted root filesystem (optional)
- The system MUST use ext4 for root filesystem

**FR-11: System Updates**
- The system MUST allow security updates via APT
- The system MUST NOT install development tools
- The system MUST NOT install unnecessary packages

**FR-12: Logging and Monitoring**
- The system MUST log all security events
- The system MUST log all network connections (via firewall logs)
- The system MUST log all authentication attempts
- The system MUST implement logrotate to manage log sizes

---

## 3. Artifact Properties

### 3.1 ISO Artifact

**Property 1: Bootable ISO**
- File format: ISO 9660 with Rock Ridge extensions
- Boot modes: BIOS (MBR) and UEFI (GPT)
- Size: ~350-400MB (Debian netinst base)
- Architecture: amd64 (x86_64)

**Property 2: Embedded Preseed**
- Preseed file location: `/preseed.cfg` on ISO root
- Preseed loading: Automatic via boot command
- Preseed automation: All installation steps except user/password/disk

**Property 3: Debian Installer Integration**
- Base: Debian 13 (trixie) netinst ISO
- Installer: Standard Debian installer (debootstrap-based)
- Packages: Minimal base system (no GUI initially)

### 3.2 Installed System Properties

**Property 4: Operating System**
- Distribution: Debian 13 (trixie)
- Architecture: amd64 (x86_64)
- Kernel: Linux (latest from Debian 13)
- Init system: systemd

**Property 5: Minimal Footprint**
- Installed packages: < 100 (minimal base)
- Desktop environment: IceWM (lightweight window manager)
- Remote access tools: Remmina only
- Development tools: None
- Services: Systemd, auditd, rsyslog, NetworkManager, WireGuard

**Property 6: Security Hardening**
- Secure Boot: Enabled (signed bootloader)
- SELinux: Not used (AppArmor instead)
- AppArmor: Enforcing mode
- Firewall: nftables with DROP policy
- SSH: Disabled and masked
- Bluetooth: Disabled
- Wireless: Disabled

**Property 7: Network Configuration**
- Physical interface (eth0): DHCP only, VPN keepalive only
- WireGuard interface (wg0): All outbound traffic
- DNS: Via VPN tunnel (no external DNS)
- Routing: Default route via VPN interface

**Property 8: User Account**
- Default username: `user` (set during install)
- Default password: Set during install (min 12 chars)
- Root account: Password protected (set during install)
- Sudo access: Not configured (local admin only)

### 3.3 Deployment Properties

**Property 9: Hardware Requirements**
- Architecture: x86_64 (amd64)
- RAM: Minimum 2GB (4GB recommended for smooth operation)
- Storage: Minimum 8GB (16GB recommended)
- Boot: UEFI preferred, BIOS supported
- Network: Ethernet interface required

**Property 10: Target Environment**
- Deployment: Bare metal laptop or VM
- Location: Physical access-only systems (football-x)
- Network: Must have internet access for VPN connection
- Physical security: Controlled environment (Tier0)

---

## 4. Non-Functional Requirements

### 4.1 Performance

**NFR-1: Boot Time**
- System MUST boot within 30 seconds to login prompt
- System MUST launch desktop within 60 seconds of login

**NFR-2: Network Latency**
- VPN tunnel latency MUST NOT exceed 200ms (typical VPN overhead)
- Remote desktop performance MUST be acceptable (not pixelated or laggy)

**NFR-3: Resource Usage**
- System MUST use < 2GB RAM at idle
- System MUST use < 10GB disk after installation

### 4.2 Reliability

**NFR-4: Uptime**
- System MUST support 24/7 operation without restart (for deployment period)
- System MUST recover gracefully from network failures

**NFR-5: Availability**
- System MUST be available for remote access when VPN is connected
- System MUST NOT crash or hang under normal operation

### 4.3 Usability

**NFR-6: Ease of Use**
- Installation MUST require < 10 minutes of user interaction
- User MUST be able to connect to PAW within 2 minutes of login
- User MUST NOT need to configure system settings

**NFR-7: Maintainability**
- System MUST support security updates via APT
- System MUST allow administrator to add required packages (if needed)
- System MUST provide logs for troubleshooting

### 4.4 Security

**NFR-8: Compliance**
- System MUST meet CIS Debian 13 Benchmark requirements
- System MUST pass automated compliance tests
- System MUST be auditable by external security teams

**NFR-9: Encryption**
- WireGuard tunnel MUST use strong encryption (ChaCha20-Poly1305)
- VPN keys MUST be securely stored (WireGuard config files)
- Optional: Root filesystem encryption support

---

## 5. User Inputs Required

During installation, user MUST provide:

### 5.1 User Account
- **Username**: For non-root user account (e.g., `user`)
- **Password**: Must meet complexity requirements:
  - Minimum 12 characters
  - Mixed case (uppercase and lowercase)
  - At least one number
  - At least one special character

### 5.2 Root Account
- **Password**: Must meet same complexity requirements as user password
- Root access: Local console only (no remote root)

### 5.3 Target Disk
- **Disk selection**: User selects disk/partition for installation
- **Partitioning**: Automated (LVM, no manual configuration)
- **Warning**: All data on selected disk will be wiped

---

## 6. System Components

### 6.1 Core Components
- **Operating System**: Debian 13 (trixie)
- **Kernel**: Linux (latest from Debian 13)
- **Init System**: systemd
- **Bootloader**: GRUB2 (UEFI and BIOS support)

### 6.2 Desktop Components
- **Window Manager**: IceWM
- **Session Manager**: Default X session
- **Auto-start**: Remmina launches on login

### 6.3 Network Components
- **VPN Client**: WireGuard
- **Network Manager**: NetworkManager (for DHCP)
- **Firewall**: nftables/iptables

### 6.4 Security Components
- **Mandatory Access Control**: AppArmor (enforcing)
- **Intrusion Detection**: AIDE
- **Audit Framework**: auditd
- **Secure Boot**: GRUB with signed bootloader

---

## 7. Compliance Requirements

The system MUST comply with:

### 7.1 CIS Benchmarks
- CIS Debian 13 Benchmark (Level 1 controls)
- Configuration reviewed and validated

### 7.2 Security Standards
- NIST SP 800-53 (Moderate impact baseline)
- Industry best practices for secure remote access

### 7.3 Operational Security
- Least privilege: Only necessary components installed
- Defense in depth: Multiple security layers
- Security by default: Secure configuration out of the box

---

## 8. Testing Requirements

The system MUST be tested for:

### 8.1 Installation Testing
- ISO boots successfully on UEFI systems
- ISO boots successfully on BIOS systems
- Preseed configuration works as expected
- User can install system with minimal input

### 8.2 Security Testing
- Firewall rules block unauthorized traffic
- WireGuard tunnel establishes successfully
- SSH and remote access are disabled
- AppArmor is enforcing
- AIDE integrity checks work

### 8.3 Functional Testing
- User can login to desktop
- Remmina launches automatically
- User can connect to PAW via RDP
- System works on bare metal hardware

---

## 9. Verification Strategy

### 9.1 First-Boot Verification (Automatic)

The system automatically runs verification on first boot:

1. **Verification Service**: Systemd service `football-first-boot` runs once on first boot
2. **Verification Script**: `/usr/local/bin/verify-system.sh` checks all functional requirements
3. **Status Tracking**: `/var/lib/football/verification-status` prevents re-running
4. **Logging**: Results logged to `/var/log/football-first-boot-verification.log`

**Verification Checks**:
- FR-1: Remote Access (Remmina, WireGuard, IceWM installed)
- FR-2: Network Isolation (SSH disabled, firewall configured)
- FR-3: Minimal UI (IceWM configured, Remmina auto-starts)
- FR-5: Zero Remote Admin (SSH/telnet disabled)
- FR-6: System Hardening (AppArmor, auditd, AIDE installed)
- FR-7: Integrity (AIDE database and config exist)
- FR-8: Firewall (nftables/iptables installed and enabled)
- FR-9: Boot Config (GRUB and kernel installed)
- FR-10: Storage (LVM installed, root filesystem mounted)
- FR-11: System Updates (APT configured, no dev tools)
- FR-12: Logging (rsyslog, logrotate, auditd configured)

### 9.2 Preseed Integration (Installation)

Verification scripts are embedded in ISO and copied during installation:

**Scripts Baked into ISO**:
- `scripts/verify-system.sh` → `/usr/local/bin/verify-system.sh`
- `config/disable-wifi-bt.sh` → Run during late_command
- `config/football-first-boot.service` → `/etc/systemd/system/`

**Preseed Late_Command Actions**:
1. Disable SSH and SSHD services (mask and disable)
2. Disable Bluetooth service (mask)
3. Run `disable-wifi-bt.sh` script (blacklist kernel modules)
4. Copy `verify-system.sh` to `/usr/local/bin/`
5. Copy `football-first-boot.service` to `/etc/systemd/system/`
6. Enable first-boot verification service
7. Create autostart directory and Remmina autostart file
8. Create `.xinitrc` for IceWM session
9. Set correct permissions on `/home/user`

### 9.3 WiFi and Bluetooth Disabling

Both are completely disabled during installation:

**Kernel Module Blacklisting**:
- `/etc/modprobe.d/disable-wifi.conf`: All WiFi drivers blacklisted
- `/etc/modprobe.d/disable-bluetooth.conf`: All Bluetooth drivers blacklisted

**Service Masking**:
- Bluetooth service masked
- No WiFi services exist

**Package Removal**:
- `bluez`, `bluez-firmware` purged during install

### 9.4 Manual Verification (Optional)

Administrators can run verification manually:

```bash
# Run verification script
/usr/local/bin/verify-system.sh

# Check first-boot verification status
cat /var/lib/football/verification-status

# View verification logs
cat /var/log/football-first-boot-verification.log
```

### 9.5 ISO Verification (Pre-Deployment)

Before deployment, ISO can be tested:

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

# Access VM console
screen -r football-iso-test

# Check for first-boot verification completion
tail -f /output/vm-console.log
```

---

## 10. Acceptance Criteria

The Football Secure Access System is considered production-ready when:

1. **ISO Artifact**:
   - ISO boots on both UEFI and BIOS systems
   - ISO contains embedded preseed configuration
   - ISO is ~350-400MB in size

2. **Installation**:
   - User can install system with < 10 minutes of interaction
   - Installation requires only username, password, root password, disk selection
   - All other steps are automated via preseed

3. **Security**:
   - SSH is disabled
   - Firewall blocks all unauthorized traffic
   - WireGuard tunnel is only network path
   - AppArmor is enforcing
   - System passes CIS Debian 13 Benchmark tests

4. **Functionality**:
   - User can login to IceWM desktop
   - Remmina launches automatically
   - User can connect to PAW via RDP
   - Remote desktop performance is acceptable

5. **Compliance**:
   - System meets all functional requirements
   - System passes all automated tests
   - System is auditable by external security teams

---

## 10. Revision History

| Version | Date | Author | Changes |
|---------|-------|---------|----------|
| 1.0 | 2025-01-20 | Initial functional requirements specification |

---

## Appendix A: Glossary

- **PAW**: Privileged Access Workstation - High-security workstation with administrative access to infrastructure
- **VPN**: Virtual Private Network - Encrypted network tunnel for secure remote access
- **RDP**: Remote Desktop Protocol - Protocol for remote desktop access
- **UEFI**: Unified Extensible Firmware Interface - Modern firmware interface
- **BIOS**: Basic Input/Output System - Legacy firmware interface
- **CIS**: Center for Internet Security - Organization providing security benchmarks
- **AIDE**: Advanced Intrusion Detection Environment - File integrity monitoring tool
- **AppArmor**: Linux Mandatory Access Control system
- **WireGuard**: Modern, high-performance VPN protocol
- **Preseed**: Debian installer automation mechanism

---

## Appendix B: Related Documents

- `docs/BUILD-DOCUMENTATION.md` - Build system documentation
- `docs/SECURITY-BASELINES.md` - Security hardening guide
- `docs/COMPLIANCE.md` - Compliance requirements
- `AGENTS.md` - Project overview and status
- `README.md` - Quick start guide