diff --git a/docs/BUILD-DOCUMENTATION.md b/docs/BUILD-DOCUMENTATION.md new file mode 100644 index 0000000..6a7ed53 --- /dev/null +++ b/docs/BUILD-DOCUMENTATION.md @@ -0,0 +1,278 @@ +# Football ISO Build Documentation + +## Overview + +Football uses an ISO-based installer approach with embedded preseed configuration. The build system creates a bootable Debian installer ISO that automates most of the installation process. + +## Directory Structure + +``` +football/ +├── AGENTS.md # Main project documentation (AI agent reference) +├── README.md # Quick start guide +├── LICENSE # License file +├── .gitignore # Git ignore rules +├── .dockerignore # Docker ignore rules +│ +├── scripts/ # Build and test scripts +│ ├── build-iso.sh # Main ISO build script (Docker-based) +│ └── test-iso.sh # ISO testing script (QEMU VM boot) +│ +├── config/ # Configuration files +│ └── preseed.cfg # Debian preseed automation file +│ +├── docs/ # Documentation +│ ├── COMPLIANCE.md # Compliance requirements +│ ├── INCIDENT-RESPONSE.md # Incident response procedures +│ ├── SECURITY-BASELINES.md # Security baselines +│ ├── SECURITY-POLICY.md # Security policies +│ ├── TEST-EVIDENCE.md # Test evidence and results +│ └── old/ # Archived old documentation +│ +├── tests/ # Test scripts +│ ├── verify-compliance.sh # Compliance verification +│ ├── compliance-test.sh # Full compliance test suite +│ └── build-and-test.sh # VM-based testing +│ +├── keys/ # WireGuard keys (generated by users) +│ +├── logs/ # Build and test logs +│ +├── output/ # Build output artifacts +│ └── football-installer.iso (generated by build-iso.sh) +│ +├── iso-tmp/ # Temporary ISO build directory (in .gitignore) +│ +├── Dockerfile.dev # Fat development container +└── Dockerfile.test # Test container +``` + +## Build Process + +### Step 1: Create Preseed Configuration + +The `config/preseed.cfg` file contains Debian installer automation: + +- **Automated Steps** (no user interaction required): + - Locale and language settings + - Network configuration (DHCP) + - Partitioning (LVM, auto) + - Timezone + - Package selection + - Boot loader installation + +- **Manual Steps** (user must provide): + - Username creation + - User password (min 12 chars, mixed case, numbers, special chars) + - Root password (min 12 chars, mixed case, numbers, special chars) + - Target disk/partition selection + +### Step 2: Build ISO + +Run `./scripts/build-iso.sh` which: + +1. **Downloads Debian ISO** (in Docker) + - Fetches Debian netinst ISO from official mirrors + - Uses sid/testing (Debian 13 is still testing) + +2. **Extracts ISO** (in Docker) + - Extracts ISO contents to temporary directory + - Preserves ISO structure + +3. **Injects Preseed** (in Docker) + - Copies `config/preseed.cfg` to ISO root + - Modifies `isolinux/isolinux.cfg` to auto-load preseed + - Sets default boot to use preseed configuration + +4. **Recreates ISO** (in Docker) + - Uses xorriso to create new hybrid ISO + - Supports both BIOS and UEFI boot + - Preserves all Debian installer features + +5. **Verifies ISO** (in Docker) + - Checks ISO file exists + - Verifies file size and type + +Output: `output/football-installer.iso` + +### Step 3: Test ISO + +Run `./scripts/test-iso.sh` which: + +1. **Creates Test Disk** (in Docker) + - Creates 16GB QCOW2 disk for VM + - Used for testing installation + +2. **Boots VM** (on host, using screen) + - Boots QEMU with 2GB RAM, 2 CPUs + - Uses `output/football-installer.iso` as boot device + - Creates 16GB test disk for installation + - Runs in background with screen session + - Saves console output to `output/vm-console.log` + +3. **Monitors Installation** + - Waits 120 seconds for installer to start + - Checks for installation prompts + - Monitors for errors or kernel panic + +Access VM console: `screen -r football-iso-test` +Detach from VM: `Ctrl+A`, then `D` + +## Deployment + +### Bare Metal Deployment + +1. **Write ISO to USB** + ```bash + sudo dd if=output/football-installer.iso of=/dev/sdX bs=4M status=progress + sync + ``` + +2. **Boot from USB** + - Enter BIOS/UEFI + - Select USB as boot device + +3. **Run Installer** + - Preseed auto-answers most questions + - Provide only: + - Username + - Password + - Root password + - Target disk + +4. **Post-Install Configuration** + - Security configurations applied via preseed late_command + - WireGuard configured + - Firewall rules applied + - Services configured + +### Virtual Machine Deployment + +1. **Create VM Disk** + ```bash + qemu-img create -f qcow2 football-disk.qcow2 16G + ``` + +2. **Boot VM from ISO** + ```bash + qemu-system-x86_64 \ + -m 2048 \ + -smp 2 \ + -drive file=football-disk.qcow2,format=qcow2 \ + -drive file=output/football-installer.iso,media=cdrom,readonly=on \ + -boot d + ``` + +3. **Run Installer** + - Same process as bare metal + +## Docker Containers + +### football-dev (Dockerfile.dev) + +Fat development container with all build tools: + +- `debootstrap` - Debian bootstrap tool +- `qemu-utils` - QEMU disk utilities +- `qemu-system-x86_64` - QEMU system emulator +- `grub-*` - GRUB bootloader tools +- `parted`, `fdisk`, `sfdisk` - Partitioning tools +- `xorriso` - ISO creation tool +- `wireguard` - WireGuard tools +- All other required build utilities + +Usage: +```bash +docker build -t football-dev -f Dockerfile.dev . +docker run --rm -it -v "$PWD:/project" football-dev bash +``` + +### football-test (Dockerfile.test) + +Lightweight test container for running tests: + +- `bash` - Shell +- `shellcheck` - Shell script linting +- `shunit2` - Bash unit testing +- Basic utilities + +Usage: +```bash +docker build -t football-test -f Dockerfile.test . +docker run --rm -v "$PWD:/test" football-test ./tests/verify-compliance.sh +``` + +## Security Features + +Applied during installation via preseed: + +1. **Network Isolation** + - All inbound traffic blocked + - WireGuard-only outbound traffic + - Mandatory VPN tunnel + +2. **Service Restrictions** + - SSH disabled and masked + - All remote access services removed + - Bluetooth disabled + +3. **System Hardening** + - Secure Boot enabled + - AppArmor enforcing + - Auditd logging enabled + - Fail2Ban configured + +4. **Minimal Attack Surface** + - Only IceWM and Remmina installed + - No development tools + - Minimal command-line utilities + +## Troubleshooting + +### Build Issues + +**Problem**: ISO download fails +- **Solution**: Check network connectivity and Debian mirror availability + +**Problem**: ISO creation fails +- **Solution**: Check xorriso installation in container + +**Problem**: Preseed not working +- **Solution**: Check `config/preseed.cfg` syntax and boot command + +### Test Issues + +**Problem**: VM won't boot from ISO +- **Solution**: Check ISO file integrity and QEMU boot order + +**Problem**: Installer not using preseed +- **Solution**: Check ISO boot command in `isolinux/isolinux.cfg` + +**Problem**: Screen session issues +- **Solution**: Ensure screen is installed and properly configured + +## Next Steps + +After successful build and test: + +1. **Deploy to target systems** + - Write ISO to USB + - Boot on bare metal or VM + - Complete installation with preseed + +2. **Customize for environment** + - Update WireGuard configuration + - Add required packages + - Adjust security policies + +3. **Verify compliance** + - Run `./tests/verify-compliance.sh` + - Run `./tests/compliance-test.sh` + - Document test results + +## References + +- [Debian Preseed Documentation](https://www.debian.org/releases/stable/amd64/apbs02.html.en) +- [CIS Debian Benchmark](https://www.cisecurity.org/benchmark/debian_linux) +- [WireGuard Documentation](https://www.wireguard.com/docs/) +- [Debian 13 (Trixie) Release Notes](https://www.debian.org/releases/trixie/releasenotes)