KNEL/football
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
football/README.md
Charles N Wyble 9b3e282d20 feat: add shared git hooks with setup script 
Git hooks were only in .git/hooks/ which isn't tracked by git.
Created a shared githooks/ directory so all contributors get
the pre-commit hook that enforces SDLC requirements.

Changes:
- githooks/pre-commit: Pre-commit hook enforcing SDLC (lint, tests, docs)
- scripts/setup-githooks.sh: Script to configure git core.hooksPath
- README.md: Added first-time setup instructions
- AGENTS.md: Updated startup steps and project structure

Users/agents run ./scripts/setup-githooks.sh after cloning to enable hooks.

Reference: docs/SDLC.md

💘 Generated with Crush

Assisted-by: GLM-5 via Crush <crush@charm.land>
2026-02-20 12:11:28 -05:00

385 lines
15 KiB
Markdown
Raw Permalink Blame History

# KNEL-Football Secure OS
## ⚠️ READ THESE FILES FIRST
### 🚀 Quick Start
1. **[AGENTS.md](AGENTS.md)** - Current status + critical requirements (START HERE)
2. **[docs/PRD.md](docs/PRD.md)** - Product Requirements Document
3. **[README.md](README.md)** - This file (project overview)
### 📋 Documentation Files
| File | Purpose |
|------|---------|
| **[STATUS.md](STATUS.md)** | 📊 Project status report (manager quick-glance) |
| **[JOURNAL.md](JOURNAL.md)** | 📝 AI memory, ADRs, lessons learned (append-only) |
| **[AGENTS.md](AGENTS.md)** | ⚡ START HERE - Current status + requirements |
| **[docs/PRD.md](docs/PRD.md)** | Complete product requirements |
| **[docs/SDLC.md](docs/SDLC.md)** | Software Development Lifecycle |
| **[docs/TEST-COVERAGE.md](docs/TEST-COVERAGE.md)** | Test suite details and coverage |
| **[docs/VERIFICATION-REPORT.md](docs/VERIFICATION-REPORT.md)** | Security compliance verification |
### 🔧 Project Files
| File | Purpose |
|------|---------|
| [`run.sh`](run.sh) | Main entry point (build/test/lint/clean/iso) |
| [`Dockerfile`](Dockerfile) | Build environment |
| [`config/`](config/) | Live-build configuration |
| [`tests/`](tests/) | BATS test suite |
| [`docs/`](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](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](config/includes.installer/preseed.cfg) | [preseed.cfg](config/includes.installer/preseed.cfg), [package-lists](config/package-lists/) | ✅ config tests |
| [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](src/firewall-setup.sh) | [firewall-setup.sh](src/firewall-setup.sh) | ✅ 7 test files |
| [FR-005: Hardware Control](src/security-hardening.sh) | [security-hardening.sh](src/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](src/security-hardening.sh) | [security-hardening.sh](src/security-hardening.sh) | ✅ 9 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](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](src/build-iso.sh) | [build-iso.sh](src/build-iso.sh), [Dockerfile](Dockerfile) | ✅ 8 test files |
| [FR-011: Host FDE](run.sh) | [run.sh](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/
```
### First-Time Setup (After Cloning)
```bash
# Configure git hooks (required for SDLC enforcement)
./scripts/setup-githooks.sh
```
### 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 13 (trixie) stable 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
**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)
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](AGENTS.md) (START HERE)
- [docs/PRD.md](docs/PRD.md) (Requirements)
- [docs/SDLC.md](docs/SDLC.md) (Development Workflow)
- [docs/TEST-COVERAGE.md](docs/TEST-COVERAGE.md) (Tests)
- [docs/VERIFICATION-REPORT.md](docs/VERIFICATION-REPORT.md) (Compliance)
Reference in New Issue View Git Blame Copy Permalink