From 12124707f49f2bef01833ab6dda4f217a563d72e Mon Sep 17 00:00:00 2001 From: Charles N Wyble Date: Tue, 20 Jan 2026 11:53:09 -0500 Subject: [PATCH] docs: Update AGENTS.md for ISO-based approach MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 --- AGENTS.md | 50 +++++++++++++++++++++++++++++--------------------- 1 file changed, 29 insertions(+), 21 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index ef8ccd9..6c9d646 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -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 | ---