football/JOURNAL.md

KNEL-Football Development Journal

Important

: This file is APPEND-ONLY. Never delete or modify existing entries. Add new entries at the TOP (after this header) with date and context. This serves as long-term memory for AI agents and human developers.

---

Entry 2026-02-17: Project Assessment and Test Coverage Analysis

Context

Comprehensive project review after session handoff. User requested full orientation and 100% test coverage including VM boot tests, Secure Boot, and FDE runtime tests.

Insights

1. Test Infrastructure Pattern

   • BATS tests work well for static analysis but lack runtime verification
   • Current tests validate file existence and content, not actual behavior
   • Missing entire category: system/integration tests that boot the ISO

2. Docker-Only Workflow is Correct

   • All build/test commands run inside Docker containers
   • Prevents host system pollution
   • Makes builds reproducible across environments
   • Volumes: /workspace (read-only), /build (temp), /output (artifacts)

3. Shellcheck Warnings Are Non-Critical

   • SC2120/SC2119: Functions don't use arguments but called without "$@"
   • SC1091: Source files not available during shellcheck (exist at runtime)
   • Pattern: Functions generate config, don't need arguments

Architectural Decision Records (ADRs)

ADR-001: Two-Tier Security Model

Date: 2026-01-28 (documented 2026-02-17) Status: Accepted

Context: How should KNEL-Football OS access tier0 infrastructure?

Decision: KNEL-Football OS is a secure remote terminal, NOT direct tier0 access. Flow: KNEL-Football OS → WireGuard VPN → Privileged Access Workstation → Tier0

Rationale:

• Defense in depth - multiple hops before tier0
• Compromise of laptop doesn't directly expose tier0
• WireGuard provides encrypted tunnel
• Physical workstation adds another security layer

Consequences:

• Network configuration focuses on WireGuard only
• WiFi/Bluetooth permanently disabled
• SSH configured for key-based auth only

ADR-002: Docker-Only Build Environment

Date: 2026-01-28 (documented 2026-02-17) Status: Accepted

Context: How should ISO builds be executed?

Decision: ALL build operations run inside Docker containers. No host modifications.

Rationale:

• Reproducible builds across different host systems
• No pollution of host environment
• Easy cleanup (just remove containers/images)
• CI/CD friendly

Consequences:

• run.sh wraps all commands with docker run
• ISO build requires --privileged for loop devices
• Output artifacts copied via volume mounts

ADR-003: LUKS2 Over LUKS1

Date: 2026-01-28 (documented 2026-02-17) Status: Accepted

Context: Which disk encryption format to use?

Decision: Use LUKS2 with Argon2id KDF, AES-256-XTS cipher, 512-bit key.

Rationale:

• LUKS2 is newer, more secure format
• Argon2id resists GPU/ASIC attacks better than PBKDF2
• AES-XTS is NIST-approved for disk encryption
• 512-bit key provides security margin

Consequences:

• Modern systems only (older grub may not support)
• Boot requires passphrase entry
• No recovery without passphrase

ADR-004: BATS Without External Libraries

Date: 2026-01-28 (documented 2026-02-17) Status: Accepted

Context: BATS test framework libraries were failing to load.

Decision: Remove bats-support, bats-assert, bats-file dependencies. Use custom assertion functions in tests/test_helper/common.bash.

Rationale:

• External library loading was unreliable
• Custom functions provide same functionality
• Fewer dependencies = fewer failure points
• Easier to debug when tests fail

Consequences:

• Custom assertions must be maintained
• Tests don't benefit from upstream library fixes
• But: simpler, more predictable behavior

Patterns Observed

1. Hook Organization

   • config/hooks/live/ - Runs during live session (before install)
   • config/hooks/installed/ - Runs after installation
   • Pattern: Source shared functions, call main function

2. Script Structure

   #!/bin/bash
   set -euo pipefail
   # Functions that generate config
   main() { ... }
   # Call main if script executed directly
   

3. Test Structure

   #!/usr/bin/env bats
   @test "description" {
       # Setup
       # Exercise
       # Verify
   }
   

Lessons Learned

1. test:iso Command Was Broken

   • run.sh:172 references deleted test-iso.sh
   • Commit c1505a9 removed obsolete scripts including test-iso.sh
   • But run.sh was not updated to remove the command
   • Lesson: When removing files, search for all references

2. Preseed.cfg Has Hardcoded Passwords

   • Lines 28-31 contain default passwords
   • These are installer defaults, should be changed on first boot
   • Security risk if users don't change them
   • Lesson: Consider using installer prompts instead

3. Test Coverage Claim vs Reality

   • Documentation claimed 95% coverage
   • Reality: 100% static analysis, 0% runtime/VM testing
   • Lesson: Be precise about what "coverage" means

Action Items for Future Sessions

1. Implement VM boot tests using libvirt
2. Add Secure Boot support (shim-signed, grub-efi-amd64-signed)
3. Create runtime FDE passphrase prompt tests
4. Remove hardcoded passwords from preseed.cfg
5. Fix shellcheck warnings (low priority, non-critical)

---

Entry 2026-01-28: Initial Build Completion

Context

First successful ISO build completed after 72 minutes.

Insights

1. Live-Build Stages

   • bootstrap: Downloads base system (longest stage)
   • chroot: Installs packages, runs hooks
   • binary: Creates ISO filesystem
   • checksum: Generates SHA256/MD5

2. Build Time Breakdown

   • Total: ~72 minutes
   • bootstrap: ~40 minutes (network dependent)
   • chroot: ~20 minutes
   • binary: ~10 minutes

3. ISO Size

   • Final ISO: 450 MB
   • Includes: Debian base, IceWM, WireGuard, security tools
   • Reasonable size for secure workstation

Patterns

1. Docker Volume Strategy

   • /workspace mounted read-only (source code)
   • /build for intermediate files
   • /output for final artifacts
   • Prevents accidental modification of source

2. Checksum Generation

   • Generate both SHA256 and MD5
   • Name checksum files after ISO
   • Copy to output directory with ISO

---

End of Journal. Add new entries at the top.