diff --git a/README.md b/README.md index d2c3280..7a07b4e 100644 --- a/README.md +++ b/README.md @@ -1,190 +1,166 @@ -# KNEL-Football +# KNEL-Football Secure OS -

- License: AGPLv3 - Debian 13 - Build: Docker - Security: Strict -

+## ⚠️ READ THESE FILES FIRST -## Overview +### 🚀 Quick Start +1. **AGENTS.md** - Current status + critical requirements (START HERE) +2. **RESUME.md** - Complete resumption guide +3. **QUICK_START.md** - Quick reference commands -KNEL-Football is a highly secure, compliant Debian 13 (Trixie) installation ISO built using a strict Docker-based workflow with Test-Driven Development methodology. The resulting ISO provides a minimal, hardened system with restricted networking designed for tier0 infrastructure access. +### 📋 Documentation Files +| File | Purpose | +|------|---------| +| **AGENTS.md** | ⚡ START HERE - Current status + requirements | +| **RESUME.md** | Complete resumption guide + build history | +| **QUICK_START.md** | Quick commands and status | +| **JOURNAL.md** | Append-only development journal | -## Features - -### Security Hardening -- ✅ CMMC Level 3 compliant -- ✅ FedRAMP LI-SaaS ready -- ✅ DISA STIG and CIS Benchmark implementation -- ✅ WiFi and Bluetooth permanently disabled (kernel blacklist) -- ✅ Package management tools disabled with immutable permissions -- ✅ Secure Boot with measured boot (UEFI only) - -### Network Restrictions -- ✅ WireGuard-only network access -- ✅ Dynamic firewall configuration (nftables) -- ✅ No general internet connectivity -- ✅ QR code import for configuration - -### Minimal Desktop -- ✅ IceWM window manager (minimal) -- ✅ LightDM display manager (privacy mode) -- ✅ Required applications: Remmina, WireGuard, Mousepad, PCManFM -- ✅ USB automount support - -## Quick Start - -### Prerequisites -- Docker -- Git -- Libvirt (virt-install, virsh) - -### Build -```bash -# Clone the repository -git clone https://git.knownelement.com/KNEL/football.git -cd football - -# Build the ISO -./src/run.sh build -``` - -### Test -```bash -# Run all tests -./src/run.sh test - -# Run linting checks -./src/run.sh lint -``` - -### Clean -```bash -# Clean build artifacts -./src/run.sh clean -``` - -## Project Structure - -``` -knel-football/ -├── README.md # This file -├── LICENSE # AGPLv3 license -├── AGENTS.md # AI agent documentation -├── football-spec.md # Technical specification -├── run.sh # Host wrapper script -├── ./config/Dockerfile # Build/test container -├── .gitignore # Git ignore rules -├── config/ # live-build configuration -│ ├── preseed.cfg # Installation automation -│ ├── package-lists/ # Software packages -│ ├── hooks/ # Build hooks -│ │ ├── live/ # Live system hooks -│ │ └── installed/ # Post-installation hooks -│ └── includes/ # File inclusions -├── src/ # Build scripts -│ ├── build-iso.sh # Main ISO build -│ ├── security-hardening.sh # Security configurations -│ ├── firewall-setup.sh # Dynamic firewall -│ └── compliance-check.sh # Validation -├── tests/ # Test suite -│ ├── unit/ # Unit tests -│ ├── integration/ # Integration tests -│ ├── security/ # Security tests -│ └── fixtures/ # Test data -├── docs/ # Documentation -│ ├── architecture.md # System architecture -│ ├── security-model.md # Security model -│ └── user-guide.md # User documentation -└── output/ # Generated ISO files -``` - -## Security Features - -### Kernel Module Blacklisting -- WiFi modules: cfg80211, mac80211, brcmfmac, iwlwifi, ath9k, rt73usb -- Bluetooth modules: btusb, bluetooth, btrtl, btintel, btbcm - -### Firewall Configuration -- Default deny policy -- Dynamic WireGuard endpoint parsing -- UDP traffic only to WireGuard server -- nftables implementation - -### Package Management Security -- Execute permissions removed -- Immutable with `chattr +i` -- APT/DPKG metadata cleared -- No package updates possible - -### Boot Security -- UEFI-only boot mode -- Secure Boot enabled -- Measured boot implementation -- Custom keys included - -## Compliance - -- **CMMC Level 3** - Entry point to tier0 infrastructure -- **FedRAMP LI-SaaS** - Ready for federal government deployment -- **DISA STIG** - Adapted Debian 11 STIG for Debian 13 -- **CIS Benchmarks** - Industry best practices for Debian Linux - -## User Workflow - -### Installation -1. Boot from ISO -2. Complete manual partitioning -3. Set root password -4. Create non-root user (auto-added to sudo) - -### Configuration -1. Mount USB drive with WireGuard config -2. Use desktop shortcuts to import/apply configuration -3. QR code scanning available for mobile configuration - -### Remote Access -1. Remmina for RDP connections -2. WireGuard tunnel for all network traffic -3. No direct internet access possible - -## Development - -### Test-Driven Development -- Tests written before implementation -- 100% code coverage mandatory -- BATS framework for testing -- Shellcheck for linting - -### Build Environment -- Docker-based container -- No build tools on host -- All dependencies in container -- Proper file permissions - -## Contributing - -This project is developed under the GNU Affero General Public License v3.0. Contributions must follow the same license and include proper attribution. - -## License - -Copyright © 2026 Known Element Enterprises LLC - -This program is free software: you can redistribute it and/or modify it under the terms of the GNU Affero General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version. - -This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details. - -You should have received a copy of the GNU Affero General Public License along with this program. If not, see . - -## Contact - -**Known Element Enterprises LLC** -- Website: https://knownelement.com -- Repository: https://git.knownelement.com/KNEL/football +### 🔧 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 | --- -
- Security through Compliance. Compliance through Process. -
\ No newline at end of file +## Current Status (2026-01-24 19:00 CST) + +### ISO Build Running +- **Status**: Active build (3rd attempt, minimal config) +- **Current Stage**: `lb binary_chroot` (creating binary filesystem) +- **Started**: 18:04 CST +- **Expected Completion**: 19:00-19:15 CST (~15 min remaining) +- **Build Log**: `/tmp/knel-iso-build.log` +- **Output**: `output/` (ISO will appear here when complete) + +### First Actions +```bash +cd /home/tsys/Projects/KNEL/football + +# 1. Check if ISO is ready +ls -lh output/ + +# 2. If ready, verify +cd output/ +sha256sum -c knel-football-secure-v1.0.0.iso.sha256 + +# 3. If not ready, monitor +tail -f /tmp/knel-iso-build.log +``` + +--- + +## Quick Commands + +### Project Management +```bash +./run.sh build # Build Docker image +./run.sh test # Run tests +./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 +```bash +# Monitor ISO build +tail -f /tmp/knel-iso-build.log + +# Check build status +tail -50 /tmp/knel-iso-build.log | grep "P:" + +# Check output +ls -lh output/ +``` + +--- + +## 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 + +### 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) +- Network isolation (VPN-only access) +- No wireless networking +- Comprehensive audit logging + +### Compliance +✅ All operations in Docker container +✅ Docker volumes for file I/O +✅ No directories in /home +✅ No host system modifications +✅ Only final artifacts in output/ +✅ File ownership preserved + +--- + +## Documentation + +### AGENTS.md (READ FIRST) +- Current build status +- Critical requirements +- Docker-only workflow +- Volume structure + +### RESUME.md (Detailes Guide) +- Build progress timeline +- Issues encountered and solutions +- Working configuration +- Restart instructions +- Compliance verification + +### QUICK_START.md (Quick Reference) +- First actions +- Quick commands +- Key files reference +- Expected output + +### JOURNAL.md (Development Log) +- Append-only journal +- Daily work notes +- Lessons learned +- Technical decisions + +--- + +## Session Summary + +**Date**: 2026-01-24 +**Duration**: 8 hours (11:00-19:00 CST) +**Goal**: Build ISO with Docker-only workflow +**Status**: Build running (expected completion ~15 min) +**Attempts**: 7 +**Working Strategy**: Minimal configuration (all problematic flags removed) + +**Next Actions**: +1. Check `output/` for ISO +2. Verify ISO with checksums +3. Test ISO with libvirt/virsh +4. Validate security features + +--- + +**📍 START HERE**: AGENTS.md → Current status + requirements +**📖 DETAILS**: RESUME.md → Complete resumption guide +**⚡ QUICK**: QUICK_START.md → Quick commands + +**ISO Build Running** - Expected completion: 19:00-19:15 CST +