KNEL-Football Secure OS

⚠️ READ THESE FILES FIRST

🚀 Quick Start

1. AGENTS.md - Current status + critical requirements (START HERE)
2. docs/PRD.md - Product Requirements Document
3. README.md - This file (project overview)

📋 Documentation Files

File	Purpose
STATUS.md	📊 Project status report (manager quick-glance)
JOURNAL.md	📝 AI memory, ADRs, lessons learned (append-only)
AGENTS.md	⚡ START HERE - Current status + requirements
docs/PRD.md	Complete product requirements
docs/SDLC.md	Software Development Lifecycle
docs/TEST-COVERAGE.md	Test suite details and coverage
docs/VERIFICATION-REPORT.md	Security compliance verification

🔧 Project Files

File	Purpose
run.sh	Main entry point (build/test/lint/clean/iso)
Dockerfile	Build environment
config/	Live-build configuration
tests/	BATS test suite
docs/	Detailed documentation

---

Project Status (2026-02-19)

✅ Ready to Build ISO

• Status: All 562 tests passing, PRD fully aligned, ready for ISO build
• Test Files: 20 test files (unit, integration, security, system)
• PRD Coverage: 100% (FR-001 through FR-011)
• Code Quality: 0 TODO/FIXME, 0 shellcheck warnings
• Next Step: Run ./run.sh iso to build

PRD → Code → Tests Alignment

PRD Requirement	Code	Tests
FR-001: Full Disk Encryption	encryption-setup.sh, encryption-validation.sh	✅ 10 test files
FR-002: Debian Base	preseed.cfg, package-lists	✅ config tests
FR-003: Desktop Environment	desktop-environment.sh	✅ 5 test files
FR-004: Network/Firewall	firewall-setup.sh	✅ 7 test files
FR-005: Hardware Control	security-hardening.sh	✅ 5 test files
FR-006: SSH Client	security-hardening.sh	✅ 5 test files
FR-007: System Hardening	security-hardening.sh	✅ 9 test files
FR-008: USB Automount	usb-automount.sh	✅ 5 test files
FR-009: Immutability	disable-package-management.sh	✅ 6 test files
FR-010: ISO Build	build-iso.sh, Dockerfile	✅ 8 test files
FR-011: Host FDE	run.sh check	✅ system tests

Mandatory Requirements Implemented

• ✅ FR-001: Full Disk Encryption - LUKS2, AES-256-XTS, 512-bit key
• ✅ FR-007: Password Complexity - 14+ chars, PAM pwquality enforced

---

Quick Commands

Project Management

./run.sh build            # Build Docker image
./run.sh test             # Run all tests
./run.sh test:unit        # Run unit tests only
./run.sh test:integration  # Run integration tests only
./run.sh test:security     # Run security tests only
./run.sh lint             # Check scripts
./run.sh clean            # Remove artifacts
./run.sh iso              # Build ISO (60-90 min)
./run.sh monitor          # Monitor build progress
./run.sh shell            # Interactive shell

VM Testing (requires libvirt)

./run.sh test:iso check        # Check prerequisites
./run.sh test:iso create       # Create and start test VM (UEFI/Secure Boot)
./run.sh test:iso console      # Connect to VM console
./run.sh test:iso status       # Show VM status
./run.sh test:iso destroy      # Destroy VM and cleanup
./run.sh test:iso boot-test    # Run automated boot test

Build Commands

# Monitor ISO build
tail -f /tmp/knel-iso-build.log

# Check output
ls -lh output/

First-Time Setup (After Cloning)

# Configure git hooks (required for SDLC enforcement)
./scripts/setup-githooks.sh

SDLC Workflow (MANDATORY)

# After ANY changes:
./run.sh lint              # Check syntax
./run.sh test              # Run full test suite
./run.sh test:security     # Verify security requirements

# Then commit:
git add <files>
git commit -m "type: subject"
git push origin main

---

Project Overview

Goal

Build KNEL-Football secure ISO with Docker-only workflow following AGENTS.md requirements.

Features

• Mandatory Full Disk Encryption - LUKS2 with AES-256-XTS
• Mandatory Strong Passwords - 14+ chars, complexity requirements
• Debian 13 (trixie) stable base
• IceWM + LightDM desktop
• WiFi/Bluetooth permanently disabled
• SSH client-only (no server, no inbound access)
• Firewall rules (all inbound denied, outbound VPN only)
• USB automount support
• QR code import for WireGuard

Architecture

See docs/architecture.md for complete system architecture.

┌─────────────────────────────────────────────────────────────────┐
│                    Development Environment                      │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────┐     │
│  │     Git     │  │   Docker    │  │     Libvirt         │     │
│  │   (VCS)     │  │ (Builder)   │  │ (Virtualization)    │     │
│  └─────────────┘  └─────────────┘  └─────────────────────┘     │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                   Build Container                               │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐              │
│  │ live-build  │  │ debootstrap │  │  shellcheck │              │
│  │   (ISO)     │  │ (Bootstrap) │  │  (Linting)  │              │
│  └─────────────┘  └─────────────┘  └─────────────┘              │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                   Output: KNEL-Football ISO                     │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐              │
│  │   IceWM     │  │  WireGuard  │  │   LUKS2     │              │
│  │  (Desktop)  │  │    (VPN)    │  │ (Encryption)│              │
│  └─────────────┘  └─────────────┘  └─────────────┘              │
└─────────────────────────────────────────────────────────────────┘

Access Model: KNEL-Football OS serves as a secure remote terminal for accessing tier0 infrastructure:

1. User boots KNEL-Football OS on secure laptop (FDE required)
2. OS connects via WireGuard VPN to secure network
3. User uses SSH/Remmina to access privileged workstation
4. Privileged workstation (physical) accesses tier0 infrastructure

Security Requirements (MANDATORY)

• Full disk encryption with LUKS2 (AES-256-XTS, 512-bit key)
• Encryption passphrase required at every boot (14+ characters)
• Password complexity enforced (14+ chars, mix of classes)
• All security requirements tested and verified

Compliance

• NIST SP 800-111 (Disk Encryption)
• NIST SP 800-53 (Security Controls)
• NIST SP 800-63B (Password Guidelines)
• ISO/IEC 27001 (Information Security)
• CIS Benchmarks (Security Configuration)
• DISA STIG (Security Implementation)

---

Documentation Structure

README.md (Main Entry Point)
  ├── ⚠️ READ THESE FILES FIRST
  │   ├── AGENTS.md (START HERE - Current Status)
  │   ├── docs/PRD.md (Requirements)
  │   ├── docs/SDLC.md (Development Workflow)
  │   ├── docs/TEST-COVERAGE.md (Test Details)
  │   └── docs/VERIFICATION-REPORT.md (Verification Results)
  ├── Quick Commands
  ├── Project Overview
  ├── Architecture
  ├── Security Requirements
  └── Compliance

---

Directory Structure

football/
├── AGENTS.md              # START HERE - Agent guidelines
├── README.md              # This file
├── Dockerfile             # Build environment
├── run.sh                # Main entry point
├── config/                # Live-build configuration
│   ├── preseed.cfg        # Debian installer preseed (with encryption)
│   ├── hooks/
│   │   ├── live/         # Hooks during live system
│   │   └── installed/    # Hooks after installation
│   └── package-lists/
├── src/                   # Source scripts
│   ├── security-hardening.sh
│   ├── firewall-setup.sh
│   ├── build-iso.sh
│   └── run.sh
├── tests/                 # BATS test suite
│   ├── unit/             # Unit tests for scripts
│   ├── integration/      # Integration tests for workflows
│   ├── security/         # Security compliance tests
│   └── test_helper/      # Test utilities
├── docs/                  # Detailed documentation
│   ├── PRD.md            # Product Requirements
│   ├── SDLC.md           # Software Development Lifecycle
│   ├── TEST-COVERAGE.md
│   └── VERIFICATION-REPORT.md
├── output/                # ISO artifacts (ISO, checksums)
└── .gitignore

---

Development Workflow

Software Development Lifecycle (SDLC)

Before Making Changes:

1. Read AGENTS.md (current status, requirements)
2. Read docs/PRD.md (detailed requirements)
3. Read docs/SDLC.md (development workflow)
4. Review docs/TEST-COVERAGE.md (test details)

Making Changes:

1. Read files before editing (Critical!)
2. Make small, atomic changes
3. Follow existing code style

Testing Changes (MANDATORY):

./run.sh lint              # Syntax validation
./run.sh test:unit         # Unit tests
./run.sh test:integration  # Integration tests
./run.sh test:security     # Security tests
./run.sh test              # Full test suite

Committing:

git add <files>
git commit -m "type: subject"
git push origin main

Commit Types:

• feat: New feature
• fix: Bug fix
• docs: Documentation changes
• test: Test changes
• refactor: Code refactoring
• chore: Maintenance tasks

---

Build Process

Docker Workflow (MANDATORY)

• ALL operations run inside Docker containers
• ONLY use Docker volumes for file operations
• NEVER create directories in user home directory
• NEVER modify host system files directly
• ONLY final artifacts copied to host system

Build Stages

1. Docker Build - Create build environment (~2 minutes)
2. lb config - Configure live-build (~30 seconds)
3. lb bootstrap - Download/install base system (~13 minutes)
4. lb chroot - Install packages and apply hooks (~8 minutes)
5. lb installer - Configure Debian installer (~2 minutes)
6. lb binary - Create binary filesystem (~4 minutes)
7. lb checksum - Generate checksums (~1 minute)

Total: ~30 minutes on modern hardware

---

Testing

Test Coverage

• 20 test files with 562 test cases
• 100% PRD coverage (FR-001 through FR-011)
• All tests passing - no failures, no skips (except VM-dependent)
• 0 shellcheck warnings

Running Tests

./run.sh test              # All tests
./run.sh test:unit         # Unit tests
./run.sh test:integration  # Integration tests
./run.sh test:security     # Security compliance tests
./run.sh test:system       # System tests (static analysis)

Test Results

• Unit tests: ~200 tests covering all shell scripts
• Integration tests: ~100 tests for end-to-end workflows
• Security tests: ~150 tests for FR-001/FR-007 compliance
• System tests: ~112 tests (static analysis always passes, VM tests skip gracefully)

---

Quick Reference

Check ISO Status

ls -lh output/
sha256sum -c output/*.sha256
md5sum -c output/*.md5

Monitor Build

./run.sh monitor              # Monitor build progress (checks every 3 min)
tail -f /tmp/knel-iso-build.log  # Or watch the log directly

Clean Up

./run.sh clean    # Remove artifacts
./run.sh test     # Run tests
./run.sh lint     # Check scripts

---

Contributing

Requirements

• Docker installed
• No host system modifications
• Follow SDLC workflow
• Run full test suite before committing
• Use conventional commit messages

Security

• All changes must preserve mandatory security requirements
• Full disk encryption cannot be disabled or weakened
• Password complexity requirements cannot be reduced
• Security tests must pass

---

License

Copyright © 2026 Known Element Enterprises LLC License: GNU Affero General Public License v3.0 only

---

For detailed information, see:

• AGENTS.md (START HERE)
• docs/PRD.md (Requirements)
• docs/SDLC.md (Development Workflow)
• docs/TEST-COVERAGE.md (Tests)
• docs/VERIFICATION-REPORT.md (Compliance)