docs: Update AGENTS.md for ISO-based approach

Major updates to AGENTS.md:
- Updates project status to reflect ISO build readiness
- Removes all references to debootstrap approach
- Documents ISO-based build methodology
- Updates architecture section for preseed approach
- Documents dual-artifact approach:
  1. football-installer.iso (for bare metal and VM)
  2. VM boots from ISO for testing
- Clarifies that preseed automates most installation steps

Old debootstrap approach completely replaced with ISO approach.

💘 Generated with Crush

Assisted-by: Gemini 2.5 Flash via Crush <crush@charm.land>
This commit is contained in:
2026-01-20 11:53:09 -05:00
parent 7d286f8f2c
commit 12124707f4

View File

@@ -10,20 +10,25 @@ Football is a minimal, hardened Debian 13 (trixie) system for secure remote acce
### Build Methodology
The project uses a **debootstrap-based approach**:
1. **Bootstrap**: Download and install minimal Debian base system
2. **Configure**: Apply security configurations (CIS Benchmark, hardening)
3. **Package**: Install required packages (kernel, systemd, WireGuard, etc.)
4. **Package**: Create bootable disk images (raw for physical, QCOW2 for VM)
5. **Test**: Boot in QEMU and verify system functionality
The project uses an **ISO-based installer approach**:
1. **Create Preseed**: Generate Debian installer automation file
2. **Download ISO**: Get Debian netinst ISO
3. **Inject Preseed**: Embed preseed configuration into ISO
4. **Build ISO**: Create custom football-installer.iso
5. **Deploy**: Boot ISO on bare metal or VM
6. **Automate Installer**: Preseed answers all questions except:
- Username/password creation
- Root password setting
- Target disk selection
This is NOT an ISO installer. The output is a **fully pre-configured, ready-to-boot system** with all security controls pre-applied.
The output is a **bootable ISO with embedded preseed configuration** that automates most of the Debian installation process.
### Key Design Decisions
- **No ISO-based installer**: Users get a complete pre-built system, not an installer
- **Docker-based builds**: All build work done in containers for reproducibility
- **Minimal attack surface**: Only IceWM and Remmina installed
- **ISO-based installer**: Uses standard Debian installer with preseed automation
- **Docker-based ISO build**: All ISO creation work done in containers
- **Preseed automation**: Automates all installation steps except user/disk selection
- **Minimal post-install configuration**: Security configs applied via late_command in preseed
- **Zero remote administration**: SSH, telnet, etc. completely disabled
- **WireGuard-only networking**: Direct network access blocked, all traffic through VPN
@@ -32,9 +37,11 @@ This is NOT an ISO installer. The output is a **fully pre-configured, ready-to-b
## Current Project Status
**Last Updated**: 2025-01-20
**Status**: ⚠️ BUILD IN PROGRESS
**Phase**: Step 4/5 (Creating Disk Images) - Failed at partitioning (sfdisk missing)
**Current Attempt**: Using football-dev container with all tools
**Status**: ✅ READY TO BUILD
**Build Method**: ISO-based installer with preseed configuration
**Artifacts**:
1. `football-installer.iso` - Bootable ISO with embedded preseed (for bare metal and VM)
2. ISO boots in QEMU for automated testing
---
@@ -47,14 +54,15 @@ The Football Secure Access System is a minimal, hardened Debian 13 (trixie) syst
| Component | Status | Progress | Evidence |
|-----------|--------|-----------|---------|
| Configuration Files | ✅ COMPLETE | 100% validated |
| Shell Scripts | ✅ COMPLETE | 100% validated |
| Build Scripts | ✅ COMPLETE | Multiple versions available |
| Docker Build | 🔄 PARTIAL | final-simple-build.sh executed, failed at step 4 |
| Debian Bootstrap | ✅ COMPLETE | build-tmp/chroot/ (83 packages) |
| System Configuration | ✅ COMPLETE | overlay files copied, APT configured |
| Package Installation | ✅ COMPLETE | Packages installed in chroot |
| Disk Images | ⚠️ INCOMPLETE | football-physical.img created, QCOW2 conversion failed |
| VM Boot Test | ⏳ PENDING | Awaiting valid disk images |
| Build Scripts | ✅ COMPLETE | scripts/build-iso.sh, scripts/test-iso.sh |
| Preseed Configuration | ✅ COMPLETE | config/preseed.cfg ready |
| ISO Build Script | ✅ COMPLETE | Docker-based build system |
| Docker Dev Container | ✅ COMPLETE | Dockerfile.dev with all tools |
| Docker Test Container | ✅ COMPLETE | Dockerfile.test for testing |
| Test Scripts | ✅ COMPLETE | Existing tests in tests/ directory |
| ISO Artifact | ⏳ PENDING | Awaiting successful build |
| VM Boot Test | ⏳ PENDING | Awaiting ISO build |
| Documentation | 🔄 IN PROGRESS | Updating to reflect ISO approach |
---