File	Purpose
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-01-29)

✅ Build Complete

Status: ISO built and verified
Build Date: 2026-01-28 16:30 CST
Duration: 72 minutes (9 stages completed)
ISO: output/knel-football-secure-v1.0.0.iso (450 MB)
Checksums: SHA256 ✅, MD5 ✅

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 (30-60 min)
./run.sh shell            # Interactive shell

Build Commands

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

# Check output
ls -lh output/

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 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:

User boots KNEL-Football OS on secure laptop (FDE required)
OS connects via WireGuard VPN to secure network
User uses SSH/Remmina to access privileged workstation
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:

Read AGENTS.md (current status, requirements)
Read PRD.md (detailed requirements)
Review docs/TEST-COVERAGE.md (test details)

Making Changes:

Read files before editing (Critical!)
Make small, atomic changes
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

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

Total: ~30 minutes on modern hardware

Testing

Test Coverage

11 test files with ~150+ test cases
~95% code coverage (all critical paths tested)
Security requirements: 100% coverage (FR-001, FR-007)

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

Test Results

Unit tests: 7 files covering all shell scripts
Integration tests: 2 files for end-to-end workflows
Security tests: 3 files for FR-001/FR-007 compliance

Quick Reference

Check ISO Status

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

Monitor Build

tail -f /tmp/knel-iso-build.log

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

For detailed information, see:

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

Description

Fully self contained , very stripped and locked down Debian image intended for deployment onto physical access only system (Dell Laptop) (called football-(x) to be used for remote (RDP) access to another high security physical system (highside) which is a privileged access workstation in the KNEL server room.

Readme 803 KiB