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 with preseed automation
• 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:

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

# 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