f7fc16b5c5
- Add comprehensive PRD → Code → Tests alignment table - Update test counts (562 tests, 20 test files) - Document 100% PRD coverage (FR-001 through FR-011) - Update project status to "Ready to Build ISO" - Note 0 TODO/FIXME and 0 shellcheck warnings 💘 Generated with Crush Assisted-by: GLM-4.7 via Crush <crush@charm.land>
349 lines
11 KiB
Markdown
349 lines
11 KiB
Markdown
# 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
|
|
```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 client-only (no server, no inbound access)
|
|
- Firewall rules (all inbound denied, 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)
|
|
│ ├── 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)**:
|
|
```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
|
|
- **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
|
|
```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
|
|
./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
|
|
```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)
|
|
- docs/PRD.md (Requirements)
|
|
- docs/SDLC.md (Development Workflow)
|
|
- docs/TEST-COVERAGE.md (Tests)
|
|
- docs/VERIFICATION-REPORT.md (Compliance)
|