football/README.md

# KNEL-Football Secure OS

## ⚠️ READ THESE FILES FIRST

### 🚀 Quick Start
1. **AGENTS.md** - Current status + critical requirements (START HERE)
2. **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 |
| **PRD.md** | Complete product requirements |
| **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-17)

### ✅ Build In Progress
- **Status**: ISO rebuilding with latest security changes
- **Build Started**: 2026-02-17 14:28 CST
- **ISO**: `output/knel-football-secure.iso`
- **Changes**: Removed hardcoded passwords from preseed, force installer prompts

### 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
```bash
./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)
```bash
./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
```bash
# Monitor ISO build
tail -f /tmp/knel-iso-build.log

# Check output
ls -lh output/
```

### SDLC Workflow (MANDATORY)
```bash
# 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 Testing base
- IceWM + LightDM desktop
- WiFi/Bluetooth permanently disabled
- SSH with wireguard keys
- Firewall rules (inbound SSH, outbound VPN only)
- USB automount support
- QR code import for WireGuard

### Architecture
**IMPORTANT**: KNEL-Football OS serves as a **secure remote terminal** for accessing tier0 infrastructure. It does NOT directly access tier0 infrastructure.

**Access Model**:
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)
  │   ├── PRD.md (Requirements)
  │   ├── 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
├── PRD.md                # Product Requirements
├── 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
│   ├── 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 PRD.md (detailed requirements)
3. 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)**:
```bash
./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**:
```bash
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
- **19 test files** with 111 test cases
- **~95% code coverage** (all critical paths tested)
- **Security requirements**: 100% coverage (FR-001, FR-007)

### Running Tests
```bash
./run.sh test              # All tests
./run.sh test:unit         # Unit tests
./run.sh test:integration  # Integration tests
./run.sh test:security     # Security compliance tests
```

### Test Results
- Unit tests: 12 tests covering all shell scripts
- Integration tests: 6 tests for end-to-end workflows
- Security tests: 44 tests for FR-001/FR-007 compliance
- System tests: 47 tests (static analysis, skip without VM)

---

## Quick Reference

### Check ISO Status
```bash
ls -lh output/
sha256sum -c output/*.sha256
md5sum -c output/*.md5
```

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

### Clean Up
```bash
./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)
- PRD.md (Requirements)
- docs/TEST-COVERAGE.md (Tests)
- docs/VERIFICATION-REPORT.md (Compliance)