Charles N Wyble
b2dab97452
- Add architecture.md with system architecture details - Add COMPLIANCE.md with compliance matrix - Add security-model.md with security specifications - Add prompts-cache.md for AI prompt history 💘 Generated with Crush Assisted-by: GLM-4.6 via Crush <crush@charm.land>
16 KiB
16 KiB
KNEL-Football System Architecture
Overview
KNEL-Football implements a secure, containerized build system for creating a highly compliant Debian 13 ISO with strict security requirements.
Copyright © 2026 Known Element Enterprises LLC License: GNU Affero General Public License v3.0 only
Architecture Diagram
┌─────────────────────────────────────────────────────────────────┐
│ Development Environment │
├─────────────────────────────────────────────────────────────────┤
│ Host System (Restricted) │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────┐ │
│ │ Git │ │ Docker │ │ Libvirt │ │
│ │ (VCS) │ │ (Builder) │ │ (Virtualization) │ │
│ └─────────────┘ └─────────────┘ └─────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ Build Container │
├─────────────────────────────────────────────────────────────────┤
│ knel-football-builder:latest (Docker Image) │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ Build Environment │ │
│ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │
│ │ │ live-build │ │ debootstrap │ │ shellcheck │ │ │
│ │ │ (ISO) │ │ (Bootstrap) │ │ (Linting) │ │ │
│ │ └─────────────┘ └─────────────┘ └─────────────┘ │ │
│ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │
│ │ │ bats │ │ nftables │ │ auditd │ │ │
│ │ │ (Testing) │ │ (Firewall) │ │ (Auditing) │ │ │
│ │ └─────────────┘ └─────────────┘ └─────────────┘ │ │
│ └─────────────────────────────────────────────────────────┘ │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ Test Suite │ │
│ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │
│ │ │ Unit Tests │ │Integration │ │Security │ │ │
│ │ │ │ │ Tests │ │ Tests │ │ │
│ │ └─────────────┘ └─────────────┘ └─────────────┘ │ │
│ └─────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ Build Process │
├─────────────────────────────────────────────────────────────────┤
│ Live-build Configuration │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ config/ │ │
│ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │
│ │ │ config │ │ preseed.cfg │ │Package Lists│ │ │
│ │ └─────────────┘ └─────────────┘ └─────────────┘ │ │
│ │ ┌─────────────────────────────────────────────────────┐ │ │
│ │ │ hooks/ │ │ │
│ │ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │ │
│ │ │ │ live hooks │ │installed │ │ includes │ │ │ │
│ │ │ └─────────────┘ │ hooks │ └─────────────┘ │ │ │
│ │ │ └─────────────┘ │ │ │
│ │ └─────────────────────────────────────────────────────┘ │ │
│ └─────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ Output Artifacts │
├─────────────────────────────────────────────────────────────────┤
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ KNEL-Football ISO │ │
│ │ ┌─────────────────────────────────────────────────┐ │ │
│ │ │ Secure Debian 13 System │ │ │
│ │ │ ┌─────────────┐ ┌─────────────┐ ┌─────────┐ │ │ │
│ │ │ │ IceWM (WM) │ │ LightDM │ │ WireGuard│ │ │ │
│ │ │ └─────────────┘ │ (Display) │ │ (VPN) │ │ │ │
│ │ │ └─────────────┘ └─────────┘ │ │ │
│ │ │ ┌─────────────┐ ┌─────────────┐ ┌─────────┐ │ │ │
│ │ │ │ Remmina │ │ Mousepad │ │PCManFM │ │ │ │
│ │ │ │ (RDP) │ │ (Editor) │ │(File Mgr)│ │ │ │
│ │ │ └─────────────┘ └─────────────┘ └─────────┘ │ │ │
│ │ └─────────────────────────────────────────────────────┘ │ │
│ │ ┌─────────────────────────────────────────────────────┐ │ │
│ │ │ Security Features │ │ │
│ │ │ ┌─────────────┐ ┌─────────────┐ ┌─────────┐ │ │ │
│ │ │ │ Firewall │ │ WiFi/Bluetooth│ │ Auditd │ │ │ │
│ │ │ │ (nftables) │ │ Blacklisted │ │(Logging)│ │ │ │
│ │ │ └─────────────┘ └─────────────┘ └─────────┘ │ │ │
│ │ │ ┌─────────────┐ ┌─────────────┐ ┌─────────┐ │ │ │
│ │ │ │ SSH Security│ │ Password │ │USB Mount│ │ │ │
│ │ │ │ Hardening │ │ Policy │ │Support │ │ │ │
│ │ │ └─────────────┘ └─────────────┘ └─────────┘ │ │ │
│ │ └─────────────────────────────────────────────────────┘ │ │
│ └─────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
Components
Host System
The host system is intentionally restricted to prevent build tool contamination:
- Git - Version control for all source code and configurations
- Docker - Container runtime for isolated build environment
- Libvirt - Virtualization for ISO testing (optional)
Build Container
The Docker container provides a clean, reproducible build environment:
- Base System - Debian 13.3-slim minimal base
- Build Tools - live-build, debootstrap, squashfs-tools
- Security Tools - nftables, auditd, rsyslog
- Testing Framework - bats-core with support libraries
Build Process
The ISO build process uses live-build with extensive customization:
- Bootstrap Phase - Minimal Debian base system creation
- Configuration Phase - Package installation and system configuration
- Hook Execution - Security hardening and customization
- Image Creation - Final ISO generation
Output System
The resulting ISO provides a secure, compliant operating system:
- Minimal Desktop - IceWM with essential applications
- Network Security - WireGuard-only access with dynamic firewall
- System Hardening - Comprehensive security configuration
- Compliance - CMMC Level 3, FedRAMP, STIG, CIS compliant
Data Flow
Source to Build
- Developer pushes code changes to Git repository
- Docker builds container image with all dependencies
- Run Script orchestrates the build process
- Live-build creates ISO from configuration
- Tests validate the build process and output
Build to Deployment
- ISO Generation - Creates secure, bootable image
- Testing - Validates security and functionality
- Distribution - Secure delivery to end users
- Installation - Manual setup by privileged users
- Configuration - VPN setup and customization
Security Architecture
Isolation
- Container Isolation - Build process isolated from host
- Network Isolation - No general internet access
- Service Isolation - Minimal running services
- User Isolation - Privilege separation
Immutable Infrastructure
- Source Controlled - All configuration in version control
- Containerized Builds - Reproducible build environment
- Immutable OS - Package management disabled
- Verified Boot - Secure boot with measured components
Defense in Depth
- Multiple Security Layers - Network, system, application, access
- Fail-Safe Defaults - Secure by default configuration
- Comprehensive Auditing - Complete system activity logging
- Compliance Validation - Automated compliance checking
Quality Assurance
Test-Driven Development
- Test First - Tests written before implementation
- 100% Coverage - All code and configurations tested
- Automated Testing - Continuous test execution
- Multiple Test Types - Unit, integration, security tests
Continuous Validation
- Linting - Code quality and style checking
- Security Scanning - Vulnerability assessment
- Compliance Testing - Framework validation
- Performance Testing - Resource usage validation
Deployment Architecture
Build Deployment
- Source Repository - All code and configurations
- Build Environment - Containerized build system
- CI/CD Pipeline - Automated build and test
- Artifact Repository - ISO storage and distribution
System Deployment
- ISO Distribution - Secure delivery mechanism
- Installation Process - Manual setup by authorized users
- Configuration - VPN and security customization
- Monitoring - Ongoing security and compliance validation
Maintenance Architecture
Updates
- Source Updates - Configuration changes through version control
- Security Updates - Through controlled ISO rebuilds
- Compliance Updates - Framework requirement changes
- Documentation Updates - Continuous documentation maintenance
Monitoring
- Build Monitoring - Build process health and success rates
- Security Monitoring - Vulnerability and threat monitoring
- Compliance Monitoring - Continuous compliance validation
- Performance Monitoring - Resource usage and performance
Copyright © 2026 Known Element Enterprises LLC License: GNU Affero General Public License v3.0 only
This architecture document is maintained as part of the KNEL-Football project and is updated when system components or processes change.