KNEL/football
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Compare commits

base: KNEL:29654c6cf2fc882f6d725a517bde8337fe4d3c59
Branches Tags
KNEL:main
...
compare: KNEL:ad2d4d3e61e0a88b96a191b9ba894247a6d433b6
Branches Tags
KNEL:main

2 Commits
29654c6cf2 ... ad2d4d3e61

Author SHA1 Message Date
Charles N Wyble
ad2d4d3e61 docs: add architecture diagram and fix FR-001 links 2026-02-19 22:58:14 -05:00
Charles N Wyble
f5bbcad08c docs: add clickable links and update to Debian 13 stable 
- Convert all file references to clickable Markdown links
- Update "Debian Testing base" to "Debian 13 (trixie) stable base"

💘 Generated with Crush

Assisted-by: GLM-5 via Crush <crush@charm.land>
 2026-02-19 22:54:58 -05:00
1 changed files with 64 additions and 34 deletions
Expand all files Collapse all files

98
README.md
View File

@@ -3,29 +3,29 @@
## ⚠️ READ THESE FILES FIRST ## ⚠️ READ THESE FILES FIRST
### 🚀 Quick Start ### 🚀 Quick Start
1. **AGENTS.md** - Current status + critical requirements (START HERE) 1. **[AGENTS.md](AGENTS.md)** - Current status + critical requirements (START HERE)
2. **docs/PRD.md** - Product Requirements Document 2. **[docs/PRD.md](docs/PRD.md)** - Product Requirements Document
3. **README.md** - This file (project overview) 3. **[README.md](README.md)** - This file (project overview)
### 📋 Documentation Files ### 📋 Documentation Files
| File | Purpose | | File | Purpose |
|------|---------| |------|---------|
| **STATUS.md** | 📊 Project status report (manager quick-glance) | | **[STATUS.md](STATUS.md)** | 📊 Project status report (manager quick-glance) |
| **JOURNAL.md** | 📝 AI memory, ADRs, lessons learned (append-only) | | **[JOURNAL.md](JOURNAL.md)** | 📝 AI memory, ADRs, lessons learned (append-only) |
| **AGENTS.md** | ⚡ START HERE - Current status + requirements | | **[AGENTS.md](AGENTS.md)** | ⚡ START HERE - Current status + requirements |
| **docs/PRD.md** | Complete product requirements | | **[docs/PRD.md](docs/PRD.md)** | Complete product requirements |
| **docs/SDLC.md** | Software Development Lifecycle | | **[docs/SDLC.md](docs/SDLC.md)** | Software Development Lifecycle |
| **docs/TEST-COVERAGE.md** | Test suite details and coverage | | **[docs/TEST-COVERAGE.md](docs/TEST-COVERAGE.md)** | Test suite details and coverage |
| **docs/VERIFICATION-REPORT.md** | Security compliance verification | | **[docs/VERIFICATION-REPORT.md](docs/VERIFICATION-REPORT.md)** | Security compliance verification |
### 🔧 Project Files ### 🔧 Project Files
| File | Purpose | | File | Purpose |
|------|---------| |------|---------|
| `run.sh` | Main entry point (build/test/lint/clean/iso) | | [`run.sh`](run.sh) | Main entry point (build/test/lint/clean/iso) |
| `Dockerfile` | Build environment | | [`Dockerfile`](Dockerfile) | Build environment |
| `config/` | Live-build configuration | | [`config/`](config/) | Live-build configuration |
| `tests/` | BATS test suite | | [`tests/`](tests/) | BATS test suite |
| `docs/` | Detailed documentation | | [`docs/`](docs/) | Detailed documentation |
--- ---
@@ -41,17 +41,17 @@
### PRD → Code → Tests Alignment ### PRD → Code → Tests Alignment
| PRD Requirement | Code | Tests | | PRD Requirement | Code | Tests |
|-----------------|------|-------| |-----------------|------|-------|
| FR-001: Full Disk Encryption | encryption-setup.sh, encryption-validation.sh | ✅ 10 test files | | [FR-001: Full Disk Encryption](config/hooks/installed/encryption-setup.sh) | [encryption-setup.sh](config/hooks/installed/encryption-setup.sh), [encryption-validation.sh](config/hooks/installed/encryption-validation.sh) | ✅ 10 test files |
| FR-002: Debian Base | preseed.cfg, package-lists | ✅ config tests | | [FR-002: Debian Base](config/includes.installer/preseed.cfg) | [preseed.cfg](config/includes.installer/preseed.cfg), [package-lists](config/package-lists/) | ✅ config tests |
| FR-003: Desktop Environment | desktop-environment.sh | ✅ 5 test files | | [FR-003: Desktop Environment](config/hooks/live/desktop-environment.sh) | [desktop-environment.sh](config/hooks/live/desktop-environment.sh) | ✅ 5 test files |
| FR-004: Network/Firewall | firewall-setup.sh | ✅ 7 test files | | [FR-004: Network/Firewall](src/firewall-setup.sh) | [firewall-setup.sh](src/firewall-setup.sh) | ✅ 7 test files |
| FR-005: Hardware Control | security-hardening.sh | ✅ 5 test files | | [FR-005: Hardware Control](src/security-hardening.sh) | [security-hardening.sh](src/security-hardening.sh) | ✅ 5 test files |
| FR-006: SSH Client | security-hardening.sh | ✅ 5 test files | | [FR-006: SSH Client](src/security-hardening.sh) | [security-hardening.sh](src/security-hardening.sh) | ✅ 5 test files |
| FR-007: System Hardening | security-hardening.sh | ✅ 9 test files | | [FR-007: System Hardening](src/security-hardening.sh) | [security-hardening.sh](src/security-hardening.sh) | ✅ 9 test files |
| FR-008: USB Automount | usb-automount.sh | ✅ 5 test files | | [FR-008: USB Automount](config/hooks/live/usb-automount.sh) | [usb-automount.sh](config/hooks/live/usb-automount.sh) | ✅ 5 test files |
| FR-009: Immutability | disable-package-management.sh | ✅ 6 test files | | [FR-009: Immutability](config/hooks/installed/disable-package-management.sh) | [disable-package-management.sh](config/hooks/installed/disable-package-management.sh) | ✅ 6 test files |
| FR-010: ISO Build | build-iso.sh, Dockerfile | ✅ 8 test files | | [FR-010: ISO Build](src/build-iso.sh) | [build-iso.sh](src/build-iso.sh), [Dockerfile](Dockerfile) | ✅ 8 test files |
| FR-011: Host FDE | run.sh check | ✅ system tests | | [FR-011: Host FDE](run.sh) | [run.sh](run.sh) check | ✅ system tests |
### Mandatory Requirements Implemented ### Mandatory Requirements Implemented
- ✅ **FR-001: Full Disk Encryption** - LUKS2, AES-256-XTS, 512-bit key - ✅ **FR-001: Full Disk Encryption** - LUKS2, AES-256-XTS, 512-bit key
@@ -117,7 +117,7 @@ Build KNEL-Football secure ISO with Docker-only workflow following AGENTS.md req
### Features ### Features
- **Mandatory Full Disk Encryption** - LUKS2 with AES-256-XTS - **Mandatory Full Disk Encryption** - LUKS2 with AES-256-XTS
- **Mandatory Strong Passwords** - 14+ chars, complexity requirements - **Mandatory Strong Passwords** - 14+ chars, complexity requirements
- Debian Testing base - Debian 13 (trixie) stable base
- IceWM + LightDM desktop - IceWM + LightDM desktop
- WiFi/Bluetooth permanently disabled - WiFi/Bluetooth permanently disabled
- SSH client-only (no server, no inbound access) - SSH client-only (no server, no inbound access)
@@ -126,9 +126,39 @@ Build KNEL-Football secure ISO with Docker-only workflow following AGENTS.md req
- QR code import for WireGuard - QR code import for WireGuard
### Architecture ### Architecture
**IMPORTANT**: KNEL-Football OS serves as a **secure remote terminal** for accessing tier0 infrastructure. It does NOT directly access tier0 infrastructure.
**Access Model**: **See [docs/architecture.md](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) 1. User boots KNEL-Football OS on secure laptop (FDE required)
2. OS connects via WireGuard VPN to secure network 2. OS connects via WireGuard VPN to secure network
3. User uses SSH/Remmina to access privileged workstation 3. User uses SSH/Remmina to access privileged workstation
@@ -341,8 +371,8 @@ License: GNU Affero General Public License v3.0 only
--- ---
**For detailed information, see:** **For detailed information, see:**
- AGENTS.md (START HERE) - [AGENTS.md](AGENTS.md) (START HERE)
- docs/PRD.md (Requirements) - [docs/PRD.md](docs/PRD.md) (Requirements)
- docs/SDLC.md (Development Workflow) - [docs/SDLC.md](docs/SDLC.md) (Development Workflow)
- docs/TEST-COVERAGE.md (Tests) - [docs/TEST-COVERAGE.md](docs/TEST-COVERAGE.md) (Tests)
- docs/VERIFICATION-REPORT.md (Compliance) - [docs/VERIFICATION-REPORT.md](docs/VERIFICATION-REPORT.md) (Compliance)