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>
231 lines
16 KiB
Markdown
231 lines
16 KiB
Markdown
# 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:
|
|
|
|
1. **Bootstrap Phase** - Minimal Debian base system creation
|
|
2. **Configuration Phase** - Package installation and system configuration
|
|
3. **Hook Execution** - Security hardening and customization
|
|
4. **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
|
|
|
|
1. **Developer** pushes code changes to Git repository
|
|
2. **Docker** builds container image with all dependencies
|
|
3. **Run Script** orchestrates the build process
|
|
4. **Live-build** creates ISO from configuration
|
|
5. **Tests** validate the build process and output
|
|
|
|
### Build to Deployment
|
|
|
|
1. **ISO Generation** - Creates secure, bootable image
|
|
2. **Testing** - Validates security and functionality
|
|
3. **Distribution** - Secure delivery to end users
|
|
4. **Installation** - Manual setup by privileged users
|
|
5. **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
|
|
|
|
1. **Test First** - Tests written before implementation
|
|
2. **100% Coverage** - All code and configurations tested
|
|
3. **Automated Testing** - Continuous test execution
|
|
4. **Multiple Test Types** - Unit, integration, security tests
|
|
|
|
### Continuous Validation
|
|
|
|
1. **Linting** - Code quality and style checking
|
|
2. **Security Scanning** - Vulnerability assessment
|
|
3. **Compliance Testing** - Framework validation
|
|
4. **Performance Testing** - Resource usage validation
|
|
|
|
## Deployment Architecture
|
|
|
|
### Build Deployment
|
|
|
|
1. **Source Repository** - All code and configurations
|
|
2. **Build Environment** - Containerized build system
|
|
3. **CI/CD Pipeline** - Automated build and test
|
|
4. **Artifact Repository** - ISO storage and distribution
|
|
|
|
### System Deployment
|
|
|
|
1. **ISO Distribution** - Secure delivery mechanism
|
|
2. **Installation Process** - Manual setup by authorized users
|
|
3. **Configuration** - VPN and security customization
|
|
4. **Monitoring** - Ongoing security and compliance validation
|
|
|
|
## Maintenance Architecture
|
|
|
|
### Updates
|
|
|
|
1. **Source Updates** - Configuration changes through version control
|
|
2. **Security Updates** - Through controlled ISO rebuilds
|
|
3. **Compliance Updates** - Framework requirement changes
|
|
4. **Documentation Updates** - Continuous documentation maintenance
|
|
|
|
### Monitoring
|
|
|
|
1. **Build Monitoring** - Build process health and success rates
|
|
2. **Security Monitoring** - Vulnerability and threat monitoring
|
|
3. **Compliance Monitoring** - Continuous compliance validation
|
|
4. **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. |