# 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.